SQLSetStmtAttr

Aplica-se a: SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure PDW (Sistema de Plataforma de Análise) do Azure Synapse Analytics

O driver ODBC do SQL Server Native Client não dá suporte ao modelo de cursor misto (conjunto de chaves/dinâmico). As tentativas de definir o tamanho do conjunto de chaves usando SQL_ATTR_KEYSET_SIZE falhará se o valor definido não for igual a 0.

O aplicativo define SQL_ATTR_ROW_ARRAY_SIZE em todas as instruções para declarar o número de linhas retornadas em uma chamada de função SQLFetch ou SQLFetchScroll . Em instruções que indicam um cursor de servidor, o driver usa SQL_ATTR_ROW_ARRAY_SIZE para determinar o tamanho do bloco de linhas que o servidor gera para satisfazer uma solicitação de busca do cursor. No tamanho do bloco de um cursor dinâmico, a ordenação e a associação de linhas serão fixas se o nível de isolamento da transação for suficiente para assegurar leituras repetidas de transações confirmadas. O cursor é completamente dinâmico fora do bloco indicado por esse valor. O tamanho do bloco de cursor de servidor é completamente dinâmico e pode ser alterado a qualquer momento do processamento de busca.

SQLGetStmtAttr e parâmetros com valor de tabela

SQLSetStmtAttr pode ser usado para definir SQL_SOPT_SS_PARAM_FOCUS no APD (descritor de parâmetro de aplicativo) antes de acessar os campos do descritor para colunas de parâmetro com valor de tabela.

Se for feita uma tentativa de definir SQL_SOPT_SS_PARAM_FOCUS como o ordinal de um parâmetro que não é um parâmetro com valor de tabela, SQLSetStmtAttr retornará SQL_ERROR e um registro de diagnóstico será criado com SQLSTATE = HY024 e a mensagem "Valor de atributo inválido". SQL_SOPT_SS_PARAM_FOCUS não é alterado quando SQL_ERROR é retornado.

A definição de SQL_SOPT_SS_PARAM_FOCUS como 0 restaura o acesso a registros de descritor para parâmetros.

SQLSetStmtAttr também pode ser usado para definir SQL_SOPT_SS_NAME_SCOPE. Para obter mais informações, consulte a seção SQL_SOPT_SS_NAME_SCOPE posteriormente neste tópico.

Para obter mais informações, consulte Metadados de parâmetro com valor de tabela para instruções preparadas.

Para obter mais informações sobre parâmetros com valor de tabela, consulte ODBC (Parâmetros com valor de tabela).

SQLSetStmtAttr Suporte para colunas esparsas

SQLSetStmtAttr pode ser usado para definir SQL_SOPT_SS_NAME_SCOPE. Para obter mais informações, consulte a seção SQL_SOPT_SS_NAME_SCOPE, mais adiante neste tópico. Para obter mais informações sobre colunas esparsas, consulte Suporte a colunas esparsas (ODBC).

Atributos de instrução

O driver ODBC do SQL Server Native Client também dá suporte aos seguintes atributos de instrução específicos do driver.

SQL_SOPT_SS_CURSOR_OPTIONS

O atributo SQL_SOPT_SS_CURSOR especifica se o driver usará opções de desempenho específicas do driver em cursores. SQLGetData não é permitido quando essas opções são definidas. A configuração padrão é SQL_CO_OFF. O valor ValuePtr é do tipo SQLLEN.

Valor de ValuePtr	Descrição
SQL_CO_OFF	Padrão. Desabilita cursores somente leitura e avanço rápido, habilita SQLGetData em cursores somente leitura e somente avanço. Quando SQL_SOPT_SS_CURSOR_OPTIONS for definido como SQL_CO_OFF, o tipo de cursor não será alterado. Ou seja, o cursor somente de avanço rápido permanecerá um cursor somente de avanço rápido. Para alterar o tipo de cursor, o aplicativo agora deve definir um tipo de cursor diferente usando SQLSetStmtAttr/SQL_ATTR_CURSOR_TYPE.
SQL_CO_FFO	Habilita cursores somente leitura e avanço rápido, desabilita SQLGetData em cursores somente leitura e somente avanço.
SQL_CO_AF	Habilita a opção autofetch em qualquer tipo de cursor. Quando essa opção é definida para um identificador de instrução, SQLExecute ou SQLExecDirect gerará um SQLFetchScroll implícito (SQL_FIRST). O cursor é aberto e o primeiro lote de linhas é retornado em uma única viagem de ida e volta ao servidor.
SQL_CO_FFO_AF	Habilita cursores somente de avanço rápido com a opção autofetch. É igual a se SQL_CO_AF e SQL_CO_FFO forem especificados.

