Setting a SQLCode Value on Error

From InterBase
Jump to: navigation, search

For DSQL applications, error conditions should be cast in terms of SQL conventions. SQL applications typically report errors through a variable, SQLCODE, declared by an application. To translate an InterBase error code into SQLCODE format, use isc_sqlcode(). This function searches the error status vector for an InterBase error code that can be translated into a SQL error code, and performs the translation. Once SQLCODE is set, the other API functions for handling SQL errors, isc_print_sqlerror(), and isc_sql_interprete(), can be called.

isc_sqlcode() requires one parameter, a pointer to the status vector. It returns a long value, containing a SQL error code. The following code illustrates the use of this function:

#include <ibase.h>
. . .
long SQLCODE; /* Declare the SQL error code variable. */
ISC_STATUS status_vector[20];
. . .
if (status_vector[0] == 1 && status_vector[1] > 0) {
SQLCODE = isc_sqlcode(status_vector);
isc_print_sqlerror(SQLCODE, status_vector)
. . .
}

If successful, isc_sqlcode() returns the first valid SQL error code decoded from the status vector. If no valid SQL error code is found, isc_sqlcode() returns –999.

Displaying SQL Error Messages

API applications that provide a DSQL interface to end users should use isc_print_sqlerror() to display SQL error codes and corresponding error messages on the screen. When passed a variable, conventionally named SQLCODE, containing a SQL error code, and a pointer to the status vector, isc_print_sqlerror()parses the status vector to build a SQL error message, then uses the C printf()function to write the SQLCODE value and message to the display. For example, the following code fragment calls isc_print_sqlerror() and rolls back a transaction on error:

#include <ibase.h>
. . .
ISC_STATUS status_vector[20];
isc_tr_handle trans;
long SQLCODE;
. . .
trans = 0L;
. . .
/* Assume a transaction, trans, is started here. */
/* Assume an API call returning status information is called here. */
if (status_vector[0] == 1 && status_vector[1] > 0) {
SQLCODE = isc_sqlcode(status_vector);
isc_print_sqlerror(SQLCODE, status_vector);
isc_rollback_transaction(status_vector, &trans);
}

Important: On windowing systems that do not permit direct screen writes with printf(), use isc_sql_interprete() to capture error messages to a buffer.

Capturing SQL Error Messages

Use isc_sql_interprete() to build a SQL error message based on a specific SQL error code and store it in a buffer defined by an application. Capturing messages in a buffer is useful when applications:

  • Run under windowing systems that do not permit direct screen writes.
  • 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_sql_interprete() requires three parameters: a valid SQL error code, usually passed as a variable named SQLCODE, a buffer where the SQL message should be stored, and the size of the buffer. The following code illustrates how this function might be called to build a message string and store it in a log file:

#include <ibase.h>
. . .
ISC_STATUS status_vector[20];
isc_tr_handle trans;
long SQLCODE;
char msg[512];
FILE *efile; /* Code fragment assumes pointer to an open file. */
trans = 0L;
. . .
/* Assume a transaction, trans, is started here. */
/* Assume an API call returning status information is called here. */
. . .
/* Error-handling routine starts here. */
if (status_vector[0] == 1 && status_vector[1] > 0) {
SQLCODE = isc_sqlcode(status_vector);
isc_sql_interprete(SQLCODE, msg, 512);
fprintf(efile, "%s\n", msg);
isc_rollback_transaction(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.

Advance to Next Section

Retrieved from "https://docwiki.embarcadero.com/InterBase/XE3/e/index.php?title=Setting_a_SQLCode_Value_on_Error&oldid=5486"