Return codes and SQLSTATES for CLI

When you call CLI functions, there are two levels of diagnostics returned by the function: return codes and detailed diagnostics (SQLSTATEs, messages, SQLCA).

Each CLI function returns the function return code as a basic diagnostic. Both SQLGetDiagRec() and SQLGetDiagField() provide more detailed diagnostic information. If the diagnostic originates at the DBMS, the SQLGetSQLCA() function provides access to the SQLCA. This arrangement lets applications handle the basic flow control based on return codes, and use the SQLSTATES along with the SQLCA to determine the specific causes of failure and to perform specific error handling.

Both SQLGetDiagRec() and SQLGetDiagField() return three pieces of information:
  • SQLSTATE
  • Native error: if the diagnostic is detected by the data source, this is the SQLCODE; otherwise, this is set to -99999.
  • Message text: this is the message text associated with the SQLSTATE.

SQLGetSQLCA() returns the SQLCA for access to specific fields, but should only be used when SQLGetDiagRec() or SQLGetDiagField() cannot provide the required information.