Using the SQLCA Data Structure

Microsoft® SQL Server™ uses the SQL communications area (SQLCA) data structure to trap and report run-time errors to your Embedded SQL for C (ESQL/C) applications. Your application can check the error fields and status indicators of the SQLCA data structure to determine the success or failure of an Embedded SQL statement. The precompiler automatically includes the SQLCA data structure in ESQL/C applications.

You can include routines in your application to test the SQLCODE, SQLWARN, SQLERRM, SQLERRD, and SQLSTATE fields of the SQLCA data structure and to provide follow-up procedures according to the status returned.

• The SQLCODE field contains the negative SQL Server error code (the ESQL/C standard requires that error codes be negative).
• The SQLWARN flags are set if certain exceptions, such as data truncation, occur.
• The SQLERRM field contains the text of the error message.
• The SQLERRD1 field contains the error number.
• The SQLERRD3 array indicates the number of rows affected.
• The SQLSTATE field contains run-time errors that generate SQL-92 standard SQLSTATE codes.

Because the character fields of SQLCA (such as SQLWARN and SQLERRMC) are FAR pointers in Microsoft Windows®, you must use the %Fs format specifier for them when using printf and similar functions.

For more information about the SQLCA data structure, see Advanced Programming.