See Code disclaimer information for information pertaining to code examples.
Error handling with ILE APIs can be accomplished in two ways: use the error code parameter or have exceptions signaled by the API to your application program.
For information and the examples, see the following:
The error code parameter enables a user to have exceptions returned to the program through the use of the parameter instead of having the exceptions signaled. Some exceptions may be signaled to the caller regardless of the size of the error code parameter. These exceptions are usually from errors that occur with the error code parameter itself (that is, message CPF3CF1) or with one of the other parameters (that is, message CPF9872). In the latter case, message CPF9872 is always signaled and never returned through the error code parameter because the API is unable to verify the error code parameter before the exception occurs.
The caller of the API must initialize the error code parameter so that the bytes provided field is set to the size, in bytes, of the error code parameter. For example, the error_code_struct structure in the Example: Variable-length structure sets the size at 116 bytes. To initialize the error code parameter, do the following:
error_code_struct error_code;
error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);
If the bytes provided field is set to a value equal to or greater than 8, the caller wants all exceptions returned through the error code parameter. The API fills in all of the message information up to the size of the error code parameter.
On the return from the call to the API, verify whether or not an error occurred. If an error occurred, the bytes available field is set to something other than zero. If the bytes available field is not zero, you can use the message ID and the message data to determine what the program should do next. To receive the message ID and data, you must provide enough storage on the error code parameter for the information.
In the following example, the bytes available field is checked to determine if an error occurred. In this case, if an error occurred, a message is printed, which states the message ID and that the call to the API failed.
if (error_code.ec_fields.Bytes_Available != 0)
{
printf("ATTEMPT TO REGISTER EXIT POINT FAILED WITH EXCEPTION: %.7s",
error_code.ec_fields.Exception_Id);
exit(1);
}
If your program needs to handle different exceptions in different ways, you may need to make use of both the message data and the message ID. The message data is returned in the same format as when you display the message description on the system. For example, if message CPF3C1E is received, some of the message data is printed. You can see message data that is associated with the message by using the Display Message Description (DSPMSGD) command. The message data for message CPF3C1E is defined as:
Parameter number
ILE entry point name
To receive all of the message data for this exception, the exception data field of the error code structure would need to be at least 260 bytes in size. The following example uses only the number of bytes shown for the parameter number of the exception in the message data; therefore, the exception data field only needs to be 4 bytes.
int parm_number;
char *temp_ptr;
if (error_code.ec_fields.Bytes_Available != 0)
{
if (memcmp(error_code.ec_fields.Exception_Id,"CPF3C1E",7)==0)
{
printf("\nFAILED WITH CPF3C1E:");
temp_ptr=&(error_code.exception_data);
parm_number=*((int *)temp_ptr);
printf("\n Parameter number omitted: %d",parm_number);
}
else
{
printf("ATTEMPT TO REGISTER EXIT POINT FAILED WITH EXCEPTION: %.7s",
error_code.ec_fields.Exception_Id);
exit(1);
}
}
The second means of exception handling is by having all exceptions signaled by the API to the calling program. To have all exceptions signaled by the API, set the bytes provided field of the error code structure to zero. Refer to the documentation of your specific programming language for information on exception handling.
