Функция SQLGetDiagField

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

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

Синтаксис

SQLRETURN SQLGetDiagField(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     DiagIdentifier,  
     SQLPOINTER      DiagInfoPtr,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLengthPtr);  

Аргументы

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. Если аргумент DiagIdentifier указывает любое поле заголовка диагностики, RecNumber игнорируется. Если нет, это должно быть более 0.

DiagIdentifier
[Входные данные] Указывает поле диагностики, значение которого должно быть возвращено. Дополнительные сведения см. в разделе "DiagIdentifier Argument" статьи "Комментарии".

DiagInfoPtr
[Выходные данные] Указатель на буфер, в котором возвращаются диагностические сведения. Тип данных зависит от значения DiagIdentifier. Если DiagInfoPtr является целым типом, приложения должны использовать буфер SQLULEN и инициализировать значение до 0 перед вызовом этой функции, так как некоторые драйверы могут записывать только нижний 32-разрядный или 16-разрядный буфер и оставить бит более высокого порядка неизменным.

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

BufferLength
[Входные данные] Если DiagIdentifier является диагностикой, определенной ODBC, и DiagInfoPtr указывает на строку символов или двоичный буфер, этот аргумент должен быть длиной *DiagInfoPtr. Если DiagIdentifier является полем, определенным ODBC, и *DiagInfoPtr является целым числом, BufferLength игнорируется. Если значение в *DiagInfoPtr является строкой Юникода (при вызове SQLGetDiagFieldW), аргумент BufferLength должен быть четным.

Если DiagIdentifier является определяемым драйвером полем, приложение указывает характер поля диспетчеру драйверов, задав аргумент BufferLength. BufferLength могут иметь следующие значения:

• Если DiagInfoPtr является указателем на символьную строку, BufferLength — это длина строки или SQL_NTS.

• Если DiagInfoPtr является указателем на двоичный буфер, приложение помещает результат макроса SQL_LEN_BINARY_ATTR (длины) в BufferLength. Это помещает отрицательное значение в BufferLength.

• Если DiagInfoPtr является указателем на значение, отличное от символьной строки или двоичной строки, BufferLength должны иметь значение SQL_IS_POINTER.

• Если *DiagInfoPtr содержит тип данных фиксированной длины, BufferLength SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT или SQL_IS_USMALLINT.

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

Возвращает

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

Диагностика

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

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

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

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

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

  • аргумент DiagIdentifier не был одним из допустимых значений.

  • аргумент DiagIdentifier был SQL_DIAG_CURSOR_ROW_COUNT, SQL_DIAG_DYNAMIC_FUNCTION, SQL_DIAG_DYNAMIC_FUNCTION_CODE или SQL_DIAG_ROW_COUNT, но Handle не был дескриптором инструкции. (Диспетчер драйверов возвращает эту диагностику.)

  • аргумент RecNumber был отрицательным или 0, если DiagIdentifier указал поле из диагностической записи. RecNumber игнорируется для полей заголовка.

  • Запрошенное значение было строкой символов и BufferLength было меньше нуля.

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

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

Комментарии

Приложение обычно вызывает SQLGetDiagField для выполнения одной из трех целей:

1. Получение определенных сведений об ошибке или предупреждении при возврате вызова функции SQL_ERROR или SQL_SUCCESS_WITH_INFO (или SQL_NEED_DATA для функции SQLBrowseConnect).

2. Чтобы определить количество строк в источнике данных, затронутых при выполнении операций вставки, удаления или обновления, с вызовом SQLExecute, SQLExecDirect, SQLBulkOperationsили SQLSetPos (из поля заголовка SQL_DIAG_ROW_COUNT) или определить количество строк, существующих в текущем открытом курсоре, Значение , если драйвер может предоставить эти сведения (из поля заголовка SQL_DIAG_CURSOR_ROW_COUNT).

3. Чтобы определить, какая функция была выполнена вызовом SQLExecDirect или SQLExecute (из полей заголовка SQL_DIAG_DYNAMIC_FUNCTION и SQL_DIAG_DYNAMIC_FUNCTION_CODE).

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

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

Приложение может вызывать SQLGetDiagField для возврата любого диагностического поля в любое время, за исключением SQL_DIAG_CURSOR_ROW_COUNT или SQL_DIAG_ROW_COUNT, которое вернет SQL_ERROR, если Handle не является дескриптором инструкции. Если любое другое поле диагностики не определено, вызов SQLGetDiagField вернет SQL_SUCCESS (если не обнаружена другая диагностика), а для поля возвращается неопределенное значение.

