SQLGetStmtAttr, функция
Соответствия
Представлена версия: соответствие стандартам ODBC 3.0: ISO 92
Сводка
SQLGetStmtAttr возвращает текущий параметр атрибута инструкции.
Заметка
Дополнительные сведения о том, с чем диспетчер драйверов сопоставляет эту функцию при использовании ODBC 3.Приложение x работает с ODBC 2.Драйвер x см. в разделе "Функции замены сопоставления" для обеспечения обратной совместимости приложений.
Синтаксис
SQLRETURN SQLGetStmtAttr(
SQLHSTMT StatementHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Аргументы
ОператорHandle
[Входные данные] Дескриптор инструкции.
Атрибут
[Входные данные] Атрибут для получения.
ValuePtr
[Выходные данные] Указатель на буфер, в котором возвращается значение атрибута, указанного в атрибуте.
Если Значение ValuePtr равно NULL, StringLengthPtr по-прежнему возвращает общее количество байтов (за исключением символа завершения null для символьных данных), доступное для возврата в буфер, на который указывает ValuePtr.
BufferLength
[Входные данные] Если атрибут является атрибутом ODBC, а ValuePtr указывает на символьную строку или двоичный буфер, этот аргумент должен быть длиной *ValuePtr. Если атрибут является атрибутом ODBC, а *ValuePtr является целым числом, bufferLength игнорируется. Если значение, возвращаемое в *ValuePtr, является строкой Юникода (при вызове SQLGetStmtAttrW), аргумент BufferLength должен быть четным числом.
Если атрибут является атрибутом, определенным драйвером, приложение указывает характер атрибута диспетчеру драйверов, задав аргумент BufferLength . BufferLength может иметь следующие значения:
Если *ValuePtr является указателем на символьную строку, буферLength — это длина строки или SQL_NTS.
Если *ValuePtr является указателем на двоичный буфер, приложение помещает результат макроса SQL_LEN_BINARY_ATTR(длина) в BufferLength. Это помещает отрицательное значение в BufferLength.
Если *ValuePtr является указателем на значение, отличное от символьной строки или двоичной строки, буферLength должен иметь значение SQL_IS_POINTER.
Если параметр *ValuePtr содержит тип данных фиксированной длины, буферLength SQL_IS_INTEGER или SQL_IS_UINTEGER соответствующим образом.
StringLengthPtr
[Выходные данные] Указатель на буфер, в котором возвращается общее количество байтов (за исключением символа завершения null), доступное для возврата в *ValuePtr. Если значение атрибута является символьной строкой, а число байтов, доступных для возврата, больше или равно BufferLength, данные в *ValuePtr усечены в BufferLength минус длина символа завершения null и завершается драйвером null.
Возвраты
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.
Диагностика
Когда SQLGetStmtAttr возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE может быть получено путем вызова SQLGetDiagRec с handleType SQL_HANDLE_STMT и дескриптором StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLGetStmtAttr и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01004 | Строковые данные, усеченные справа | Данные, возвращаемые в *ValuePtr , были усечены для буфераLength минус длина символа завершения null. Длина ненадежного строкового значения возвращается в *StringLengthPtr. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 24000 | Недопустимое состояние курсора | Атрибут аргумента был SQL_ATTR_ROW_NUMBER, и курсор не был открыт, или курсор был размещен до начала результирующий набор или после окончания результирующий набор. |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в аргументе MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY010 | Ошибка последовательности функций | (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция по-прежнему выполнялась при вызове функции SQLGetStmtAttr . (DM) асинхронно выполняющаяся функция была вызвана для StatementHandle и по-прежнему выполнялась при вызове этой функции. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для ОператораHandle и возвращены SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов. |
| HY013 | Ошибка управления памятью | Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти. |
| HY090 | Недопустимая длина строки или буфера | (DM) *ValuePtr — это символьная строка, и BufferLength было меньше нуля, но не равно SQL_NTS. |
| HY092 | Недопустимый идентификатор атрибута или параметра | Значение, указанное для атрибута аргумента, недопустимо для версии ODBC, поддерживаемой драйвером. |
| HY109 | Недопустимое положение курсора | Аргумент Атрибута был SQL_ATTR_ROW_NUMBER, и строка была удалена или не удалось получить. |
| HY117 | Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. | (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function. |
| HYC00 | Необязательный компонент не реализован | Значение, указанное для атрибута аргумента, было допустимым атрибутом инструкции ODBC для версии ODBC, поддерживаемой драйвером, но не поддерживается драйвером. |
| HYT01 | Время ожидания для подключения истекло | Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Драйвер не поддерживает эту функцию | (DM) Драйвер, соответствующий ОператорHandle , не поддерживает функцию. |
Комментарии
Общие сведения об атрибутах инструкции см. в разделе "Атрибуты инструкции".
Вызов SQLGetStmtAttr возвращается в *ValuePtr значение атрибута инструкции, указанного в Атрибуте. Это значение может быть значением SQLULEN или строкой символов, завершаемой значением NULL. Если значение является значением SQLULEN, некоторые драйверы могут записывать только более низкий 32-разрядный или 16-разрядный буфер и оставить бит более высокого порядка без изменений. Поэтому приложения должны использовать буфер SQLULEN и инициализировать значение до 0 перед вызовом этой функции. Кроме того, аргументы BufferLength и StringLengthPtr не используются. Если значение является строкой, завершающей значение NULL, приложение указывает максимальную длину этой строки в аргументе BufferLength , а драйвер возвращает длину этой строки в буфере *StringLengthPtr .
Чтобы разрешить приложениям, вызывающим SQLGetStmtAttr , работать с ODBC 2.Драйверы x , вызов SQLGetStmtAttr сопоставляется в диспетчере драйверов с SQLGetStmtOption.
Следующие атрибуты инструкции доступны только для чтения, поэтому их можно получить с помощью SQLGetStmtAttr, но не задать с помощью SQLSetStmtAttr:
SQL_ATTR_IMP_PARAM_DESC
SQL_ATTR_IMP_ROW_DESC
SQL_ATTR_ROW_NUMBER
Список атрибутов, которые можно задать и извлечь, см. в разделе SQLSetStmtAttr.
Связанные функции
| Сведения | Раздел |
|---|---|
| Возврат параметра атрибута подключения | Функция SQLGetConnectAttr |
| Настройка атрибута подключения | Функция SQLSetConnectAttr |
| Задание атрибута инструкции | Функция SQLSetStmtAttr |
См. также
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по