Функция SQLGetDiagRec

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

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

Синтаксис

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

Аргументы

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 см. в статье "Разработка осведомленности о пуле подключений" в драйвере ODBC.

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

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

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

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

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

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

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

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

Возвраты

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

Диагностика

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

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

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

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

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

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

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

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

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

Комментарии

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

SQLGetDiagRec нельзя использовать для возврата полей из заголовка структуры диагностических данных. (The Аргумент 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, Дескриптор может быть общим или не общим дескриптором среды.

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

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

См. также

Справочник по API ODBC
Файлы заголовков ODBC
Образец программы ODBC