Функция SQLGetDiagRec

Соответствие
Введенная версия: Соответствие стандартам ODBC 3.0: ISO 92

Сводка
SQLGetDiagRec возвращает текущие значения нескольких полей диагностической записи, содержащих информацию об ошибках, предупреждениях и статусе. В отличие от SQLGetDiagField, который возвращает одно диагностическое поле за вызов, SQLGetDiagRec возвращает несколько часто используемых полей диагностической записи, включая SQLSTATE, родной код ошибки и текст диагностического сообщения.

Syntax

  
SQLRETURN SQLGetDiagRec(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLCHAR *       SQLState,  
     SQLINTEGER *    NativeErrorPtr,  
     SQLCHAR *       MessageText,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   TextLengthPtr);  

Arguments

HandleType
[Входные данные] Идентификатор типа дескриптора, описывающий тип дескриптора, для которого требуется диагностика. Должно быть одним из следующих элементов:

• SQL_HANDLE_DBC

• SQL_HANDLE_DBC_INFO_TOKEN

• SQL_HANDLE_DESC

• SQL_HANDLE_ENV

• SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN дескриптор используется только диспетчером драйверов и драйвером. Приложения не должны использовать этот тип дескриптора. Для получения дополнительной информации о SQL_HANDLE_DBC_INFO_TOKEN см. раздел «Развитие Connection-Pool осведомлённости у водителя ODBC».

Дескриптор
[Входные данные] Дескриптор структуры диагностических данных типа, указанного HandleType. Если HandleType SQL_HANDLE_ENV, Handle может быть общим или необработаным дескриптором среды.

RecNumber
[Входные данные] Указывает запись состояния, из которой приложение ищет сведения. Записи состояния нумеруются от 1.

Sqlstate
[Выход] Указатель на буфер для возврата пятисимвольного SQLSTATE кода (с завершением NULL) для диагностической записи RecNumber. Первые два символа обозначают класс; следующие три указывают на подкласс. Эта информация содержится в области диагностики SQL_DIAG_SQLSTATE. Дополнительные сведения см. в SQLSTATEs.

NativeErrorPtr
[Выход] Указатель на буфер для возврата родного кода ошибки, специфичного для источника данных. Эта информация содержится в области диагностики SQL_DIAG_NATIVE.

MessageText
[Выход] Указатель на буфер для возврата текстовой строки диагностического сообщения. Эта информация содержится в области диагностики SQL_DIAG_MESSAGE_TEXT. Для формата строки см. раздел «Диагностические сообщения».

Если MessageText равен NULL, TextLengthPtr всё равно вернёт общее количество символов (исключая символ null-termination для данных символов), доступных для возврата в буфере, на который указывает MessageText.

BufferLength
[Ввод] Длина буфера *MessageText в символах. Максимальная длина текста диагностического сообщения отсутствует.

ТекстДлинаPtr
[Выход] Указатель на буфер, в котором можно вернуть общее количество символов (исключая количество символов, необходимых для символа null-termination), доступных для возврата в *MessageText. Если количество доступных для возврата символов превышает BufferLength, диагностический текст сообщения в *MessageText усекается до BufferLength минус длина символа нулевой терминации.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA или SQL_INVALID_HANDLE.

Diagnostics

SQLGetDiagRec не публикует диагностические записи для себя. В нем используются следующие возвращаемые значения, чтобы сообщить о результатах собственного выполнения:

• SQL_SUCCESS: функция успешно вернула диагностические сведения.

• SQL_SUCCESS_WITH_INFO: Буфер *MessageText был слишком мал, чтобы хранить запрошенное диагностическое сообщение. Диагностические записи не были получены. Чтобы определить, что произошло усечение, приложение должно сравнить BufferLength с фактическим количеством доступных байт, которое записывается в *TextLengthPtr.

• SQL_INVALID_HANDLE: дескриптор, указанный HandleType и Handle, не является допустимым дескриптором.

• SQL_ERROR: произошло одно из следующих действий:

  • RecNumber был отрицательным или нулем.

  • BufferLength был меньше нуля.

  • При использовании асинхронного уведомления асинхронная операция в дескрипторе не завершена.

• SQL_NO_DATA: RecNumber было больше количества диагностических записей, которые существовали для дескриптора, указанного в Handle. Функция также возвращает SQL_NO_DATA для любых положительных RecNumber, если нет диагностических записей для Handle.

Comments

Приложение обычно вызывает SQLGetDiagRec , когда предыдущий вызов функции ODBC возвращал SQL_ERROR или SQL_SUCCESS_WITH_INFO. Однако, поскольку любая функция ODBC может создавать ноль или более диагностических записей при каждом вызове, приложение может вызвать SQLGetDiagRec после любого вызова функции ODBC. Приложение может несколько раз вызывать SQLGetDiagRec , чтобы вернуть часть или все записи в диагностической структуре данных. ODBC не устанавливает ограничений на количество диагностических записей, которые могут храниться одновременно.

SQLGetDiagRec не может использоваться для возврата полей из заголовка диагностической структуры данных. ( Аргумент RecNumber должен быть больше 0.) Для этого приложение должно вызывать SQLGetDiagField .

SQLGetDiagRec получает только диагностическую информацию, недавно связанную с дескриптором, указанным в аргументе Handle . Если приложение вызывает другую функцию ODBC, кроме SQLGetDiagRec, SQLGetDiagField или SQLError, любая диагностическая информация из предыдущих вызовов на том же дескрипте теряется.

Приложение может сканировать все диагностические записи путём цикла, увеличивая RecNumber, при условии, что SQLGetDiagRec возвращает SQL_SUCCESS. Вызовы SQLGetDiagRec не разрушают поля заголовка и записи. Приложение может повторно вызвать SQLGetDiagRec позже для получения поля из записи, если в промежутке не была вызвана другая функция, кроме SQLGetDiagRec, SQLGetDiagField или SQLError. Приложение также может получить счёт общего числа доступных диагностических записей, вызвав SQLGetDiagField для получения значения поля SQL_DIAG_NUMBER, а затем вызвав SQLGetDiagRec столько раз.

Для описания полей диагностической структуры данных см. SQLGetDiagField. Дополнительные сведения см. в разделе Использование SQLGetDiagRec и SQLGetDiagField и реализации SQLGetDiagRec и SQLGetDiagField.

Вызов API, отличный от выполняемого асинхронно, приведет к возникновению ошибки последовательности функций HY010. Однако запись об ошибке не может быть получена до завершения асинхронной операции.

Аргумент HandleType

Каждый тип дескриптора может иметь диагностические сведения, связанные с ним. Аргумент HandleType обозначает тип дескриптора аргумента Handle.

Некоторые поля заголовков и записей нельзя возвращать для дескрипторов среды, подключения, инструкции и дескриптора. Дескрипторы, для которых поле не применимо, указаны в разделах «Поля заголовка» и «Поля записи» в SQLGetDiagField.

Вызов SQLGetDiagRec вернёт SQL_INVALID_HANDLE, если HandleType — SQL_HANDLE_SENV, что обозначает общую дескрипторку среды. Однако если HandleType SQL_HANDLE_ENV, Handle может быть как общим, так и неразделённым дескриптором среды.

Связанные функции

Сведения о	Смотри
Получение поля диагностической записи или поля диагностического заголовка	Функция SQLGetDiagField

Связанные материалы

• Ссылка на ODBC API
• Файлы заголовков ODBC
• Пример программы ODBC