SQLSetStmtAttr

Применимо к:SQL ServerAzure SQL DatabaseAzure Managed InstanceAzure Synapse Analytics AnalyticsPlatform System (PDW)

Драйвер ODBC для собственного клиента SQL Server не поддерживает модель смешанного курсора (набор ключей или динамический). Попытки установить размер набора ключей с помощью атрибута SQL_ATTR_KEYSET_SIZE завершатся неудачей, если задаваемое значение не равно 0.

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

Функция SQLSetStmtAttr и возвращающие табличные значения параметры

SQLSetStmtAttr можно использовать для задания SQL_SOPT_SS_PARAM_FOCUS в дескрипторе параметра приложения (APD) перед доступом к полям дескриптора для столбцов параметров с табличным значением.

Если предпринята попытка задать SQL_SOPT_SS_PARAM_FOCUS порядковый номер параметра, который не является табличным параметром, SQLSetStmtAttr возвращает SQL_ERROR, а диагностическая запись создается с помощью SQLSTATE = HY024 и сообщение "Недопустимое значение атрибута". Если возвращается значение SQL_ERROR, то атрибут SQL_SOPT_SS_PARAM_FOCUS не меняется.

Установка атрибута SQL_SOPT_SS_PARAM_FOCUS в значение 0 восстанавливает доступ к записям дескриптора для параметров.

SQLSetStmtAttr также можно использовать для задания SQL_SOPT_SS_NAME_SCOPE. Дополнительные сведения см. в подразделе «SQL_SOPT_SS_NAME_SCOPE» далее в этом разделе.

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

Дополнительные сведения о табличном значении параметров см. в разделе "Параметры с табличным значением" (ODBC).

Поддержка разреженных столбцов функцией SQLSetStmtAttr

SQLSetStmtAttr можно использовать для задания SQL_SOPT_SS_NAME_SCOPE. Дополнительные сведения см. в разделе SQL_SOPT_SS_NAME_SCOPE далее в этом разделе. Дополнительные сведения о разреженных столбцах см. в разделе "Поддержка разреженных столбцов" (ODBC).

Атрибуты инструкции

Драйвер ODBC для собственного клиента SQL Server также поддерживает следующие атрибуты инструкции для конкретного драйвера.

SQL_SOPT_SS_CURSOR_OPTIONS

Атрибут SQL_SOPT_SS_CURSOR указывает, будет ли драйвер использовать для курсоров специфичные для данного драйвера параметры настройки производительности. SQLGetData не допускается при установке этих параметров. Значение по умолчанию равно SQL_CO_OFF. Значение аргумента ValuePtr имеет тип SQLLEN.

Значение ValuePtr	Description
SQL_CO_OFF	По умолчанию. Отключает курсоры только для чтения и автозабор только для чтения, включает SQLGetData только для перенаправления, доступные только для чтения. Если атрибут SQL_SOPT_SS_CURSOR_OPTIONS имеет значение SQL_CO_OFF, тип курсора не изменится. То есть быстрый однопроходный курсор останется быстрым однопроходным курсором. Чтобы изменить тип курсора, приложение должно задать другой тип курсора с помощью SQLSetStmtAttr/SQL_ATTR_CURSOR_TYPE.
SQL_CO_FFO	Включает быстрый переадресацию, только для чтения курсоров, отключает SQLGetData только для перенаправления, доступные только для чтения.
SQL_CO_AF	Включает параметр автоматической выборки для курсора любого типа. Если этот параметр задан для дескриптора инструкций, SQLExecute или SQLExecDirect создаст неявный SQLFetchScroll (SQL_FIRST). Курсор открыт, и первый набор строк возвращен за одно обращение к серверу.
SQL_CO_FFO_AF	Включает быстрые однопроходные курсоры с параметром автоматической выборки. Эквивалентно одновременному заданию SQL_CO_AF и SQL_CO_FFO.

