Because different database servers often have different diagnostic message
codes, DB2® UDB
CLI provides a standard set of SQLSTATEs that are defined by the X/Open
SQL CAE specification. This allows consistent message handling across different
database servers.
SQLSTATEs are alphanumeric strings
of 5 characters (bytes) with a format of
ccsss, where
cc indicates
class and
sss indicates subclass. Any SQLSTATE that has a
class of:
- 01, is a warning.
- HY, is generated by the CLI driver (either DB2 UDB CLI or ODBC).
The SQLError() function also returns an
error code if the code is generated by the server. When connected to an IBM® database
server, the error code is SQLCODE. If the code is generated by DB2 UDB CLI instead
of at the server, then the error code is set to -99999.
DB2 UDB
CLI SQLSTATEs include both additional IBM defined SQLSTATEs that are returned
by the database server, and DB2 UDB CLI defined SQLSTATEs for conditions that are
not defined in the X/Open specification. This allows for the maximum amount
of diagnostic information to be returned. When running applications in Windows® using
ODBC, it is also possible to receive ODBC defined SQLSTATEs.
Follow these
guidelines for using SQLSTATEs within your application:
- Always check the function return code before calling SQLError() to
determine if diagnostic information is available.
- Use the SQLSTATEs rather than the error code.
- To increase your application's portability, only build dependencies on
the subset of DB2 UDB
CLI SQLSTATEs that are defined by the X/Open specification, and return the
additional ones as information only. (Dependencies refers to the application
making logic flow decisions based on specific SQLSTATEs.)
- For maximum diagnostic information, return the text message along with
the SQLSTATE (if applicable, the text message includes the IBM defined
SQLSTATE). It is also useful for the application to print out the name of
the function that returned the error.