isc_interprete()
Go Up to API Function Reference
Extracts the text for an InterBase error message from the error status vector to a user-defined buffer.
Syntax
ISC_STATUS isc_interprete(
char *buffer,
ISC_STATUS **status_vector);
| Parameter | Type | Description |
|---|---|---|
|
|
|
Application buffer for storing an InterBase error message |
|
|
|
Pointer to a pointer to the error status vector |
Description
Given both the location of a storage buffer allocated in a program, and the address of the status vector, isc_interprete() builds an error message string from the information in the status vector, puts the formatted string in the buffer where the program can manipulate it, and advances the status vector pointer to the start of the next cluster of error message information. For example, you might declare an error string buffer, call isc_interprete() to retrieve the first error message and insert the message into the buffer, write the buffer to a log file, then peek at the next cluster to see if it contains more error information.
isc_interprete() retrieves and formats a single message each time it is called. When an error occurs, however, the status vector usually contains more than one error message. To retrieve all relevant error messages, you must make repeated calls to isc_interprete() until no more messages are returned.
- Note: Do not pass the address of the status vector directly, because each time
isc_interprete()is called, it modifies the pointer to the status vector to point to the start of the next available message.
To display all error messages on the screen instead of to a buffer, use isc_print_status().
Example
The following code declares a message buffer, a status vector, and a pointer to the vector, then illustrates how repeated calls are made to isc_interprete() to store all messages in the buffer:
#include <ibase.h>
char msg[512];
ISC_STATUS status_vector[20];
long *pvector; /* Pointer to pointer to status vector. */
FILE *efile; /* Code fragment assumes this points to an open file. */
. . .
pvector = status_vector; /* (Re)set to start of status vector. */
isc_interprete(msg, &pvector); /* Retrieve first message. */
fprintf(efile, "%s\n", msg); /* Write buffer to log file. */
msg[0] = '-'; /* Append leading hyphen to secondary messages. */
while(isc_interprete(msg + 1,&pvector)) { /* More messages? */
fprintf(efile, "%s\n", msg); /* If so, write them, too. */
}
fclose(efile);
. . .
Return value
If successful, isc_interprete() returns the length of the error message string it stores in buffer. It also advances the status vector pointer to the start of the next cluster of error message information.
If there are no more messages in the status vector, or if isc_interprete() cannot interpret the next message, it returns 0.