Capturing InterBase Error Messages (Embedded SQL Guide)
Go Up to Additional InterBase Error Handling
The text of InterBase error messages can be captured in a buffer by using isc_interprete(). Capture messages in a buffer when applications:
- Run under windowing systems that do not permit direct writing to the screen.
- Store a record of all error messages in a log file.
- Manipulate or format error messages for display.
isc_interprete() should not be used unless SQLCODE is less than –1 because the contents of isc_status may not contain reliable error information in these cases.Given both the location of a storage buffer previously allocated by the program, and a pointer to the start of the status array, isc_interprete() builds an error message string from the information in the status array, and puts the formatted string in the buffer where it can be manipulated. It also advances the status array pointer to the start of the next cluster of available error information.
isc_interprete() retrieves and formats a single error message each time it is called. When an error occurs in an InterBase program, however, the status array may contain more than one error message. To retrieve all relevant error messages, error-handling routines should repeatedly call isc_interprete() until it returns no more messages.
Because isc_interprete() modifies the pointer to the status array that it receives, do not pass isc_status directly to it. Instead, declare a pointer to isc_status, then pass the pointer to isc_interprete().
The following C code fragment illustrates how InterBase error messages can be captured to a log file, and demonstrates the proper declaration of a string buffer and pointer to isc_status. It assumes the log file is properly declared and opened before control is passed to the error-handling routine. It also demonstrates how to set the pointer to the start of the status array in the error-handling routine before isc_interprete() is first called.
. . .
#include "ibase.h";
. . .
main()
{
char msg[512];
ISC_STATUS *vector;
FILE *efile; /* code fragment assumes pointer to an open file */
. . .
if (SQLCODE < –1)
ErrorExit();
}
. . .
ErrorExit()
{
vector = isc_status; /* (re)set to start of status vector */
isc_interprete(msg, &vector); /* retrieve first mesage */
fprintf(efile, "%s\n", msg); /* write buffer to log file */
msg[0] = '-'; /* append leading hyphen to secondary messages */
while (isc_interprete(msg + 1, &vector)) /* more?*/
fprintf(efile, "%s\n", msg); /* if so, write it to log */
fclose(efile); /* close log prior to quitting program */
EXEC SQL
ROLLBACK;
EXEC SQL
DISCONNECT ALL;
exit(1); /* quit program with an 'abnormal termination' code */
}
. . .
In this example, the error-handling routine performs the following tasks:
- Sets the error array pointer to the starting address of the status vector,
isc_status. - Calls
isc_interprete()a single time to retrieve the first error message from the status vector. - Writes the first message to a log file.
- Makes repeated calls to
isc_interprete()within aWHILEloop to retrieve any additional messages. If additional messages are retrieved, they are also written to the log file. - Rolls back the transaction.
- Closes the database and releases system resources.