6.1 Error Handling with sqlca

Table of Contents Previous Next


6 Error Handling : 6.1 Error Handling with sqlca

sqlca (SQL communications area) is a global variable used by ecpglib to communicate information from the server to the client application. After executing a SQL statement (for example, an INSERT or SELECT statement) you can inspect the contents of sqlca to determine if the statement has completed successfully or if the statement has failed.
sqlca has the following structure:
EXEC SQL INCLUDE sqlca;
If you include the ecpg directive, you do not need to #include the sqlca.h file in the client application's header declaration.
The Advanced Server sqlca structure contains the following members:
sqlcaid contains the string: "SQLCA".
sqlabc contains the size of the sqlca structure.
The sqlcode member has been deprecated with SQL 92; Advanced Server supports sqlcode for backward compatibility, but you should use the sqlstate member when writing new code.
sqlcode is an integer value; a positive sqlcode value indicates that the client application has encountered a harmless processing condition, while a negative value indicates a warning or error.
If a statement processes without error, sqlcode will contain a value of 0. If the client application encounters an error (or warning) during a statement's execution, sqlcode will contain the last code returned.
The SQL standard defines only a positive value of 100, which indicates that he most recent SQL statement processed returned/affected no rows. Since the SQL standard does not define other sqlcode values, please be aware that the values assigned to each condition may vary from database to database.
sqlerrm is a structure embedded within sqlca, composed of two members:
sqlerrml contains the length of the error message currently stored in sqlerrmc.
sqlerrmc contains the null-terminated message text associated with the code stored in sqlstate. If a message exceeds 149 characters in length, ecpglib will truncate the error message.
sqlerrp contains the string "NOT SET".
sqlerrd is an array that contains six elements:
sqlerrd[1] contains the OID of the processed row (if applicable).
sqlerrd[2] contains the number of processed or returned rows.
sqlerrd[0], sqlerrd[3], sqlerrd[4] and sqlerrd[5] are unused.
sqlwarn is an array that contains 8 characters:
sqlwarn[0] contains a value of 'W' if any other element within sqlwarn is set to 'W'.
sqlwarn[1] contains a value of 'W' if a data value was truncated when it was stored in a host variable.
sqlwarn[2] contains a value of 'W' if the client application encounters a non-fatal warning.
sqlwarn[3], sqlwarn[4], sqlwarn[5], sqlwarn[6], and sqlwarn[7] are unused.
sqlstate is a 5 character array that contains a SQL-compliant status code after the execution of a statement from the client application. If a statement processes without error, sqlstate will contain a value of 00000. Please note that sqlstate is not a null-terminated string.
sqlstate codes are assigned in a hierarchical scheme:
The first two characters of sqlstate indicate the general class of the condition.
The last three characters of sqlstate indicate a specific status within the class.
If the client application encounters multiple errors (or warnings) during an SQL statement's execution sqlstate will contain the last code returned.
The following table lists the sqlstate and sqlcode values, as well as the symbolic name and error description for the related condition:
07001, or 07002
07001, or 07002

6 Error Handling : 6.1 Error Handling with sqlca

Table of Contents Previous Next