How do I decode an APDFL error message?

Exception codes and error messages for the Adobe PDF Library are listed in the AcroErr.h header file. You will find this in the product installation package, in the directory called /CPlusPlus/Include/Headers.

The Adobe PDF Library creates error messages using a macro defined in AcroErr.h (lines 291-316). The product provides each error code as a series of bit field values, concatenated together into a single larger number.

Interpreting error messages with the ASGetErrorString API

The Adobe PDF Library offers an API, ASGetErrorString, that translates error codes into error messages that are easy to read and prints them to a command line monitor.

const char *ASGetErrorString(ASErrorCode errorCode, char *buffer, ASTArraySize lenBuffer);

ASGetErrorString() has three parameters:

• errorCode. The error number that you want to translate into an error message text string. You must pass to the function the full error code number created with the ErrBuildCode() macro, or a user-defined exception returned with ASRegisterErrorString().
• buffer. The buffer where ASGetErrorString will write the text string ( char buffer[256]; ). Make sure that you memset this buffer to 0 before you call ASGetErrorString.
• lenBuffer. The number of characters that the buffer can hold. You can pass ASGetErrorString() sizeof(buffer) here.

ASGetErrorString() returns a pointer to buffer, but this pointer does not by itself indicate that the function worked.  If the buffer was memset to 0, call strlen on the returned buffer to determine if the error code was valid.

For example, the following code will convert an error code into an error message string, and print that string to stderr:

  char buf[256];
  ...
  DURING
  ...
  HANDLER
  ASGetErrorString(ERRORCODE, buf, sizeof(buf));
  fprintf(stderr, "Error code: %ld, Error Message: %sn", ERRORCODE, buf);
  return;
  END_HANDLER

The use of the ASGetErrorString API is demonstrated in the sample program APDFLDoc.cpp. Find this sample program in your Adobe PDF Library software installation package:

/CPlusPlus/Sample_Source/_Common

The samples found in this directory are called by other Library sample programs.

Translating the Adobe PDF Library error code manually

The Adobe PDF Library provides each error code as a series of bit field values, concatenated together into a single larger number. You can interpret the message by converting the decimal value that results into hexadecimal.  The hexadecimal number is always eight digits long.

Remember that each hexadecimal number is a single digit that represents one of 16 values, between 0 and 15.  Hexadecimal digits are 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F.

It is easier to read if you use a  decimal to hexadecimal code converter  utility to convert the error code to hex notation, and then parse the hex version of the error code. 

You can also use the Windows 10 calculator app.  

Open the calculator and click the   icon in the upper left corner.

Click Programmer.

Type in a value for Dec to convert it to Hex. Try typing 1073938471:

Note that if you have an error code that is eight digits, it might be hexadecimal already. 

What do these error numbers mean?

Consider this example.  The error code 1073938471 can be converted to hex code 40030027, as shown in the Windows Calculator screens above. You can then parse that hex code into four fields:

Error code examples