Если эти параметры заданы, сервер автоматически закрывает курсор, когда обнаруживает, что была получена последняя строка. Приложение должно по-прежнему вызывать SQLFreeStmt (SQL_CLOSE) или SQLCloseCursor, но драйвер не должен отправлять близкое уведомление серверу.

Если список выбора содержит текст, ntext или столбец изображения , то курсор только для быстрого переадресации преобразуется в динамический курсор и SQLGetData разрешено.

SQL_SOPT_SS_DEFER_PREPARE

Атрибут SQL_SOPT_SS_DEFER_PREPARE определяет, подготавливается ли инструкция немедленно или откладывается до выполнения SQLExecute, SQLDescribeCol или SQLDescribeParam. В SQL Server 7.0 и более ранних версий это свойство игнорируется (не откладывается подготовка). Значение аргумента ValuePtr имеет тип SQLLEN.

Значение ValuePtr	Description
SQL_DP_ON	По умолчанию. После вызова функции SQLPrepare подготовка инструкции откладывается до тех пор, пока sqlExecute не будет вызвана или выполняется операция метапрописи (SQLDescribeCol или SQLDescribeParam).
SQL_DP_OFF	Инструкция подготавливается сразу после выполнения SQLPrepare .

SQL_SOPT_SS_REGIONALIZE

Атрибут SQL_SOPT_SS_REGIONALIZE используется для задания преобразования данных на уровне инструкции. Атрибут указывает драйверу, что следует использовать настройки локали на клиенте при преобразовании данных в денежном формате, формате даты и времени в символьные данные. Преобразование выполняется только из собственных типов данных SQL Server в символьные строки.

Значение аргумента ValuePtr имеет тип SQLLEN.

Значение ValuePtr	Description
SQL_RE_OFF	По умолчанию. Драйвер ODBC не использует настройки локали на клиенте при преобразовании данных в денежном формате, формате даты и времени в строковые данные.
SQL_RE_ON	Драйвер ODBC использует настройки локали на клиенте при преобразовании данных в денежном формате, формате даты и времени в символьные данные.

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

Заметка

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

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

SQL_SOPT_SS_TEXTPTR_LOGGING

Атрибут SQL_SOPT_SS_TEXTPTR_LOGGING переключает ведение журнала операций с столбцами, содержащими текстовые или изображения . Значение аргумента ValuePtr имеет тип SQLLEN.

Значение ValuePtr	Description
SQL_TL_OFF	Отключает ведение журнала операций, выполняемых с данными текста и изображения .
SQL_TL_ON	По умолчанию. Включает ведение журнала операций, выполняемых с данными текста и изображения .

SQL_SOPT_SS_HIDDEN_COLUMNS

Атрибут SQL_SOPT_SS_HIDDEN_COLUMNS предоставляет в результирующем наборе столбцы, скрытые в инструкции SQL Server SELECT FOR BROWSE. По умолчанию драйвер не предоставляет доступ к этим столбцам. Значение аргумента ValuePtr имеет тип SQLLEN.

Значение ValuePtr	Description
SQL_HC_OFF	По умолчанию. Столбцы FOR BROWSE в результирующем наборе скрыты.
SQL_HC_ON	Обеспечивает доступ к столбцам FOR BROWSE.

Атрибут SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT

Атрибут SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT возвращает текст сообщения в ответ на запрошенное уведомление о запросе.

SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS

Атрибут SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS задает параметры для запроса уведомления о запросе. Эти параметры заданы в строке с конструкцией name=value, как показано ниже. За создание службы и считывание уведомлений из очереди отвечает приложение.

Строка параметров уведомлений запросов имеет следующий синтаксис.

service=<service-name>[;(local database=<database>|broker instance=<broker instance>)]

Например:

service=mySSBService;local database=mydb

SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT

Атрибут SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT задает время в секундах, в течение которого уведомление о запросе будет активным. Значение по умолчанию составляет 432 000 секунд (5 суток). Значение аргумента ValuePtr имеет тип SQLLEN.

SQL_SOPT_SS_PARAM_FOCUS

