Examples: Receiving error conditions
Depending on how you set the error code parameter, your application can receive error conditions as exceptions or receive the error code with or without exception data.
Example: Receiving error conditions as exceptions
This example defines an error code structure that receives error conditions as exceptions using format ERRC0100 of the error code structure. The application allocates an error code parameter that is a minimum of 4 bytes long to hold the bytes provided field. The only field used is the bytes provided INPUT field, which the application sets to zero to request exceptions. The error code parameter contains the following field.
Field | INPUT | OUTPUT |
---|---|---|
Bytes provided | 0 | 0 |
Example: Receiving the error code without the exception data
This example defines a format ERRC0100 error code structure that receives the error message or exception ID but no exception replacement data. To do this, the application allocates an error code parameter that is a minimum of 16 bytes long for the bytes provided, bytes available, exception ID, and reserved fields. It sets the bytes provided field of the error code parameter to 16.
If the called API were to return the error message CPF7B03, the error code parameter would contain the data shown in the following table. In this example, 16 bytes are provided for data, but 36 bytes are available. Twenty more bytes of data could be returned if the bytes provided field were set to reflect a larger error code parameter.
Field | INPUT | OUTPUT |
---|---|---|
Bytes provided | 16 | 16 |
Bytes available | Ignored | 36 |
Exception ID | Ignored | CPF7B03 |
Reserved | Ignored | 0 |
Example: Receiving the error code with the exception data
This example defines a format ERRC0100 error code structure that receives the error message or exception ID and up to 100 bytes of exception replacement data that is associated with the exception. To do this, the application allocates an error code parameter that is 116 bytes long: 16 bytes for the bytes provided, bytes available, exception ID, and reserved fields, and 100 bytes for the exception data for the exception. (In some cases, the exception data might be a variable-length directory or file name, so this might not be large enough to hold all of the data; whatever fits is returned in the error code parameter.) Finally, it sets the bytes provided field to 116.
If the called API were to return the error message CPF7B03 with replacement variable &1 set to the value 'USRMSG ' and replacement variable &2 set to the value 'QGPL ', the error code parameter would contain the data shown in the following table.
Field | INPUT | OUTPUT |
---|---|---|
Bytes provided | 116 | 116 |
Bytes available | Ignored | 36 |
Exception ID | Ignored | CPF7B03 |
Reserved | Ignored | 0 |
Exception data | Ignored | USRMSG QGPL |