Диагностические записи и поля
Диагностические записи связаны со средой ODBC, соединением, инструкцией или указателями дескриптора. Когда любая функция ODBC возвращает код возврата, отличный от SQL_SUCCESS или SQL_INVALID_HANDLE, дескриптор, вызванный функцией, имеет связанные диагностические записи, содержащие информационные сообщения или сообщения об ошибке. Эти записи сохраняются до тех пор, пока с помощью данного дескриптора не будет вызвана другая функция, в этот момент записи отменяются. Не существует ограничения на количество диагностических записей, одновременно связанных с дескриптором.
Существует два типа диагностических записей: заголовок и состояние. Заголовочная запись имеет номер 0; если есть записи состояния, то они имеют номера от 1 и далее. Диагностические записи содержат различные поля для заголовочной записи и для записей состояния. Компоненты ODBC могут также определять свои собственные поля диагностических записей.
Поля в заголовочной записи содержат общие сведения о выполнении функции, включая код возврата, число строк, число записей состояния и тип выполняемой инструкции. Заголовочная запись создается всегда, если только функция ODBC не возвращает SQL_INVALID_HANDLE. Полный список полей в заголовочной записи см. в разделе SQLGetDiagField.
Поля в записях состояния содержат сведения об конкретных ошибках и предупреждениях, возвращаемых диспетчером драйверов ODBC, драйвером или источником данных, включая значение SQLSTATE, номер собственной ошибки, диагностическое сообщение, номер столбца и номер строки. Записи состояния создаются только в том случае, если функция возвращает SQL_ERROR, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_NEED_DATA или SQL_STILL_EXECUTING. Полный список полей в записях состояния см. в разделе SQLGetDiagField.
Функция SQLGetDiagRec получает единую диагностическую запись вместе с ее значением ODBC SQLSTATE, номером собственной ошибки и полями диагностического сообщения. Эта функциональность подобна имеющийся в ODBC 2.x функции SQLError. Простейшая функция обработки ошибок в ODBC 3.x состоит в повторяющемся вызове SQLGetDiagRec, начиная с задания параметру RecNumber значения 1, затем параметр RecNumber увеличивается на 1 до тех пор, пока функция SQLGetDiagRec не возвратит SQL_NO_DATA. Это эквивалентно вызову в приложении ODBC 2.x функции SQLError до тех пор, пока она не возвратит SQL_NO_DATA_FOUND.
ODBC 3.x поддерживает намного больше диагностических сведений, чем ODBC 2.x. Эти сведения хранятся в дополнительных полях в диагностических записях, получаемых с помощью функции SQLGetDiagField.
Драйвер ODBC для собственного клиента SQL Server содержит специфические для драйвера диагностические поля, которые можно получить с помощью функции SQLGetDiagField. Метки для этих специфических для драйвера полей определяются в файле sqlncli.h. С помощью этих меток можно получить состояние SQL Server, степень серьезности, имя сервера, имя процедуры и номер строки, связанный с каждой диагностической записью. Также файл sqlncli.h содержит определения кодов, которые используются драйвером для идентификации инструкций Transact-SQL, если приложение вызывает функцию SQLGetDiagField с заданным для параметра DiagIdentifier значением SQL_DIAG_DYNAMIC_FUNCTION_CODE.
Функция SQLGetDiagField обрабатывается диспетчером драйверов ODBC с помощью сведений об ошибке, кэшированных с базового драйвера. Диспетчер драйверов ODBC не кэширует специфические для драйвера диагностические поля до того, как установлено успешное соединение. Функция SQLGetDiagField возвращает SQL_ERROR, если она была вызвана для получения специфических для драйвера диагностических полей до того, как было завершено успешное соединение. Если функция соединения ODBC возвращает SQL_SUCCESS_WITH_INFO, то специфические для драйвера диагностические поля еще не доступны для функции соединения. Функцию SQLGetDiagField для специфических для драйвера диагностических полей можно вызывать после того, как будет сделан вызов функции соединения и после нее вызов другой функции ODBC.
Большинство ошибок, зарегистрированных драйвером ODBC для собственного клиента SQL Server могут быть эффективно обнаружены только с помощью сведений, возвращаемых функцией SQLGetDiagRec. Однако в некоторых случаях сведения, возвращаемые в специфических для драйвера диагностических полях, важны для диагностирования ошибки. При написании обработчика ошибок ODBC для приложений, использующих драйвер для собственного клиента SQL Server, рекомендуется также использовать функцию SQLGetDiagField, чтобы получить, по крайней мере, специфические для драйвера поля SQL_DIAG_SS_MSGSTATE и SQL_DIAG_SS_SEVERITY. Если какая-то ошибка может быть вызвана в нескольких местах кода SQL Server, то SQL_DIAG_SS_MSGSTATE показывает сотруднику отдела службы технической поддержки корпорации Майкрософт, где именно ошибка была вызвана, и это может иногда помочь при диагностике проблемы.