Атрибут SQL_SOPT_SS_PARAM_FOCUS задает фокус для последующих вызовов SQLBindParameter, SQLGetDescField, SQLSetDescField, SQLGetDescRec и SQLSetDescRec.

Атрибут SQL_SOPT_SS_PARAM_FOCUS принадлежит к типу SQLULEN.

По умолчанию он имеет значение 0; это означает, что вызовы относятся к параметрам, соответствующим маркерам параметров в инструкции SQL. Если задать для атрибута значение, равное порядковому номеру возвращающего табличное значение параметра, вызовы будут относиться к столбцам этого параметра. Если задано значение, которое не является номером параметра табличного значения, эти вызовы возвращают ошибку IM020: "Фокус параметра не ссылается на параметр с табличным значением".

SQL_SOPT_SS_NAME_SCOPE

Атрибут SQL_SOPT_SS_NAME_SCOPE задает область действия имени для последующих вызовов функций работы с каталогами. Результирующий набор, возвращаемый SQLColumns, зависит от параметра SQL_SOPT_SS_NAME_SCOPE.

Атрибут SQL_SOPT_SS_NAME_SCOPE принадлежит к типу SQLULEN.

Значение ValuePtr	Description
SQL_SS_NAME_SCOPE_TABLE	По умолчанию. При использовании возвращающих табличное значение параметров этот атрибут указывает, что нужно возвратить метаданные реально существующих таблиц. При использовании функции разреженных столбцов SQLColumns возвращает только столбцы, которые не являются членами разреженных column_set.
SQL_SS_NAME_SCOPE_TABLE_TYPE	Указывает, что приложению требуются метаданные для табличного типа, а не для реально существующих таблиц (функции работы с каталогами должны возвращать метаданные для табличных типов). Затем приложение передает TYPE_NAME табличного параметра в качестве параметра TableName .
SQL_SS_NAME_SCOPE_EXTENDED	При использовании функции разреженных столбцов SQLColumns возвращает все столбцы независимо от column_set членства.
SQL_SS_NAME_SCOPE_SPARSE_COLUMN_SET	При использовании функции разреженных столбцов SQLColumns возвращает только столбцы, которые являются членами разреженного column_set.
SQL_SS_NAME_SCOPE_DEFAULT	Равен атрибуту SQL_SS_NAME_SCOPE_TABLE.

SS_TYPE_CATALOG_NAME и SS_TYPE_SCHEMA_NAME используются с параметрами CatalogName и SchemaName соответственно для идентификации каталога и схемы для параметра с табличным значением. Когда приложение закончит получать метаданные для возвращающего табличное значение параметра, оно должно вновь присвоить SQL_SOPT_SS_NAME_SCOPE значение по умолчанию SQL_SS_NAME_SCOPE_TABLE.

Если SQL_SOPT_SS_NAME_SCOPE имеет значение SQL_SS_NAME_SCOPE_TABLE, то запросы к связанным серверам завершаются ошибкой. Вызовы SQLColumns или SQLPrimaryKeys с каталогом, содержащим компонент сервера, завершаются ошибкой.

При попытке задать для атрибута SQL_SOPT_SS_NAME_SCOPE недопустимое значение будет возвращено значение SQL_ERROR и создана диагностическая запись с параметром SQLSTATE HY024 и сообщением «Недопустимое значение атрибута».

Если функция каталога другая, то sqlColumns или SQLPrimaryKeys вызывается, если SQL_SOPT_SS_NAME_SCOPE имеет значение, отличное от SQL_SS_NAME_SCOPE_TABLE, возвращается SQL_ERROR. Создается диагностическая запись с параметром SQLSTATE HY010 и сообщением «Ошибочная последовательность функций (значение атрибута SQL_SOPT_SS_NAME_SCOPE не равно SQL_SS_NAME_SCOPE_TABLE)».

См. также

Функция SQLGetStmtAttr
Подробные сведения о реализации API-интерфейсов ODBC