Quando essas opções são definidas, o servidor fecha o cursor automaticamente ao detectar que a última linha foi buscada. O aplicativo ainda deve chamar SQLFreeStmt (SQL_CLOSE) ou SQLCloseCursor, mas o driver não precisa enviar a notificação de fechamento para o servidor.

Se a lista de seleção contiver uma coluna de texto, ntext ou imagem , o cursor somente de avanço rápido será convertido em um cursor dinâmico e SQLGetData será permitido.

SQL_SOPT_SS_DEFER_PREPARE

O atributo SQL_SOPT_SS_DEFER_PREPARE determina se a instrução é preparada imediatamente ou adiada até que SQLExecute, SQLDescribeCol ou SQLDescribeParam seja executado. No SQL Server 7.0 e versões anteriores, essa propriedade é ignorada (sem preparação adiada). O valor ValuePtr é do tipo SQLLEN.

Valor de ValuePtr	Descrição
SQL_DP_ON	Padrão. Depois de chamar SQLPrepare Function, a preparação da instrução é adiada até que SQLExecute seja chamado ou a operação de metapropriedade (SQLDescribeCol ou SQLDescribeParam) seja executada.
SQL_DP_OFF	A instrução é preparada assim que SQLPrepare é executado.

SQL_SOPT_SS_REGIONALIZE

O atributo SQL_SOPT_SS_REGIONALIZE é usado para determinar a conversão de dados no nível de instrução. O atributo faz o driver respeitar a configuração de localidade do cliente ao converter valores de data, hora, e moeda em cadeias de caracteres. A conversão é de tipos de dados nativos do SQL Server apenas para cadeias de caracteres.

O valor ValuePtr é do tipo SQLLEN.

Valor de ValuePtr	Descrição
SQL_RE_OFF	Padrão. O driver não converte dados de data, hora e moeda em dados de cadeia de caracteres usando a configuração de localidade do cliente.
SQL_RE_ON	O driver usa a configuração de localidade do cliente ao converter dados de data, hora e moeda em dados de cadeia de caracteres.

As configurações regionais de conversão se aplicam a tipos de dados de moeda, numéricos e de data e hora. A configuração da conversão é aplicável somente a conversões de saída quando valores de moeda, numéricos, de data ou de hora são convertidos em cadeias de caracteres.

Observação

Quando a opção de instrução SQL_SOPT_SS_REGIONALIZE está ativa, o driver usa as configurações do Registro de localidade do usuário atual. O driver não respeitará a localidade do thread atual se o aplicativo o definir, por exemplo, chamando SetThreadLocale.

A alteração do comportamento regional de uma fonte de dados pode fazer o aplicativo falhar. Um aplicativo que analisa cadeias de caracteres de data e espera que cadeias de caracteres de data sejam exibidas conforme definido pelo ODBC poderia ser afetado adversamente pela alteração desse valor.

SQL_SOPT_SS_TEXTPTR_LOGGING

O atributo SQL_SOPT_SS_TEXTPTR_LOGGING alterna o registro de operações em colunas que contêm dados de texto ou imagem . O valor ValuePtr é do tipo SQLLEN.

Valor de ValuePtr	Descrição
SQL_TL_OFF	Desabilita o registro de operações executadas em dados de texto e imagem .
SQL_TL_ON	Padrão. Permite o registro de operações executadas em dados de texto e imagem .

SQL_SOPT_SS_HIDDEN_COLUMNS

O atributo SQL_SOPT_SS_HIDDEN_COLUMNS expõe, no conjunto de resultados, colunas ocultas em uma instrução SELECT FOR BROWSE do SQL Server. Por padrão, o driver não expõe estas colunas. O valor ValuePtr é do tipo SQLLEN.

Valor de ValuePtr	Descrição
SQL_HC_OFF	Padrão. As colunas FOR BROWSE são ocultadas do conjunto de resultados.
SQL_HC_ON	Expõe colunas FOR BROWSE.

SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT

O atributo SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT retorna o texto de mensagem para a solicitação de notificação de consulta.

SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS

