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

См. также

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