Статья
04/01/2012

SQLSetStmtAttr

Драйвер 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 в дескрипторе параметра приложения (application parameter descriptor, 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. Эти параметры допустимы только при соединении с экземпляром SQL Server 7.0 или более поздней версии. Значение аргумента ValuePtr имеет тип SQLLEN.

Значение ValuePtr	Описание
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, но драйвер не обязан посылать серверу уведомление о закрытии.

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

SQL_SOPT_SS_DEFER_PREPARE

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

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

SQL_SOPT_SS_REGIONALIZE

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

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

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

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

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

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

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

SQL_SOPT_SS_TEXTPTR_LOGGING

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

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

SQL_SOPT_SS_HIDDEN_COLUMNS

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

Значение ValuePtr	Описание
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	Описание
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 и сообщением «Недопустимое значение атрибута».

Если функция работы с каталогами, отличная от SQLTables, 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)».