Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Conformidade
Versão Introduzida: Normas ODBC 3.0 Conformidade: ISO 92
Summary
O SQLSetConnectAttr define atributos que regulam aspetos das ligações.
Note
Para mais informações sobre o que o Gestor de Drivers mapeia esta função quando uma aplicação ODBC 3*.x* está a trabalhar com um driver ODBC 2*.x*, consulte Mapeamento de Funções de Substituição para Compatibilidade Retrocedora de Aplicações.
Syntax
SQLRETURN SQLSetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
Arguments
ConnectionHandle
[Entrada] Alavanca de ligação.
Atributo
[Entrada] Atributo ao conjunto, listado em "Comentários."
ValuePtr
[Entrada] Apontar para o valor a ser associado ao Atributo. Dependendo do valor de Attribute, ValuePtr será um valor inteiro sem sinal ou apontará para uma cadeia de caracteres terminada por nulo. Note que o tipo integral do argumento Atributo pode não ter comprimento fixo, veja a secção de Comentários para detalhes.
StringLength
[Entrada] Se o Atributo for um atributo definido por ODBC e o ValuePtr apontar para uma cadeia de caracteres ou um buffer binário, este argumento deve corresponder ao comprimento de *ValuePtr. Para dados de cadeia de caracteres, este argumento deve conter o número de bytes na cadeia.
Se o Atributo for um atributo definido por ODBC e o ValuePtr for um inteiro, o StringLength é ignorado.
Se o Atributo for definido pelo driver, a aplicação indica a natureza do atributo ao Driver Manager definindo o argumento StringLength . StringLength pode ter os seguintes valores:
Se ValuePtr for um ponteiro para uma cadeia de caracteres, então StringLength é o comprimento da cadeia ou SQL_NTS.
Se o ValuePtr for um apontador para um buffer binário, então a aplicação coloca o resultado da macro SQL_LEN_BINARY_ATTR(comprimento) no StringLength. Isto coloca um valor negativo em StringLength.
Se ValuePtr for um ponteiro para um valor diferente de uma cadeia de caracteres ou binária, então StringLength deve ter o valor SQL_IS_POINTER.
Se o ValuePtr contiver um valor de comprimento fixo, então o StringLength é SQL_IS_INTEGER ou SQL_IS_UINTEGER, conforme apropriado.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_STILL_EXECUTING.
Diagnósticos
Quando SQLSetConnectAttr devolve SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_DBC e um Handle de ConnectionHandle. A tabela seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLSetConnectAttr e explica cada um no contexto desta função; a notação "(DM)" precede as descrições dos SQLSTATEs devolvidas pelo Gestor de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.
O condutor pode regressar SQL_SUCCESS_WITH_INFO para fornecer informações sobre o resultado da definição de uma opção.
| SQLSTATE | Erro | Descrição |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica para o condutor. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Valor da opção alterado | O condutor não suportou o valor especificado no ValuePtr e substituiu-o por um valor semelhante. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| 08002 | Nome da ligação em uso | O argumento do Atributo era SQL_ATTR_ODBC_CURSORS, e o driver já estava ligado à fonte de dados. |
| 08003 | Ligação não aberta | (DM) Foi especificado um valor de Atributo que exigia uma ligação aberta, mas o ConnectionHandle não estava num estado de conexão. |
| 08S01 | Falha da ligação de comunicação | A ligação de comunicação entre o driver e a fonte de dados à qual o driver estava ligado falhou antes de a função concluir o processamento. |
| 24000 | Estado do cursor inválido | O argumento do Atributo era SQL_ATTR_CURRENT_CATALOG, e um conjunto de resultados estava pendente. |
| 25000 | Operação ilegal durante uma transação local | Uma ligação estava numa transação local enquanto tentava inscrever-se numa ligação de transação distribuída (DTC) ao definir o atributo de ligação SQL_ATTR_ENLIST_IN_DTC. Uma ligação já está registada num DTC. Foi estabelecida uma ligação numa ligação de transação distribuída e uma transação local foi iniciada definindo SQL_ATTR_AUTOCOMMIT para SQL_AUTOCOMMIT_OFF. |
| 3D000 | Nome do catálogo inválido | O argumento do Atributo era SQL_CURRENT_CATALOG, e o nome do catálogo especificado era inválido. |
| HY000 | Erro geral | Ocorreu um erro para o qual não existia um SQLSTATE específico e para o qual não estava definido nenhum SQLSTATE específico da implementação. A mensagem de erro devolvida pelo SQLGetDiagRec no buffer *MessageText descreve o erro e a sua causa. |
| HY001 | Erro de alocação de memória | O driver não conseguia alocar a memória necessária para suportar a execução ou conclusão da função. |
| HY008 | Operação cancelada | O processamento assíncrono foi ativado para o ConnectionHandle. A função SQLSetConnectAttr era chamada e, antes de terminar a execução, a função SQLCancelHandle era chamada no ConnectionHandle, e depois a função SQLSetConnectAttr era chamada novamente no ConnectionHandle. Ou, a função SQLSetConnectAttr era chamada e, antes de terminar a execução, o SQLCancelHandle era chamado no ConnectionHandle a partir de um thread diferente numa aplicação multithread. |
| HY009 | Uso inválido do ponteiro nulo | O argumento Atributo identificava um atributo de ligação que requeria um valor de cadeia, e o argumento ValuePtr era um ponteiro nulo. |
| HY010 | Erro de sequência de funções | (DM) Uma função de execução assíncrona era chamada para um StatementHandle associado ao ConnectionHandle e continuava a ser executada quando o SQLSetConnectAttr era chamado. (DM) Uma função de execução assíncrona (não esta) era chamada para o ConnectionHandle e continuava a ser executada quando esta função era chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para um dos handles de instruções associados ao ConnectionHandle e devolvido SQL_PARAM_DATA_AVAILABLE. Esta função era chamada antes de os dados serem recuperados para todos os parâmetros transmitidos. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos era chamado para um StatementHandle associado ao ConnectionHandle e devolvido SQL_NEED_DATA. Esta função era chamada antes de os dados serem enviados para todos os parâmetros ou colunas de dados na execução. (DM) SQLBrowseConnect foi chamado para o ConnectionHandle e retornou SQL_NEED_DATA. Esta função era chamada antes do SQLBrowseConnect devolver SQL_SUCCESS_WITH_INFO ou SQL_SUCCESS. |
| HY011 | O atributo não pode ser definido agora | O argumento do Atributo era SQL_ATTR_TXN_ISOLATION, e uma transação estava em aberto. |
| HY013 | Erro de gestão de memória | A chamada de função não podia ser processada porque os objetos de memória subjacentes não podiam ser acedidos, possivelmente devido a condições de baixa memória. |
| HY024 | Valor de atributo inválido | Dado o valor especificado do Atributo , foi especificado um valor inválido no ValuePtr. (O Gestor de Drivers devolve este SQLSTATE apenas para atributos de ligação e de instruções que aceitam um conjunto discreto de valores, como SQL_ATTR_ACCESS_MODE ou SQL_ATTR_ASYNC_ENABLE. Para todos os outros atributos de ligação e instrução, o driver deve verificar o valor especificado em ValuePtr.) O argumento Atributo era SQL_ATTR_TRACEFILE ou SQL_ATTR_TRANSLATE_LIB, e ValuePtr era uma cadeia vazia. |
| HY090 | Comprimento inválido da corda ou do buffer | (DM) *ValuePtr é uma cadeia de caracteres, e o argumento StringLength era inferior a 0 mas não era SQL_NTS. |
| HY092 | Identificador de atributo/opção inválido | (DM) O valor especificado para o argumento Atributo não era válido para a versão de ODBC suportada pelo driver. (DM) O valor especificado para o atributo argumento Atributo era um atributo de apenas leitura. |
| HY114 | O driver não suporta a execução de funções assíncronas a nível de ligação | (DM) Uma aplicação tentou permitir a execução de funções assíncronas com SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE para um driver que não suporta operações de ligação assíncronas. |
| HY117 | A ligação é suspensa devido ao estado desconhecido da transação. Apenas funções de desconexão e de leitura são permitidas. | (DM) Para mais informações sobre o estado suspenso, veja Função SQLEndTran. |
| HY121 | A Biblioteca de Cursores e o Driver-Aware Pooling não podem ser ativados ao mesmo tempo | Para mais informações, consulte Driver-Aware Pooling de Ligações. |
| HYC00 | Funcionalidade opcional não implementada | O valor especificado para o atributo argumento Attribute era uma ligação ou atributo de instrução ODBC válido para a versão de ODBC suportada pelo driver, mas que não era suportada pelo driver. |
| HYT01 | Expirou o tempo limite de ligação | O período de timeout da ligação expirou antes de a fonte de dados responder ao pedido. O período de tempo de expiração da ligação é definido através do SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | O driver não suporta esta função | (DM) O driver associado ao ConnectionHandle não suporta esta função. |
| IM009 | Não é possível carregar DLL de tradução | O driver não conseguiu carregar a DLL de tradução especificada para a ligação. Este erro só pode ser devolvido quando o Atributo está SQL_ATTR_TRANSLATE_LIB. |
| IM017 | A sondagem está desativada no modo de notificação assíncrona | Sempre que o modelo de notificação é utilizado, o sonding é desativado. |
| IM018 | O SQLCompleteAsync não foi chamado para completar a operação assíncrona anterior neste handle. | Se a chamada de função anterior no handle devolver SQL_STILL_EXECUTING e se o modo de notificação estiver ativado, o SQLCompleteAsync deve ser chamado no handle para fazer o pós-processamento e completar a operação. |
| S1118 | O driver não suporta notificações assíncronas | SQL_ATTR_ASYNC_DBC_EVENT foi definido (após a ligação ter sido estabelecida), mas a notificação assíncrona não é suportada pelo driver. |
Quando o Atributo é um atributo de instrução, o SQLSetConnectAttr pode devolver quaisquer SQLSTATEs devolvidos pelo SQLSetStmtAttr.
Comments
Para informações gerais sobre atributos de ligação, veja Atributos de Conexão.
Os atributos atualmente definidos e a versão do ODBC em que foram introduzidos são apresentados na tabela mais adiante nesta secção; Espera-se que mais atributos sejam definidos para tirar partido de diferentes fontes de dados. Um conjunto de atributos é reservado pelo ODBC; os desenvolvedores de drivers devem reservar valores para o seu uso específico do driver a partir do Open Group.
Note
A capacidade de definir atributos de instruções ao nível da ligação chamando SQLSetConnectAttr foi obsoleta no ODBC 3*.x*. As aplicações ODBC 3*.x* nunca devem definir atributos da instrução ao nível da ligação. Os atributos da instrução ODBC 3*.x* não podem ser definidos ao nível da ligação, com exceção dos atributos SQL_ATTR_METADATA_ID e SQL_ATTR_ASYNC_ENABLE, que são tanto atributos de ligação como atributos da instrução e podem ser definidos tanto ao nível da ligação como ao nível da instrução.
Os drivers ODBC 3*.x* só precisam de suportar esta funcionalidade se funcionarem com aplicações ODBC 2*.x* que definam opções de instruções ODBC 2*.x* ao nível da ligação. Para mais informações, consulte o mapeamento SQLSetConnectOption no Apêndice G: Diretrizes de Drivers para Retrocompatibilidade.
Uma aplicação pode chamar SQLSetConnectAttr a qualquer momento entre o momento em que a ligação é alocada e a libertação. Todos os atributos da ligação e da instrução definidos com sucesso pela aplicação para a ligação persistem até que o SQLFreeHandle seja chamado na ligação. Por exemplo, se uma aplicação chamar SQLSetConnectAttr antes de se ligar a uma fonte de dados, o atributo persiste mesmo que o SQLSetConnectAttr falhe no driver quando a aplicação se liga à fonte de dados; Se uma aplicação definir um atributo específico do driver, o atributo persiste mesmo que a aplicação se ligue a outro driver na ligação.
Alguns atributos de ligação só podem ser definidos antes de uma ligação ter sido estabelecida; outras só podem ser definidas depois de uma ligação ter sido estabelecida. A tabela seguinte indica os atributos de ligação que devem ser definidos antes ou depois de uma ligação ter sido estabelecida. Qualquer um indica que o atributo pode ser definido antes ou depois da ligação.
| Attribute | Definido antes ou depois da ligação? |
|---|---|
| SQL_ATTR_ACCESS_MODE | Ou[1] |
| SQL_ATTR_ASYNC_DBC_EVENT | Ambas |
| SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE | Ou[4] |
| SQL_ATTR_ASYNC_DBC_PCALLBACK | Ambas |
| SQL_ATTR_ASYNC_DBC_PCONTEXT | Ambas |
| SQL_ATTR_ASYNC_ENABLE | Ou[2] |
| SQL_ATTR_AUTO_IPD | Ambas |
| SQL_ATTR_AUTOCOMMIT | Ou[5] |
| SQL_ATTR_CONNECTION_DEAD | Depois de |
| SQL_ATTR_CONNECTION_TIMEOUT | Ambas |
| SQL_ATTR_CURRENT_CATALOG | Ou[1] |
| SQL_ATTR_DBC_INFO_TOKEN | Depois de |
| SQL_ATTR_ENLIST_IN_DTC | Depois de |
| SQL_ATTR_LOGIN_TIMEOUT | Antes |
| SQL_ATTR_METADATA_ID | Ambas |
| SQL_ATTR_ODBC_CURSORS | Antes |
| SQL_ATTR_PACKET_SIZE | Antes |
| SQL_ATTR_QUIET_MODE | Ambas |
| SQL_ATTR_TRACE | Ambas |
| SQL_ATTR_TRACEFILE | Ambas |
| SQL_ATTR_TRANSLATE_LIB | Depois de |
| SQL_ATTR_TRANSLATE_OPTION | Depois de |
| SQL_ATTR_TXN_ISOLATION | Ou[3] |
[1] SQL_ATTR_ACCESS_MODE e SQL_ATTR_CURRENT_CATALOG podem ser definidos antes ou depois da ligação, dependendo do driver. No entanto, aplicações interoperáveis definem-nos antes de se conectarem porque alguns drivers não suportam ajustá-los após a conexão.
[2] SQL_ATTR_ASYNC_ENABLE deve ser definido antes de haver uma declaração ativa.
[3] SQL_ATTR_TXN_ISOLATION só podem ser definidos se não houver transações em aberto na ligação. Alguns atributos de ligação suportam a substituição de um valor semelhante se a fonte de dados não suportar o valor especificado em *ValuePtr. Nesses casos, o driver devolve SQL_SUCCESS_WITH_INFO e SQLSTATE 01S02 (Valor da opção alterado). Por exemplo, se o Atributo for SQL_ATTR_PACKET_SIZE e o *ValuePtr exceder o tamanho máximo do pacote, o driver substitui o tamanho máximo. Para determinar o valor substituído, uma aplicação chama SQLGetConnectAttr.
[4] Se SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE for definido antes de uma ligação ser aberta, o Gestor de Drivers irá definir o atributo do driver quando este for carregado durante uma chamada para SQLBrowseConnect, SQLConnect ou SQLDriverConnect. Antes de uma chamada para SQLBrowseConnect, SQLConnect ou SQLDriverConnect, o Gestor de Drivers não sabe a que driver se deve ligar e não sabe se o driver suporta operações de ligação assíncronas. Por isso, o Driver Manager devolve sempre SQL_SUCCESS. Mas, caso o driver não suporte operações de ligação assíncronas, a chamada para SQLBrowseConnect, SQLConnect ou SQLDriverConnect falhará.
[5] Quando SQL_ATTR_AUTOCOMMIT está definido para FALSE, as aplicações devem chamar SQLEndTran(SQL_ROLLBACK) se alguma API devolver SQL_ERROR para garantir consistência transacional.
O formato da informação definida no *ValuePtr buffer depende do Atributo especificado. O SQLSetConnectAttr aceita informação de atributos num de dois formatos diferentes: uma cadeia de caracteres terminada por nulo ou um valor inteiro. O formato de cada um é indicado na descrição do atributo. As cadeias de caracteres apontadas pelo argumento ValuePtr do SQLSetConnectAttr têm um comprimento de bytes StringLength .
O argumento StringLength é ignorado se o comprimento for definido pelo atributo, como acontece com todos os atributos introduzidos em ODBC 2*.x* ou anteriores.
| Atributo | Conteúdos do ValuePtr |
|---|---|
| SQL_ATTR_ACCESS_MODE (ODBC 1.0) | Um valor SQLUINTEIR. SQL_MODE_READ_ONLY é usado pelo driver ou fonte de dados como indicador de que a ligação não é obrigada a suportar instruções SQL que causam atualizações. Este modo pode ser usado para otimizar estratégias de bloqueio, gestão de transações ou outras áreas, conforme apropriado ao driver ou fonte de dados. O condutor não é obrigado a impedir que tais declarações sejam submetidas à fonte de dados. O comportamento do driver e da fonte de dados quando solicitado a processar instruções SQL que não são só leitura durante uma ligação apenas leitura é definido pela implementação. SQL_MODE_READ_WRITE é o padrão. |
| SQL_ATTR_ASYNC_DBC_EVENT (ODBC 3.8) | Um valor SQLPOINTER que é um handle de evento. A notificação da conclusão das funções assíncronas é habilitada chamando SQLSetConnectAttr com o atributo SQL_ATTR_ASYNC_STMT_EVENT e especificando o handle do evento. Nota: O método de notificação não é suportado com a biblioteca de cursores. Um aplicativo receberá uma mensagem de erro se tentar habilitar a biblioteca de cursores via SQLSetConnectAttr, quando o método de notificação estiver habilitado. |
| SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE (ODBC 3.8) | Um valor SQLUINTEGER que permite ou desativa a execução assíncrona de funções selecionadas no handle de ligação. Para mais informações, consulte Execução Assíncrona (Método de Sondagem). SQL_ASYNC_DBC_ENABLE_ON = Permitir operação assíncrona para funções relacionadas com a ligação especificadas. SQL_ASYNC_DBC_ENABLE_OFF = (Padrão) Desativar a operação assíncrona para funções relacionadas com a ligação especificadas. Definir SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE é sempre síncrono (ou seja, nunca retornará SQL_STILL_EXECUTING). A execução assíncrona das operações de instruções é ativada com SQL_ATTR_ASYNC_ENABLE. |
| SQL_ATTR_ASYNC_DBC_PCALLBACK (ODBC 3.8) | Um valor SQLPOINTER que aponta para a estrutura de contexto. Só o Gestor de Drivers pode chamar a função SQLSetStmtAttr de um driver com este atributo. |
| SQL_ATTR_ASYNC_DBC_PCONTEXT (ODBC 3.8) | Um valor SQLPOINTER que aponta para a estrutura de contexto. Só o Gestor de Drivers pode chamar a função SQLSetStmtAttr de um driver com este atributo. |
| SQL_ATTR_ASYNC_ENABLE (ODBC 3.0) | Um valor SQLULEN que especifica se uma função chamada com uma instrução na ligação especificada é executada de forma assíncrona: SQL_ASYNC_ENABLE_OFF = Desativar o suporte de execução assíncrona ao nível da ligação para operações de instruções (o padrão). SQL_ASYNC_ENABLE_ON = Ativar suporte de execução assíncrona ao nível de ligação para operações de instruções. Este atributo pode ser definido quer o SQLGetInfo com o tipo de informação SQL_ASYNC_MODE retorne SQL_AM_CONNECTION ou SQL_AM_STATEMENT. |
| SQL_ATTR_AUTO_IPD (ODBC 3.0) | Um valor SQLUINTEGER apenas de leitura que especifica se a população automática do IPD após uma chamada ao SQLPrepare é suportada: SQL_TRUE = População automática do IPD após uma chamada ao SQLPrepare ser suportada pelo driver. SQL_FALSE = A população automática do IPD após uma chamada ao SQLPrepare não é suportada pelo driver. Servidores que não suportam declarações preparadas não poderão preencher automaticamente o IPD. Se SQL_TRUE for devolvido para o atributo de ligação SQL_ATTR_AUTO_IPD, o atributo da instrução SQL_ATTR_ENABLE_AUTO_IPD pode ser definido para ativar ou desativar automaticamente a população do IPD. Se SQL_ATTR_AUTO_IPD for SQL_FALSE, SQL_ATTR_ENABLE_AUTO_IPD não pode ser definido para SQL_TRUE. O valor padrão de SQL_ATTR_ENABLE_AUTO_IPD é igual ao valor de SQL_ATTR_AUTO_IPD. Este atributo de ligação pode ser devolvido pelo SQLGetConnectAttr , mas não pode ser definido pelo SQLSetConnectAttr. |
| SQL_ATTR_AUTOCOMMIT (ODBC 1.0) | Um valor SQLUINTEGER que especifica se deve usar o modo autocommit ou o modo de commit manual: SQL_AUTOCOMMIT_OFF = O driver utiliza o modo de commit manual, e a aplicação deve explicitamente comprometer ou reverter transações com SQLEndTran. SQL_AUTOCOMMIT_ON = O driver usa o modo de autocommit. Cada instrução é comprometida imediatamente após ser executada. Este é o padrão. Quaisquer transações abertas na ligação são comprometidas quando SQL_ATTR_AUTOCOMMIT está definida para SQL_AUTOCOMMIT_ON para mudar do modo de commit manual para o modo de autocommittente. Para mais informações, consulte Modo de Compromisso. Importante: Algumas fontes de dados eliminam os planos de acesso e fecham os cursores para todas as instruções numa ligação cada vez que uma instrução é confirmada; O modo de autocommit pode fazer com que isto aconteça após cada instrução nonquery ser executada ou quando o cursor está fechado para uma consulta. Para mais informações, consulte os tipos de informação SQL_CURSOR_COMMIT_BEHAVIOR e SQL_CURSOR_ROLLBACK_BEHAVIOR em SQLGetInfo e Efeito das Transações em Cursores e Instruções Preparadas. Quando um batch é executado em modo de autocommit, duas coisas são possíveis. Todo o lote pode ser tratado como uma unidade autocomprometível, ou cada instrução num lote é tratada como uma unidade autocomprometível. Certas fontes de dados podem suportar ambos estes comportamentos e podem proporcionar uma forma de escolher um ou outro. É definido pelo driver se um batch é tratado como uma unidade auto-commitável ou se cada instrução individual dentro do batch é autocommitível. |
| SQL_ATTR_CONNECTION_DEAD (ODBC 3.5) |
Um valor SQLUINTEGER apenas de leitura que indica o estado da ligação. Se SQL_CD_TRUE, a ligação perdeu-se. Se SQL_CD_FALSE, a ligação continua ativa. |
| SQL_ATTR_CONNECTION_TIMEOUT (ODBC 3.0) | Um valor SQLUINTEGER correspondente ao número de segundos para esperar que qualquer pedido na ligação seja concluído antes de regressar à aplicação. O driver deve devolver SQLSTATE HYT00 (Timeout expired) sempre que for possível timeout numa situação não associada à execução da consulta ou login. Se o ValuePtr for igual a 0 (o padrão), não há timeout. |
| SQL_ATTR_CURRENT_CATALOG (ODBC 2.0) | Uma cadeia de caracteres contendo o nome do catálogo a ser usado pela fonte de dados. Por exemplo, no SQL Server, o catálogo é uma base de dados, pelo que o driver envia uma instrução USEpara a fonte de dados, onde base de dados é a base de dados especificada em *ValuePtr. Para um driver de nível único, o catálogo pode ser um diretório, por isso o driver altera o diretório atual para o diretório especificado em *ValuePtr. |
| SQL_ATTR_DBC_INFO_TOKEN (ODBC 3.8 | Um valor SQLPOINTER usado para recolocar o token de informação de ligação no handle DBC quando o parâmetro do SQLRateConnection (*pRating) não é igual a 100. SQL_ATTR_DBC_INFO_TOKEN é só para o set. Não é possível usar SQLGetConnectAttr ou SQLGetConnectOption para recuperar este valor. O SQLSetConnectAttr do Gestor de Drivers não aceita SQL_ATTR_DBC_INFO_TOKEN, pois uma aplicação não deve definir este atributo. Se um driver devolver SQL_ERROR depois de definir SQL_ATTR_DBC_INFO_TOKEN, a ligação recém-obtida no pool será libertada. O Gestor de Condutores tenta então obter outra ligação do pool. Consulte Desenvolvimento Connection-Pool Consciência num Driver ODBC para mais informações. |
| SQL_ATTR_ENLIST_IN_DTC (ODBC 3.0) | Um valor SQLPOINTER que especifica se deve usar o driver ODBC em transações distribuídas coordenadas pelos Microsoft Component Services. Passe um objeto de transação DTC OLE que especifique a transação a exportar para SQL Server, ou SQL_DTC_DONE terminar a associação DTC da ligação. O cliente chama o método Coordenador de Transações Distribuídas da Microsoft (MS DTC) OLE ITransactionDispenser::BeginTransaction para iniciar uma transação MS DTC e criar um objeto de transação MS DTC que represente a transação. A aplicação chama então SQLSetConnectAttr com a opção SQL_ATTR_ENLIST_IN_DTC para associar o objeto de transação à ligação ODBC. Toda a atividade relacionada com a base de dados será realizada sob a proteção da transação MS DTC. A aplicação chama SQLSetConnectAttr com SQL_DTC_DONE para terminar a associação DTC da ligação. Para obter mais informações, consulte a documentação do MS DTC. |
| SQL_ATTR_LOGIN_TIMEOUT (ODBC 1.0) | Um valor SQLUINTEGER correspondente ao número de segundos para esperar que um pedido de login seja concluído antes de regressar à aplicação. O padrão depende do driver. Se o ValuePtr for 0, o timeout é desativado e uma tentativa de ligação espera indefinidamente. Se o timeout especificado exceder o limite máximo de login na fonte de dados, o driver substitui esse valor e devolve SQLSTATE 01S02 (Valor da opção alterado). |
| SQL_ATTR_METADATA_ID (ODBC 3.0) | Um valor SQLUINTEGER que determina como os argumentos das cadeias das funções de catálogo são tratados. Se SQL_TRUE, o argumento da cadeia das funções de catálogo é tratado como identificadores. O caso não é significativo. Para cordas não delimitadas, o driver remove quaisquer espaços finais e a corda é dobrada para maiúsculas. Para cordas delimitadas, o driver remove quaisquer espaços iniciais ou finais e leva literalmente tudo o que está entre os delimitadores. Se um destes argumentos for definido para um ponteiro nulo, a função devolve SQL_ERROR e SQLSTATE HY009 (Uso inválido do ponteiro nulo). Se SQL_FALSE, os argumentos de cadeia das funções de catálogo não são tratados como identificadores. O caso é significativo. Podem conter um padrão de pesquisa de cadeias ou não, dependendo do argumento. O valor padrão é SQL_FALSE. O argumento TableType dos SQLTables, que recebe uma lista de valores, não é afetado por este atributo. SQL_ATTR_METADATA_ID também podem ser definidos ao nível da instrução. (É o único atributo de ligação que também é atributo de afirmação.) Para mais informações, consulte Argumentos em Funções de Catálogo. |
| SQL_ATTR_ODBC_CURSORS (ODBC 2.0) | Um valor SQLULEN que especifica como o Gestor de Drivers utiliza a biblioteca de cursores ODBC: SQL_CUR_USE_IF_NEEDED = O Gestor de Drivers usa a biblioteca de cursores ODBC apenas se for necessária. Se o driver suportar a opção SQL_FETCH_PRIOR no SQLFetchScroll, o Gestor de Drivers utiliza as capacidades de scroll do driver. Caso contrário, utiliza a biblioteca de cursores ODBC. SQL_CUR_USE_ODBC = O Gestor de Drivers utiliza a biblioteca de cursores ODBC. SQL_CUR_USE_DRIVER = O Gestor de Drivers utiliza as capacidades de scroll do driver. Esta é a configuração padrão. Para mais informações sobre a biblioteca de cursores ODBC, consulte o Apêndice F: Biblioteca de Cursores ODBC. Aviso: A biblioteca de cursores será removida numa versão futura do Windows. Evite usar esta funcionalidade em novos trabalhos de desenvolvimento e planeie modificar aplicações que atualmente a utilizem. A Microsoft recomenda usar a funcionalidade de cursor do driver. |
| SQL_ATTR_PACKET_SIZE (ODBC 2.0) | Um valor SQLUINTEGER que especifica o tamanho do pacote de rede em bytes.
Nota: Muitas fontes de dados ou não suportam esta opção ou apenas podem devolver, mas não definir, o tamanho do pacote de rede. Se o tamanho especificado exceder o tamanho máximo do pacote ou for menor do que o tamanho mínimo do pacote, o driver substitui esse valor e retorna SQLSTATE 01S02 (Valor da opção alterado). Se a aplicação definir o tamanho do pacote depois de já ter sido feita uma ligação, o driver devolverá SQLSTATE HY011 (O atributo não pode ser definido agora). |
| SQL_ATTR_QUIET_MODE (ODBC 2.0) | Uma maçaneta de janela (HWND). Se o handler da janela for um ponteiro nulo, o driver não exibe nenhuma caixa de diálogo. Se o handle da janela não for um ponteiro nulo, deve ser o handle da janela pai da aplicação. Este é o padrão. O driver usa este handle para mostrar caixas de diálogo. Nota: O atributo SQL_ATTR_QUIET_MODE conexão não se aplica às caixas de diálogo apresentadas pelo SQLDriverConnect. |
| SQL_ATTR_TRACE (ODBC 1.0) | Um valor SQLUINTEGER que indica ao Gestor de Drivers se deve realizar o rastreamento: SQL_OPT_TRACE_OFF = Desligar o rastreio (o padrão) SQL_OPT_TRACE_ON = Traçado em Quando o rastreio está ativado, o Gestor de Drivers escreve cada chamada de função ODBC no ficheiro de rastreamento. Nota: Quando o traçado está ativado, o Gestor de Drivers pode devolver SQLSTATE IM013 (erro de ficheiro de traço) de qualquer função. Uma aplicação especifica um ficheiro de traço com a opção SQL_ATTR_TRACEFILE. Se o ficheiro já existir, o Gestor de Drivers adiciona-o ao ficheiro. Caso contrário, cria o ficheiro. Se o rastreio estiver ativado e nenhum ficheiro trace for especificado, o Gestor de Drivers escreve no ficheiro SQL. INICIAR sessão no diretório raiz. Uma aplicação pode definir a variável ODBCSharedTraceFlag para permitir o rastreamento dinamicamente. O rastreio é então ativado para todas as aplicações ODBC atualmente em execução. Se uma aplicação desligar o rastreamento, está desligado apenas para essa aplicação. Se a palavra-chave Trace na informação do sistema for definida para 1 quando uma aplicação chama SQLAllocHandle com um HandleType de SQL_HANDLE_ENV, o rastreamento está ativado para todos os handles. Está ativado apenas para a aplicação chamada SQLAllocHandle. Chamar SQLSetConnectAttr com um Atributo de SQL_ATTR_TRACE não requer que o argumento ConnectionHandle seja válido e não devolverá SQL_ERROR se ConnectionHandle for NULL. Este atributo aplica-se a todas as ligações. |
| SQL_ATTR_TRACEFILE (ODBC 1.0) | Uma cadeia de caracteres terminada por nulo contendo o nome do ficheiro de traço. O valor padrão do atributo SQL_ATTR_TRACEFILE é especificado com a palavra-chave TraceFile na informação do sistema. Para mais informações, consulte ODBC Subkey. Chamar SQLSetConnectAttr com um atributo de SQL_ATTR_TRACEFILE não requer que o argumento ConnectionHandle seja válido e não devolverá SQL_ERROR se ConnectionHandle for inválido. Este atributo aplica-se a todas as ligações. |
| SQL_ATTR_TRANSLATE_LIB (ODBC 1.0) | Uma cadeia de caracteres terminada por null contendo o nome de uma biblioteca contendo as funções SQLDriverToDataSource e SQLDataSourceToDriver que o driver acede para realizar tarefas como tradução de conjuntos de caracteres. Esta opção só pode ser especificada se o driver estiver ligado à fonte de dados. A configuração deste atributo persistirá através das ligações. Para mais informações sobre tradução de dados, consulte DLLs de Tradução e Referência de Função DLL de Tradução. |
| SQL_ATTR_TRANSLATE_OPTION (ODBC 1.0) | Um valor flag de 32 bits que é passado para a DLL de tradução. Este atributo só pode ser especificado se o driver estiver ligado à fonte de dados. Para informações sobre tradução de dados, consulte DLLs de Tradução. |
| SQL_ATTR_TXN_ISOLATION (ODBC 1.0) | Uma máscara de bits de 32 bits que define o nível de isolamento da transação para a ligação atual. Uma aplicação deve chamar SQLEndTran para comprometer ou reverter todas as transações abertas numa ligação, antes de chamar SQLSetConnectAttr com esta opção. Os valores válidos para ValuePtr podem ser determinados chamando SQLGetInfo com InfoType igual a SQL_TXN_ISOLATION_OPTIONS. Para uma descrição dos níveis de isolamento das transações, veja a descrição do tipo de informação SQL_DEFAULT_TXN_ISOLATION em SQLGetInfo e Níveis de Isolamento de Transações. |
[1] Estas funções só podem ser chamadas assíncronas se o descritor for um descritor de implementação, e não um descritor de aplicação.
Exemplo de código
Veja SQLConnect.
Funções relacionadas
| Para obter informações sobre | Veja |
|---|---|
| Atribuição de uma alça | Função SQLAllocHandle |
| Devolver a definição de um atributo de conexão | Função SQLGetConnectAttr |