Диагностические записи и поля

Применимо: SQL Server База данных SQL Azure Управляемый экземпляр SQL Azure azure Synapse Analytics Analytics Platform System (PDW)

Диагностические записи связаны со средой 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.функция xSQLError . Простейшая функция обработки ошибок в 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 для приложений с помощью драйвера ODBC собственного клиента SQL Server рекомендуется также использовать SQLGetDiagField для получения по крайней мере SQL_DIAG_SS_MSGSTATE и SQL_DIAG_SS_SEVERITY полей драйвера. Если определенная ошибка может возникать в нескольких местах в коде SQL Server, SQL_DIAG_SS_MSGSTATE указывает инженеру службы поддержки Майкрософт специально, где возникла ошибка, которая иногда помогает диагностировать проблему.

См. также

Обработка ошибок и сообщений