Handling Errors and Messages
When an application calls an ODBC function, the driver executes the function and returns diagnostic information in two ways: A return code indicates the overall success or failure of an ODBC function, and diagnostic records provide detailed information about the function. Diagnostic records include a header record and status records. At least one diagnostic record, the header record, is returned even if the function succeeds.
Diagnostic information is used at development time to catch programming errors, such as invalid handles and syntax errors in hard-coded SQL statements. It is also used at run time to catch run-time errors and warnings, such as data truncation, rule violations, and syntax errors in SQL statements entered by the user. Program logic is generally based on return codes.
For example, after an application calls SQLFetch to retrieve the rows in a result set, the return code indicates whether the end of the result set was reached (SQL_NO_DATA), if any informational messages were returned (SQL_SUCCESS_WITH_INFO), or if an error occurred (SQL_ERROR).
If the SQL Native Client ODBC driver returns anything other than SQL_SUCCESS, the application can call SQLGetDiagRec to retrieve any informational or error messages. Use SQLGetDiagRec to scroll up and down the message set if there is more than one message.
The return code SQL_INVALID_HANDLE always indicates a programming error and should never be encountered at run time. All other return codes provide run-time information, although SQL_ERROR may indicate a programming error.
The original Microsoft SQL Server native API, DB-Library for C, allows an application to install callback error-handling and message-handling functions that return errors or messages. Some Transact-SQL statements, such as PRINT, RAISERROR, DBCC, and SET, return their results to the DB-Library message handler function instead of to a result set. However, the ODBC API has no such callback capability. When the SQL Native Client ODBC driver detects messages coming back from SQL Server, it sets the ODBC return code to SQL_SUCCESS_WITH_INFO or SQL_ERROR and returns the message as one or more diagnostic records. Therefore, an ODBC application must carefully test for these return codes and call SQLGetDiagRec to retrieve message data.