Дополнительные сведения см. в разделе Использование SQLGetDiagRec и SQLGetDiagField и реализации SQLGetDiagRec и SQLGetDiagField.

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

Аргумент HandleType

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

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

Если HandleType SQL_HANDLE_ENV, Handle может быть либо общим, либо необработаным дескриптором среды.

Поля диагностики заголовков для конкретного драйвера не должны быть связаны с дескриптором среды.

Единственными полями заголовка диагностики, определенными для дескриптора, являются SQL_DIAG_NUMBER и SQL_DIAG_RETURNCODE.

Аргумент DiagIdentifier

Этот аргумент указывает идентификатор поля, необходимого для структуры диагностических данных. Если recNumber больше или равно 1, данные в поле описывают диагностические сведения, возвращаемые функцией. Если значение recNumber равно 0, поле находится в заголовке структуры диагностических данных и, следовательно, содержит данные, относящиеся к вызову функции, возвращающим диагностические сведения, а не к определенной информации.

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

Приложение ODBC 3*.x*, работающее с драйвером ODBC 2*.x*, сможет вызывать SQLGetDiagField только с аргументом DiagIdentifier SQL_DIAG_CLASS_ORIGIN, SQL_DIAG_CLASS_SUBCLASS_ORIGIN, SQL_DIAG_CONNECTION_NAME, SQL_DIAG_MESSAGE_TEXT, SQL_DIAG_NATIVE, SQL_DIAG_NUMBER, SQL_DIAG_RETURNCODE, SQL_DIAG_SERVER_NAME, или SQL_DIAG_SQLSTATE. Все остальные поля диагностики возвращают SQL_ERROR.

Поля заголовка

Поля заголовка, перечисленные в следующей таблице, можно включить в аргумент DiagIdentifier.

Поля записи

Поля записи, перечисленные в следующей таблице, можно включить в аргумент DiagIdentifier.

Значения полей динамической функции

В следующей таблице описываются значения SQL_DIAG_DYNAMIC_FUNCTION и SQL_DIAG_DYNAMIC_FUNCTION_CODE, которые применяются к каждому типу инструкции SQL, выполняемой вызовом SQLExecute или SQLExecDirect. Драйвер может добавлять к перечисленным драйверу значения.

Последовательность записей состояния

Записи состояния размещаются в последовательности на основе номера строки и типа диагностики. Диспетчер драйверов определяет окончательный порядок возврата записей состояния, создаваемых им. Драйвер определяет окончательный порядок возврата записей состояния, создаваемых им.

Если диагностические записи публикуются диспетчером драйверов и драйвером, диспетчер драйверов отвечает за их заказ.

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

• Записи, которые не соответствуют какой-либо строке, отображаются перед записями, соответствующими определенной строке, так как SQL_NO_ROW_NUMBER определен как -1.

• Записи, для которых номер строки неизвестен перед всеми остальными записями, так как SQL_ROW_NUMBER_UNKNOWN определен как -2.

• Для всех записей, относящихся к определенным строкам, записи сортируются по значению в поле SQL_DIAG_ROW_NUMBER. Перечислены все ошибки и предупреждения первой строки, а затем все ошибки и предупреждения следующей строки, и т. д.

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

Следующие правила используются для определения первой записи в строке. Запись с самым высоким рангом является первой записью. Источник записи (диспетчер драйверов, драйвер, шлюз и т. д.) не учитывается при ранжировании записей.

• записи о состоянии, описывающие ошибки, имеют самый высокий рейтинг. К ошибкам сортировки применяются следующие правила:

  • Записи, указывающие на сбой транзакции или возможный сбой транзакции, выделяющие все остальные записи.

  • Если две или более записей описывают одно и то же условие ошибки, то SQLSTATEs, определенные спецификацией Open Group CLI (классы 03–ГЦ), не используют ODBC и определяемые драйвером SQLSTATEs.

• ,определяемые реализацией Значения данных, записи состояния, описывающие значения данных, определяемые драйвером no (класс 02), имеют второй самый высокий рейтинг.

• предупреждения записи состояния, описывающие предупреждения (класс 01), имеют самый низкий ранг. Если две или более записей описывают одно и то же условие предупреждения, то предупреждение SQLSTATEs, определенное спецификацией Open Group CLI, выдается определение ODBC и определяемые драйвером SQLSTATEs.

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

См. также

Справочник по API ODBC
файлы заголовков ODBC