O atributo SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS especifica as opções usadas para a solicitação de notificação de consulta. Elas são especificadas em uma cadeia de caracteres com a sintaxe name=value conforme especificado a seguir. O aplicativo é responsável por criar o serviço e ler as notificações da fila.

A sintaxe da cadeia de caracteres das opções de notificação de consulta é:

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

Por exemplo:

service=mySSBService;local database=mydb

SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT

O atributo SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT especifica o número de segundos que a notificação de consulta deve permanecer ativa. O valor padrão é 432.000 segundos (5 dias). O valor ValuePtr é do tipo SQLLEN.

SQL_SOPT_SS_PARAM_FOCUS

O atributo SQL_SOPT_SS_PARAM_FOCUS especifica o foco para chamadas SQLBindParameter, SQLGetDescField, SQLSetDescField, SQLGetDescRec e SQLSetDescRec subsequentes.

O tipo para SQL_SOPT_SS_PARAM_FOCUS é SQLULEN.

O padrão é 0, o que significa que estas chamadas são endereçadas a parâmetros que correspondem a marcadores de parâmetro na instrução SQL. Quando definido como o número de um parâmetro com valor de tabela, estas chamadas são endereçadas a colunas desse parâmetro com valor de tabela. Quando definido como um valor que não é o número de um parâmetro com valor de tabela, estas chamadas retornam o erro IM020: "O foco do parâmetro não se refere a um parâmetro com valor de tabela".

SQL_SOPT_SS_NAME_SCOPE

O atributo SQL_SOPT_SS_NAME_SCOPE especifica o escopo de nome para chamadas de função de catálogo subsequentes. O conjunto de resultados retornado por SQLColumns depende da configuração de SQL_SOPT_SS_NAME_SCOPE.

O tipo para SQL_SOPT_SS_NAME_SCOPE é SQLULEN.

Valor de ValuePtr	Descrição
SQL_SS_NAME_SCOPE_TABLE	Padrão. Ao usar parâmetros com valor de tabela, indica que metadados de tabelas reais devem ser retornados. Ao usar o recurso de colunas esparsas, SQLColumns retornará apenas colunas que não são membros do column_set esparso.
SQL_SS_NAME_SCOPE_TABLE_TYPE	Indica que o aplicativo exige metadados para um tipo de tabela, em vez de uma tabela real (funções de catálogo devem retornar metadados para tipos de tabela). Em seguida, o aplicativo passa o TYPE_NAME do parâmetro com valor de tabela como o parâmetro TableName .
SQL_SS_NAME_SCOPE_EXTENDED	Ao usar o recurso de colunas esparsas, SQLColumns retorna todas as colunas, independentemente de column_set associação.
SQL_SS_NAME_SCOPE_SPARSE_COLUMN_SET	Ao usar o recurso de colunas esparsas, SQLColumns retorna apenas colunas que são membros do column_set esparso.
SQL_SS_NAME_SCOPE_DEFAULT	Igual a SQL_SS_NAME_SCOPE_TABLE.

SS_TYPE_CATALOG_NAME e SS_TYPE_SCHEMA_NAME são usados com os parâmetros CatalogName e SchemaName Quando um aplicativo concluir a recuperação de metadados para parâmetros com valor de tabela, ele deve definir SQL_SOPT_SS_NAME_SCOPE novamente com seu valor padrão SQL_SS_NAME_SCOPE_TABLE.

Quando SQL_SOPT_SS_NAME_SCOPE for definido como SQL_SS_NAME_SCOPE_TABLE, as consultas a servidores vinculados irão falhar. As chamadas para SQLColumns ou SQLPrimaryKeys com um catálogo que contém um componente de servidor falharão.

Se você tentar definir SQL_SOPT_SS_NAME_SCOPE com um valor inválido, SQL_ERROR será retornado e um registro de diagnóstico será gerado com SQLSTATE HY024 e a mensagem "Valor de atributo inválido".

Se uma função de catálogo diferente de SQLTables, SQLColumns ou SQLPrimaryKeys for chamada quando SQL_SOPT_SS_NAME_SCOPE tiver um valor diferente de SQL_SS_NAME_SCOPE_TABLE, SQL_ERROR será retornado. Um registro de diagnóstico é gerado com SQLSTATE HY010 e a mensagem "Erro de sequência de função (SQL_SOPT_SS_NAME_SCOPE não está definido como SQL_SS_NAME_SCOPE_TABLE)".

Confira também

Função SQLGetStmtAttr
Detalhes da implementação da API do ODBC