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