Most iSeries™ APIs include an error code parameter to return error codes and exception data to the application. The error code parameter can be one of two variable-length structures, format ERRC0100 or format ERRC0200.
In format ERRC0100, one field in that structure 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 structure of the error code parameter is as follows. The fields are described in detail after the tables.
| 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 |
| 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 | ||
This topic describes the fields returned in further detail. Field descriptions are in alphabetical order.
Bytes available. The length of the error information available to the API to return, in bytes. If this 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.
| 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 only occurs if format ERRC0100 is used. |
| >=12 | If an error occurs, the space is filled in with the exception information. No exception is returned. This only occurs if format ERRC0200 is used. |
CCSID of the CCHAR data. The coded character set identifier (CCSID) of the convertible character (CCHAR) portion of the exception data. The default is 0.
| 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.