Capturing InterBase Error Messages

From InterBase

Go Up to Using Information in the Status Vector


Use isc_interprete() to build an error message from information in the status vector and store it in an application-defined buffer where it can be further manipulated. Capturing messages in a buffer is useful when applications:

  • Run under windowing systems that do not permit direct screen writes.
  • Require more control over message display than is possible with isc_print_status().
  • Store a record of all error messages in a log file.
  • Manipulate or format error messages for display or pass them to a windowing system’s display routines.

isc_interprete() retrieves and formats a single error message each time it is called. When an error occurs, the status vector usually contains more than one error message. To retrieve all relevant error messages, you must make repeated calls to isc_interprete().

Given both the location of a buffer, and the address of the status vector, isc_interprete() builds an error message from the information in the status vector, puts the formatted string in the buffer where an application can manipulate it, and advances the status vector pointer to the start of the next cluster of error information. isc_interprete() requires two parameters, the address of an application buffer to hold formatted message output, and a pointer to the status vector array.

Important:
Never pass the status vector array directly to isc_interprete(). Each time it is called, isc_interprete() advances the pointer to the status vector to the next element containing new message information. Before calling isc_interprete(), be sure to set the pointer to the starting address of the status vector.

The following code demonstrates an error-handling routine that makes repeated calls to isc_interprete() to retrieve error messages from the status vector in a buffer, one at a time, so they can be written to a log file:

#include <ibase.h>
. . .
ISC_STATUS status_vector[20];
isc_tr_handle trans;
long *pvector;
char msg[512];
FILE *efile; /* Code fragment assumes pointer to an open file. */
trans = 0L;
. . .
/* Error-handling routine starts here. */
/* Always set pvector to point to start of status_vector. */
pvector = status_vector;
/* Retrieve first message. */
isc_interprete(msg, &pvector);
/* Write first message from buffer to log file. */
fprintf(efile, "%s\n", msg);
msg[0] = '-'; /* Append leading hyphen to secondary messages. */
/* Look for more messages and handle in a loop. */
while(isc_interprete(msg + 1, &pvector)) /* More? */
fprintf(efile, "%s\n", msg); /* If so, write it to the log. */
fclose(efile); /* All done, so close the log file. */
isc_rollback(status_vector, &trans);
return(1);
. . .
Note:
This code fragment assumes that the log file is properly declared and opened elsewhere in the application before control is passed to this error handler.
Tip:
For applications that use the dynamic SQL (DSQL) API functions, errors should be buffered using SQL conventions. Use isc_sqlcode() and ­isc_sql_interprete() instead of isc_interprete().

Advance To: