Error code parameter format

Most IBM i APIs include an error code parameter to return error codes and exception data to the application.

The error code parameter can be one of these variable-length structures: format ERRC0100 or format ERRC0200.

In format ERRC0100, one field is an INPUT field; it controls whether an exception is returned to the application or the error code structure is filled in with the exception information. When the bytes provided field is greater than or equal to 8, the rest of the error code structure is filled in with the OUTPUT exception information associated with the error. When the bytes provided INPUT field is zero, all other fields are ignored and an exception is returned.

Format ERRC0200 must be used if the API caller wants convertible character (CCHAR) support. Format ERRC0200 contains two INPUT fields. The first field, called the key field, must contain a -1 to use CCHAR support. When the bytes provided field is greater than or equal to 12, the rest of the error code structure is filled in with the OUTPUT exception information associated with the error. When the bytes provided INPUT field is zero, all other fields are ignored and an exception is returned.

For some APIs, the error code parameter is optional. If you do not code the optional error code parameter, the API returns diagnostic and escape messages. If you do code the optional error code parameter, the API returns only escape messages or error codes; it never returns diagnostic messages.

The following tables show the structures of the error code parameter. The fields are described in detail after the tables.
Note: The error code structures for both formats are provided in the QUSEC include file in the QSYSINC library. Include files exist in these source physical files: QRPGSRC, QRPGLESRC, QLBLSRC, QCBLLESRC, and H.

Format ERRC0100

Table 1. Format ERRC0100 for the error code parameter
Offset Use Type Field
Dec Hex
0 0 INPUT BINARY(4) Bytes provided
4 4 OUTPUT BINARY(4) Bytes available
8 8 OUTPUT CHAR(7) Exception ID
15 F OUTPUT CHAR(1) Reserved
16 10 OUTPUT CHAR(*) Exception data

Format ERRC0200

Table 2. Format ERRC0200 for the error code parameter
Offset Use Type Field
Dec Hex
0 0 INPUT BINARY(4) Key
4 4 INPUT BINARY(4) Bytes provided
8 8 OUTPUT BINARY(4) Bytes available
12 C OUTPUT CHAR(7) Exception ID
19 13 OUTPUT CHAR(1) Reserved
20 14 OUTPUT BINARY(4) CCSID of the CCHAR data
24 18 OUTPUT BINARY(4) Offset to the exception data
28 1C OUTPUT BINARY(4) Length of the exception data
    OUTPUT CHAR(*) Exception data

Field descriptions

Fields in the error code structures are described in alphabetic order.

Bytes available. The length of the error information available for the API to return, in bytes. If it is 0, no error was detected and none of the fields that follow this field in the structure are changed.

Bytes provided. The number of bytes that the calling application provides for the error code. If the API caller is using format ERRC0100, the bytes provided must be 0, 8, or more than 8. If more than 32 783 bytes (32KB for exception data plus 16 bytes for other fields) are specified, it is not an error, but only 32 767 bytes (32KB) can be returned in the exception data.

If the API caller is using format ERRC0200, the bytes provided must be 0, 12, or more than 12. If more than 32 799 bytes (32KB for exception data plus 32 bytes for other fields) are specified, it is not an error, but only 32 767 bytes (32KB) can be returned in the exception data.

Table 3. Possible values for bytes provided
Bytes Description
0 If an error occurs, an exception is returned to the application to indicate that the requested function failed.
>=8 If an error occurs, the space is filled in with the exception information. No exception is returned. This occurs only for format ERRC0100.
>=12 If an error occurs, the space is filled in with the exception information. No exception is returned. This occurs for formats ERRC0100 and ERRC0200.

CCSID of the CCHAR data. The coded character set identifier (CCSID) of the convertible character (CCHAR) portion of the exception data.

Table 4. Possible values for CCSID of the CCHAR data
CCSID Description
0 The default job CCSID.
CCSID A valid CCSID number. The valid CCSID range is 1 through 65535, but not 65534.

Exception data. A variable-length character field that contains the insert data associated with the exception ID.

Exception ID. The identifier for the message for the error condition.

Key. The key value that enables the message handler error function if CCHAR support is used. This value should be -1 if CCHAR support is expected.

Length of the exception data. The length, in bytes, of the exception data returned in the error code.

Offset to the exception data. The offset from the beginning of the error code structure to the exception data in the error code structure.

Reserved. A 1-byte reserved field.