SQLGetStmtAttr, функция

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

Сводка
SQLGetStmtAttr возвращает текущий параметр атрибута инструкции.

Синтаксис

  
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, если не указано иное.

Комментарии

Общие сведения об атрибутах инструкции см. в разделе "Атрибуты инструкции".

Вызов 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.

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

См. также

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