Handling Errors and Messages
Applies to: 
SQL Server
Azure SQL Database
Azure SQL Managed Instance
Azure Synapse Analytics
Analytics Platform System (PDW)
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 Server 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 Server 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.
For information about tracing errors, see Data Access Tracing. For information about enhancements to error tracing added in SQL Server 2012 (11.x), see Accessing Diagnostic Information in the Extended Events Log.