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.

Table 1. Error code structure for receiving error conditions as exceptions
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.

Table 2. Error code structure for receiving the error code without the exception data
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.

Table 3. Error code structure for receiving the error code with the exception data
Field INPUT OUTPUT
Bytes provided 116 116
Bytes available Ignored 36
Exception ID Ignored CPF7B03
Reserved Ignored 0
Exception data Ignored USRMSG    QGPL