SQLSetStmtAttr

Artigo
05/07/2013

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 retornado 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 campos de descritor para colunas de parâmetros 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 será criado um registro de diagnóstico 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 do parâmetro com valor de tabela para instruções preparadas.

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

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 posteriormente 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 estas opções estão definidas. A configuração padrão é SQL_CO_OFF. O valor ValuePtr é do tipo SQLLEN.

Valor ValuePtr	Descrição
SQL_CO_OFF	Padrão. Desabilita cursores somente de avanço rápido, somente leitura e autofetch, habilita SQLGetData em cursores de somente avanço, somente leitura. 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 deve definir agora um tipo de cursor diferente usando SQLSetStmtAttr/SQL_ATTR_CURSOR_TYPE.
SQL_CO_FFO	Habilita cursores somente de avanço rápido, somente leitura, desabilita SQLGetData em cursores de somente avanço, somente leitura.
SQL_CO_AF	Habilita a opção autofetch em qualquer tipo de cursor. Quando essa opção for definida para um identificador de instrução, SQLExecute ou SQLExecDirect gerará um SQLFetchScroll (SQL_FIRST) implícito. 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 ao servidor.

Se a lista selecionada contiver uma coluna text, ntext ou image, o cursor de somente 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 será preparada imediatamente ou adiada até SQLExecute, SQLDescribeCol ou SQLDescribeParam ser executado. No SQL Server 7.0 e anteriores, essa propriedade é ignorada (sem adiamento da preparação). O valor ValuePtr é do tipo SQLLEN.

Valor ValuePtr	Descrição
SQL_DP_ON	Padrão. Depois de chamar Função SQLPrepare, a preparação da instrução é adiada até que SQLExecute seja chamado ou que a operação de metapropriedade (SQLDescribeCol ou SQLDescribeParam) seja executada.
SQL_DP_OFF	A instrução será preparada assim que SQLPrepare for 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 ocorre somente de tipos de dados nativos do SQL Server em cadeias de caracteres.

O valor ValuePtr é do tipo SQLLEN.

Valor 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 honra a localidade do thread atual se o aplicativo assim 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 log de operações em colunas que contêm dados text ou image. O valor ValuePtr é do tipo SQLLEN.

Valor ValuePtr	Descrição
SQL_TL_OFF	Desabilita o log de operações executado em dados text e image.
SQL_TL_ON	Padrão. Habilita o log de operações executado em dados text e image.

SQL_SOPT_SS_HIDDEN_COLUMNS

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

Valor 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 é a seguinte:

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 das 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 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 esparsas.
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). O aplicativo passa então o TYPE_NAME do parâmetro com valor de tabela como parâmetro TableName.
SQL_SS_NAME_SCOPE_EXTENDED	Ao usar o recurso de colunas esparsas, SQLColumns retorna todas as colunas, independentemente da associação de column_set.
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 esparsas.
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, respectivamente, para identificar o catálogo e o esquema do parâmetro com valor de tabela. 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 irão falhar.

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)".

Partilhar via