Função SQLSetConnectAttr
Compatibilidade
Versão introduzida: ODBC 3.0 Conformidade com os padrões: ISO 92
Resumo
SQLSetConnectAttr define atributos que controlam aspectos de conexões.
Observação
Para obter mais informações sobre o que o Gerenciador de Driver mapeia essa função quando um aplicativo ODBC 3*.x* está trabalhando com um driver ODBC 2*.x*, consulte Mapeando funções de substituição para compatibilidade com versões anteriores de aplicativos.
Sintaxe
SQLRETURN SQLSetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
Argumentos
Identificador de conexão
[Entrada] Identificador de conexão.
Atributo
[Entrada] Atributo a ser definido, listado em "Comentários".
ValuePtr
[Entrada] Ponteiro 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 em nulo. Observe que o tipo integral do argumento Attribute pode não ter comprimento fixo, consulte a seção Comentários para obter detalhes.
Comprimento da cadeia de caracteres
[Entrada] Se Attribute for um atributo definido por ODBC e ValuePtr apontar para uma cadeia de caracteres ou um buffer binário, esse argumento deverá ter o comprimento de *ValuePtr. Para dados de cadeia de caracteres, esse argumento deve conter o número de bytes na cadeia de caracteres.
Se Attribute for um atributo definido por ODBC e ValuePtr for um inteiro, StringLength será ignorado.
Se Attribute for um atributo definido pelo driver, o aplicativo indicará a natureza do atributo para o Gerenciador de Driver definindo o argumento StringLength . StringLength pode ter os seguintes valores:
Se ValuePtr for um ponteiro para uma cadeia de caracteres, StringLength será o comprimento da cadeia de caracteres ou SQL_NTS.
Se ValuePtr for um ponteiro para um buffer binário, o aplicativo colocará o resultado da macro SQL_LEN_BINARY_ATTR(length) em StringLength. Isso coloca um valor negativo em StringLength.
Se ValuePtr for um ponteiro para um valor diferente de uma cadeia de caracteres ou uma cadeia de caracteres binária, StringLength deverá ter o valor SQL_IS_POINTER.
Se ValuePtr contiver um valor de comprimento fixo, StringLength será 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 retorna 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 a seguir lista os valores SQLSTATE normalmente retornados por SQLSetConnectAttr e explica cada um deles no contexto dessa função; a notação "(DM)" precede as descrições de SQLSTATEs retornadas pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.
O driver pode retornar SQL_SUCCESS_WITH_INFO para fornecer informações sobre o resultado da configuração de uma opção.
| SQLSTATE | Erro | Descrição |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Valor da opção alterado | O driver não deu suporte ao valor especificado em ValuePtr e substituiu por um valor semelhante. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 08002 | Nome da conexão em uso | O argumento Attribute foi SQL_ATTR_ODBC_CURSORS e o driver já estava conectado à fonte de dados. |
| 08003 | Conexão não aberta | (DM) Foi especificado um valor de atributo que exigia uma conexão aberta, mas o ConnectionHandle não estava em um estado conectado. |
| 08S01 | Falha no link de comunicação | O link de comunicação entre o driver e a fonte de dados à qual o driver estava conectado falhou antes que a função concluísse o processamento. |
| 24000 | Estado de cursor inválido | O argumento Attribute foi SQL_ATTR_CURRENT_CATALOG e um conjunto de resultados estava pendente. |
| 25000 | Operação ilegal durante uma transação local | Uma conexão estava em uma transação local ao tentar se inscrever em uma conexão de transação distribuída (DTC) definindo o atributo de conexão SQL_ATTR_ENLIST_IN_DTC. Uma conexão já está inscrita em um DTC. Uma conexão foi inscrita em uma conexão de transação distribuída e uma transação local foi iniciada definindo SQL_ATTR_AUTOCOMMIT como SQL_AUTOCOMMIT_OFF. |
| 3D000 | Nome de catálogo inválido | O argumento Attribute foi SQL_CURRENT_CATALOG e o nome do catálogo especificado era inválido. |
| HY000 | Erro geral | Ocorreu um erro para o qual não havia SQLSTATE específico e para o qual nenhum SQLSTATE específico da implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no buffer *MessageText descreve o erro e sua causa. |
| HY001 | Erro de alocação de memória | O driver não pôde alocar a memória necessária para dar suporte à execução ou conclusão da função. |
| HY008 | Operação cancelada | O processamento assíncrono foi habilitado para o ConnectionHandle. A função SQLSetConnectAttr foi chamada e, antes de concluir a execução, a função SQLCancelHandle foi chamada no ConnectionHandle e, em seguida, a função SQLSetConnectAttr foi chamada novamente no ConnectionHandle. Ou a função SQLSetConnectAttr foi chamada e, antes de concluir a execução, SQLCancelHandle foi chamado no ConnectionHandle de um thread diferente em um aplicativo multithread. |
| HY009 | Uso inválido de ponteiro nulo | O argumento Attribute identificou um atributo de conexão que exigia um valor de cadeia de caracteres e o argumento ValuePtr era um ponteiro nulo. |
| HY010 | Erro de sequência de função | (DM) Uma função de execução assíncrona foi chamada para um StatementHandle associado ao ConnectionHandle e ainda estava em execução quando SQLSetConnectAttr foi chamado. (DM) Uma função de execução assíncrona (não esta) foi chamada para o ConnectionHandle e ainda estava em execução quando essa função foi chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para um dos identificadores de instrução associados ao ConnectionHandle e retornou SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes que os dados fossem recuperados para todos os parâmetros transmitidos. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foi chamado para um StatementHandle associado ao ConnectionHandle e retornado SQL_NEED_DATA. Essa função foi chamada antes que os dados fossem enviados para todos os parâmetros ou colunas de dados em execução. (DM) SQLBrowseConnect foi chamado para o ConnectionHandle e retornado SQL_NEED_DATA. Essa função foi chamada antes de SQLBrowseConnect retornar SQL_SUCCESS_WITH_INFO ou SQL_SUCCESS. |
| HY011 | O atributo não pode ser definido agora | O argumento Attribute foi SQL_ATTR_TXN_ISOLATION e uma transação foi aberta. |
| HY013 | Erro de gerenciamento de memória | A chamada de função não pôde ser processada porque os objetos de memória subjacentes não puderam ser acessados, possivelmente devido a condições de memória baixa. |
| HY024 | Valor de atributo inválido | Dado o valor de atributo especificado, um valor inválido foi especificado em ValuePtr. (O Gerenciador de Driver retorna esse SQLSTATE somente para atributos de conexão e instrução que aceitam um conjunto discreto de valores, como SQL_ATTR_ACCESS_MODE ou SQL_ATTR_ASYNC_ENABLE. Para todos os outros atributos de conexão e instrução, o driver deve verificar o valor especificado em ValuePtr.) O argumento Attribute era SQL_ATTR_TRACEFILE ou SQL_ATTR_TRANSLATE_LIB e ValuePtr era uma cadeia de caracteres vazia. |
| HY090 | Cadeia de caracteres ou comprimento de buffer inválido | (DM) *ValuePtr é uma cadeia de caracteres e o argumento StringLength era menor que 0, mas não era SQL_NTS. |
| HY092 | Identificador de atributo/opção inválido | (DM) O valor especificado para o argumento Attribute não era válido para a versão do ODBC compatível com o driver. (DM) O valor especificado para o argumento Attribute era um atributo somente leitura. |
| HY114 | O driver não dá suporte à execução de função assíncrona no nível da conexão | (DM) Um aplicativo tentou habilitar a execução de função assíncrona com SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE para um driver que não dá suporte a operações de conexão assíncrona. |
| HY117 | A conexão está suspensa devido ao estado desconhecido da transação. Somente funções de desconexão e somente leitura são permitidas. | (DM) Para obter mais informações sobre o estado suspenso, consulte Função SQLEndTran. |
| HY121 | A biblioteca de cursores e o pool com reconhecimento de driver não podem ser ativados ao mesmo tempo | Para obter mais informações, confira Pool de conexões com reconhecimento de driver. |
| HYC00 | Recurso opcional não implementado | O valor especificado para o argumento Attribute era uma conexão ODBC válida ou um atributo de instrução para a versão do ODBC compatível com o driver, mas não tinha suporte do driver. |
| HYT01 | O tempo limite da conexão expirou | O período de tempo limite da conexão expirou antes que a fonte de dados respondesse à solicitação. O período de tempo limite da conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | O driver não suporta esta função | (DM) O driver associado ao ConnectionHandle não dá suporte à função. |
| IM009 | Não é possível carregar a DLL de tradução | O driver não pôde carregar a DLL de conversão especificada para a conexão. Esse erro pode ser retornado somente quando Attribute é SQL_ATTR_TRANSLATE_LIB. |
| IM017 | A sondagem está desabilitada no modo de notificação assíncrona | Sempre que o modelo de notificação é usado, a sondagem é desabilitada. |
| IM018 | SQLCompleteAsync não foi chamado para concluir a operação assíncrona anterior nesse identificador. | Se a chamada de função anterior no identificador retornar SQL_STILL_EXECUTING e se o modo de notificação estiver habilitado, SQLCompleteAsync deverá ser chamado no identificador para fazer o pós-processamento e concluir a operação. |
| S1118 | O driver não dá suporte à notificação assíncrona | SQL_ATTR_ASYNC_DBC_EVENT foi definido (depois que a conexão foi feita), mas a notificação assíncrona não é suportada pelo driver. |
Quando Attribute é um atributo de instrução, SQLSetConnectAttr pode retornar qualquer SQLSTATEs retornado por SQLSetStmtAttr.
Comentários
Para obter informações gerais sobre atributos de conexão, consulte Atributos de conexão.
Os atributos definidos atualmente e a versão do ODBC na qual eles foram introduzidos são mostrados na tabela mais adiante nesta seção; Espera-se que mais atributos sejam definidos para aproveitar as diferentes fontes de dados. Uma variedade de atributos é reservada pelo ODBC; os desenvolvedores de driver devem reservar valores para seu próprio uso específico do driver do Open Group.
Observação
A capacidade de definir atributos de instrução no nível da conexão chamando SQLSetConnectAttr foi preterida no ODBC 3*.x*. Os aplicativos ODBC 3*.x* nunca devem definir atributos de instrução no nível da conexão. Os atributos de instrução ODBC 3*.x* não podem ser definidos no nível de conexão, com exceção dos atributos SQL_ATTR_METADATA_ID e SQL_ATTR_ASYNC_ENABLE, que são atributos de conexão e atributos de instrução e podem ser definidos no nível de conexão ou no nível de instrução.
Os drivers ODBC 3*.x* só precisam dar suporte a essa funcionalidade se precisarem funcionar com aplicativos ODBC 2*.x* que definem opções de instrução ODBC 2*.x* no nível da conexão. Para obter mais informações, consulte Mapeamento de SQLSetConnectOption no Apêndice G: diretrizes de driver para compatibilidade com versões anteriores.
Um aplicativo pode chamar SQLSetConnectAttr a qualquer momento entre o momento em que a conexão é alocada e liberada. Todos os atributos de conexão e instrução definidos com êxito pelo aplicativo para a conexão persistem até que SQLFreeHandle seja chamado na conexão. Por exemplo, se um aplicativo chamar SQLSetConnectAttr antes de se conectar a uma fonte de dados, o atributo persistirá mesmo se SQLSetConnectAttr falhar no driver quando o aplicativo se conectar à fonte de dados; se um aplicativo definir um atributo específico do driver, o atributo persistirá mesmo se o aplicativo se conectar a um driver diferente na conexão.
Alguns atributos de conexão podem ser definidos somente antes de uma conexão ser feita; outros podem ser definidos somente após uma conexão ter sido feita. A tabela a seguir indica os atributos de conexão que devem ser definidos antes ou depois de uma conexão ter sido feita. Either indica que o atributo pode ser definido antes ou depois da conexão.
| Atributo | Definir antes ou depois da conexão? |
|---|---|
| SQL_ATTR_ACCESS_MODE | Ou[1] |
| SQL_ATTR_ASYNC_DBC_EVENT | Você pode usar o |
| SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE | Ou[4] |
| SQL_ATTR_ASYNC_DBC_PCALLBACK | Você pode usar o |
| SQL_ATTR_ASYNC_DBC_PCONTEXT | Você pode usar o |
| SQL_ATTR_ASYNC_ENABLE | Ou[2] |
| SQL_ATTR_AUTO_IPD | Você pode usar o |
| SQL_ATTR_AUTOCOMMIT | Ou[5] |
| SQL_ATTR_CONNECTION_DEAD | Após |
| SQL_ATTR_CONNECTION_TIMEOUT | Você pode usar o |
| SQL_ATTR_CURRENT_CATALOG | Ou[1] |
| SQL_ATTR_DBC_INFO_TOKEN | Após |
| SQL_ATTR_ENLIST_IN_DTC | Após |
| SQL_ATTR_LOGIN_TIMEOUT | Antes |
| SQL_ATTR_METADATA_ID | Você pode usar o |
| SQL_ATTR_ODBC_CURSORS | Antes |
| SQL_ATTR_PACKET_SIZE | Antes |
| SQL_ATTR_QUIET_MODE | Você pode usar o |
| SQL_ATTR_TRACE | Você pode usar o |
| SQL_ATTR_TRACEFILE | Você pode usar o |
| SQL_ATTR_TRANSLATE_LIB | Após |
| SQL_ATTR_TRANSLATE_OPTION | Após |
| 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 condutor. No entanto, os aplicativos interoperáveis os definem antes da conexão porque alguns drivers não oferecem suporte à alteração deles após a conexão.
[2] SQL_ATTR_ASYNC_ENABLE deve ser definido antes que haja uma declaração ativa.
[3] SQL_ATTR_TXN_ISOLATION só pode ser definido se não houver transações abertas na conexão. Alguns atributos de conexão dão suporte à substituição de um valor semelhante se a fonte de dados não der suporte ao valor especificado em *ValuePtr. Nesses casos, o driver retorna SQL_SUCCESS_WITH_INFO e SQLSTATE 01S02 (valor da opção alterado). Por exemplo, se Attribute for SQL_ATTR_PACKET_SIZE e *ValuePtr exceder o tamanho máximo do pacote, o driver substituirá o tamanho máximo. Para determinar o valor substituído, um aplicativo chama SQLGetConnectAttr.
[4] Se SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE for definido antes de uma conexão ser aberta, o Gerenciador de Driver definirá o atributo do driver quando o driver for carregado durante uma chamada para SQLBrowseConnect, SQLConnect ou SQLDriverConnect. Antes de uma chamada para SQLBrowseConnect, SQLConnect ou SQLDriverConnect, o Gerenciador de Driver não sabe a qual driver se conectar e não sabe se o driver dá suporte a operações de conexão assíncronas. Portanto, o Gerenciador de Driver sempre retorna SQL_SUCCESS. Mas, caso o driver não dê suporte a operações de conexão assíncrona, a chamada para SQLBrowseConnect, SQLConnect ou SQLDriverConnect falhará.
[5] Quando SQL_ATTR_AUTOCOMMIT é definido como FALSE, os aplicativos devem chamar SQLEndTran(SQL_ROLLBACK) se alguma API retornar SQL_ERROR para garantir a consistência transacional.
O formato das informações definidas no buffer *ValuePtr depende do atributo especificado. SQLSetConnectAttr aceitará informações de atributo em um dos dois formatos diferentes: uma cadeia de caracteres terminada em nulo ou um valor inteiro. O formato de cada um é anotado na descrição do atributo. As cadeias de caracteres apontadas pelo argumento ValuePtr de SQLSetConnectAttr têm um comprimento de bytes StringLength.
O argumento StringLength será ignorado se o comprimento for definido pelo atributo, como é o caso de todos os atributos introduzidos no ODBC 2*.x* ou anterior.
| Atributo | Conteúdo do ValuePtr |
|---|---|
| SQL_ATTR_ACCESS_MODE (ODBC 1.0) | Um valor SQLUINTEGER. SQL_MODE_READ_ONLY é usado pelo driver ou fonte de dados como um indicador de que a conexão não é necessária para dar suporte a instruções SQL que causam atualizações. Esse modo pode ser usado para otimizar estratégias de bloqueio, gerenciamento de transações ou outras áreas, conforme apropriado para o driver ou a fonte de dados. O driver não é necessário para impedir que essas instruções sejam enviadas para a fonte de dados. O comportamento do driver e da fonte de dados quando solicitado a processar instruções SQL que não são somente leitura durante uma conexão somente 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 identificador de evento. A notificação da conclusão de funções assíncronas é habilitada chamando SQLSetConnectAttr com o atributo SQL_ATTR_ASYNC_STMT_EVENT e especificando o identificador de evento. Observação: o método de notificação não é compatível com a biblioteca de cursores. Um aplicativo receberá a mensagem de erro se tentar habilitar a biblioteca de cursores por meio do SQLSetConnectAttr quando o método de notificação for habilitado. |
| SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE (ODBC 3.8) | Um valor SQLUINTEGER que habilita ou desabilita a execução assíncrona de funções selecionadas no identificador de conexão. Para obter mais informações, consulte Execução assíncrona (método de pesquisa). SQL_ASYNC_DBC_ENABLE_ON = Habilite a operação assíncrona para funções relacionadas à conexão especificadas. SQL_ASYNC_DBC_ENABLE_OFF = (Padrão) Desative a operação assíncrona para funções relacionadas à conexão especificadas. A configuração SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE é sempre síncrona (ou seja, nunca retornará SQL_STILL_EXECUTING). A execução assíncrona de operações de instrução é habilitada com SQL_ATTR_ASYNC_ENABLE. |
| SQL_ATTR_ASYNC_DBC_PCALLBACK (ODBC 3.8) | Um valor SQLPOINTER que aponta para a estrutura de contexto. Somente o Gerenciador de Driver pode chamar a função SQLSetStmtAttr de um driver com esse atributo. |
| SQL_ATTR_ASYNC_DBC_PCONTEXT (ODBC 3.8) | Um valor SQLPOINTER que aponta para a estrutura de contexto. Somente o Gerenciador de Driver pode chamar a função SQLSetStmtAttr de um driver com esse atributo. |
| SQL_ATTR_ASYNC_ENABLE (ODBC 3.0) | Um valor SQLULEN que especifica se uma função chamada com uma instrução na conexão especificada é executada de forma assíncrona: SQL_ASYNC_ENABLE_OFF = Desabilitar o suporte à execução assíncrona no nível da conexão para operações de instrução (o padrão). SQL_ASYNC_ENABLE_ON = Habilite o suporte à execução assíncrona no nível da conexão para operações de instrução. Esse atributo pode ser definido se SQLGetInfo com o tipo de informação SQL_ASYNC_MODE retorna SQL_AM_CONNECTION ou SQL_AM_STATEMENT. |
| SQL_ATTR_AUTO_IPD (ODBC 3.0) | Um valor SQLUINTEGER somente leitura que especifica se há suporte para o preenchimento automático do IPD após uma chamada para SQLPrepare : SQL_TRUE = O preenchimento automático do IPD após uma chamada para SQLPrepare é suportado pelo driver. SQL_FALSE = O preenchimento automático do IPD após uma chamada para SQLPrepare não é suportado pelo driver. Os servidores que não oferecem suporte a instruções preparadas não poderão preencher o IPD automaticamente. Se SQL_TRUE for retornado para o atributo de conexão SQL_ATTR_AUTO_IPD, o atributo de instrução SQL_ATTR_ENABLE_AUTO_IPD poderá ser definido para ativar ou desativar o preenchimento automático do IPD. Se SQL_ATTR_AUTO_IPD for SQL_FALSE, SQL_ATTR_ENABLE_AUTO_IPD não poderá ser definido como SQL_TRUE. O valor padrão de SQL_ATTR_ENABLE_AUTO_IPD é igual ao valor de SQL_ATTR_AUTO_IPD. Esse atributo de conexão pode ser retornado por SQLGetConnectAttr , mas não pode ser definido por SQLSetConnectAttr. |
| SQL_ATTR_AUTOCOMMIT (ODBC 1.0) | Um valor SQLUINTEGER que especifica se o modo de confirmação automática ou de confirmação manual deve ser usado: SQL_AUTOCOMMIT_OFF = O driver usa o modo de confirmação manual e o aplicativo deve confirmar ou reverter explicitamente as transações com SQLEndTran. SQL_AUTOCOMMIT_ON = O driver usa o modo de confirmação automática. Cada instrução é confirmada imediatamente após ser executada. Esse é o padrão. Todas as transações abertas na conexão são confirmadas quando SQL_ATTR_AUTOCOMMIT é definido como SQL_AUTOCOMMIT_ON para mudar do modo de confirmação manual para o modo de confirmação automática. Para obter mais informações, consulte Modo de confirmação. Importante: Algumas origens de dados excluem os planos de acesso e fecham os cursores de todas as instruções em uma conexão sempre que uma instrução é confirmada; o modo de confirmação automática pode fazer com que isso aconteça depois que cada instrução que não seja de consulta for executada ou quando o cursor for fechado para uma consulta. Para obter mais informações, consulte os tipos de informações SQL_CURSOR_COMMIT_BEHAVIOR e SQL_CURSOR_ROLLBACK_BEHAVIOR em SQLGetInfo e Efeito de transações em cursores e instruções preparadas. Quando um lote é executado no modo de confirmação automática, duas coisas são possíveis. O lote inteiro pode ser tratado como uma unidade auto-confirmável, ou cada instrução em um lote é tratada como uma unidade auto-confirmável. Determinadas fontes de dados podem dar suporte a esses dois comportamentos e podem fornecer uma maneira de escolher um ou outro. É definido pelo driver se um lote é tratado como uma unidade auto-confirmável ou se cada instrução individual dentro do lote é auto-confirmável. |
| SQL_ATTR_CONNECTION_DEAD (ODBC 3.5) |
Um valor SQLUINTEGER somente leitura que indica o estado da conexão. Se SQL_CD_TRUE, a conexão foi perdida. Se SQL_CD_FALSE, a conexão ainda está ativa. |
| SQL_ATTR_CONNECTION_TIMEOUT (ODBC 3.0) | Um valor SQLUINTEGER correspondente ao número de segundos para aguardar a conclusão de qualquer solicitação na conexão antes de retornar ao aplicativo. O driver deve retornar SQLSTATE HYT00 (Tempo limite expirado) sempre que for possível atingir o tempo limite em uma situação não associada à execução da consulta ou logon. Se ValuePtr for igual a 0 (o padrão), não haverá tempo limite. |
| SQL_ATTR_CURRENT_CATALOG (ODBC 2.0) | Uma cadeia de caracteres que contém o nome do catálogo a ser usado pela fonte de dados. Por exemplo, no SQL Server, o catálogo é um banco de dados, portanto, o driver envia uma instrução de banco de dados USE para a fonte de dados, em que database é o banco de dados especificado em *ValuePtr. Para um driver de camada única, o catálogo pode ser um diretório, portanto, o driver altera seu diretório atual para o diretório especificado em *ValuePtr. |
| SQL_ATTR_DBC_INFO_TOKEN (ODBC 3.8 | Um valor SQLPOINTER usado para definir o token de informações de conexão no identificador DBC quando o parâmetro (*pRating) de SQLRateConnection não é igual a 100. SQL_ATTR_DBC_INFO_TOKEN é somente definido. Não é possível usar SQLGetConnectAttr ou SQLGetConnectOption para recuperar esse valor. O SQLSetConnectAttr do Gerenciador de Driver não aceitará SQL_ATTR_DBC_INFO_TOKEN, pois um aplicativo não deve definir esse atributo. Se um driver retornar SQL_ERROR após definir SQL_ATTR_DBC_INFO_TOKEN, a conexão recém-obtida do pool será liberada. O Gerenciador de Driver tentará obter outra conexão do pool. Consulte Desenvolvendo o reconhecimento do pool de conexões em um driver ODBC para obter mais informações. |
| SQL_ATTR_ENLIST_IN_DTC (ODBC 3.0) | Um valor SQLPOINTER que especifica se o driver ODBC deve ser usado em transações distribuídas coordenadas pelos Serviços de Componentes da Microsoft. Passe um objeto de transação OLE DTC que especifique a transação a ser exportada para SQL Server ou SQL_DTC_DONE para encerrar a associação DTC da conexão. O cliente chama o método OLE ITransactionDispenser::BeginTransaction do Microsoft Distributed Transaction Coordinator (MS DTC) para iniciar uma transação MS DTC e criar um objeto de transação MS DTC que represente a transação. Em seguida, o aplicativo chama SQLSetConnectAttr com a opção SQL_ATTR_ENLIST_IN_DTC para associar o objeto de transação à conexão ODBC. Todas as atividades de banco de dados relacionadas serão executadas sob a proteção da transação do MS DTC. O aplicativo chama SQLSetConnectAttr com SQL_DTC_DONE para encerrar a associação DTC da conexã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 aguardar a conclusão de uma solicitação de logon antes de retornar ao aplicativo. O padrão é dependente do driver. Se ValuePtr for 0, o tempo limite será desabilitado e uma tentativa de conexão aguardará indefinidamente. Se o tempo limite especificado exceder o tempo limite máximo de logon na fonte de dados, o driver substituirá esse valor e retornará SQLSTATE 01S02 (valor da opção alterado). |
| SQL_ATTR_METADATA_ID (ODBC 3.0) | Um valor SQLUINTEGER que determina como os argumentos de cadeia de caracteres das funções de catálogo são tratados. Se SQL_TRUE, o argumento de cadeia de caracteres das funções de catálogo será tratado como identificadores. O caso não é significativo. Para cadeias de caracteres não delimitadas, o driver remove todos os espaços à direita e a cadeia de caracteres é dobrada em maiúsculas. Para cadeias de caracteres delimitadas, o driver remove todos os espaços à esquerda ou à direita e pega literalmente o que estiver entre os delimitadores. Se um desses argumentos for definido como um ponteiro nulo, a função retornará SQL_ERROR e SQLSTATE HY009 (uso inválido de ponteiro nulo). Se SQL_FALSE, os argumentos de cadeia de caracteres das funções de catálogo não serão tratados como identificadores. O caso é significativo. Eles podem conter um padrão de pesquisa de cadeia de caracteres ou não, dependendo do argumento. O valor padrão é SQL_FALSE. O argumento TableType de SQLTables, que usa uma lista de valores, não é afetado por esse atributo. SQL_ATTR_METADATA_ID também pode ser definido no nível da instrução. (É o único atributo de conexão que também é um atributo de instrução.) Para obter mais informações, confira Argumentos em funções de catálogo. |
| SQL_ATTR_ODBC_CURSORS (ODBC 2.0) | Um valor SQLULEN especificando como o Gerenciador de Driver usa a biblioteca de cursores ODBC: SQL_CUR_USE_IF_NEEDED = O Gerenciador de Driver usa a biblioteca de cursores ODBC somente se for necessário. Se o driver der suporte à opção SQL_FETCH_PRIOR em SQLFetchScroll, o Gerenciador de Driver usará os recursos de rolagem do driver. Caso contrário, ele usará a biblioteca de cursores ODBC. SQL_CUR_USE_ODBC = O Gerenciador de Driver usa a biblioteca de cursores ODBC. SQL_CUR_USE_DRIVER = O Gerenciador de Driver usa os recursos de rolagem do driver. Esta é a configuração padrão. Para obter 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 em uma versão futura do Windows. Evite usar esse recurso em desenvolvimentos novos e planeje modificar os aplicativos que atualmente o utilizam. A Microsoft recomenda usar a funcionalidade de cursor do driver. |
| SQL_ATTR_PACKET_SIZE (ODBC 2.0) | Um valor SQLUINTEGER especificando o tamanho do pacote de rede em bytes. Observação: muitas fontes de dados não oferecem suporte a essa opção ou podem apenas retornar, mas não definir o tamanho do pacote de rede. Se o tamanho especificado exceder o tamanho máximo do pacote ou for menor que o tamanho mínimo do pacote, o driver substituirá esse valor e retornará SQLSTATE 01S02 (Valor da opção alterado). Se o aplicativo definir o tamanho do pacote depois que uma conexão já tiver sido feita, o driver retornará SQLSTATE HY011 (o atributo não pode ser definido agora). |
| SQL_ATTR_QUIET_MODE (ODBC 2.0) | Um identificador de janela (HWND). Se o identificador da janela for um ponteiro nulo, o driver não exibirá nenhuma caixa de diálogo. Se o identificador da janela não for um ponteiro nulo, ele deverá ser o identificador da janela pai do aplicativo. Esse é o padrão. O driver usa esse identificador para exibir caixas de diálogo. Observação: o atributo de conexão SQL_ATTR_QUIET_MODE não se aplica às caixas de diálogo exibidas pelo SQLDriverConnect. |
| SQL_ATTR_TRACE (ODBC 1.0) | Um valor SQLUINTEGER informando ao Gerenciador de Driver se o rastreamento deve ser executado: SQL_OPT_TRACE_OFF = Rastreamento desativado (o padrão) SQL_OPT_TRACE_ON = Rastreamento ativado Quando o rastreamento está ativado, o Gerenciador de Driver grava cada chamada de função ODBC no arquivo de rastreamento. Observação: quando o rastreamento está ativado, o Gerenciador de Driver pode retornar SQLSTATE IM013 (erro de arquivo de rastreamento) de qualquer função. Um aplicativo especifica um arquivo de rastreamento com a opção SQL_ATTR_TRACEFILE. Se o arquivo já existir, o Gerenciador de Driver será anexado ao arquivo. Caso contrário, ele cria o arquivo. Se o rastreamento estiver ativado e nenhum arquivo de rastreamento tiver sido especificado, o Gerenciador de Driver gravará no arquivo SQL. LOG no diretório raiz. Um aplicativo pode definir a variável ODBCSharedTraceFlag para habilitar o rastreamento dinamicamente. O rastreamento é habilitado para todos os aplicativos ODBC em execução no momento. Se um aplicativo desativar o rastreamento, ele será desativado apenas para esse aplicativo. Se a palavra-chave Trace nas informações do sistema for definida como 1 quando um aplicativo chamar SQLAllocHandle com um HandleType de SQL_HANDLE_ENV, o rastreamento será habilitado para todos os identificadores. Ele é habilitado apenas para o aplicativo chamado SQLAllocHandle. Chamar SQLSetConnectAttr com um Atributo de SQL_ATTR_TRACE não exige que o argumento ConnectionHandle seja válido e não retornará SQL_ERROR se ConnectionHandle for NULL. Esse atributo se aplica a todas as conexões. |
| SQL_ATTR_TRACEFILE (ODBC 1.0) | Uma cadeia de caracteres terminada em nulo que contém o nome do arquivo de rastreamento. O valor padrão do atributo SQL_ATTR_TRACEFILE é especificado com a palavra-chave TraceFile nas informações do sistema. Para obter mais informações, consulte Subchave ODBC. Chamar SQLSetConnectAttr com um atributo de SQL_ATTR_TRACEFILE não exige que o argumento ConnectionHandle seja válido e não retornará SQL_ERROR se ConnectionHandle for inválido. Esse atributo se aplica a todas as conexões. |
| SQL_ATTR_TRANSLATE_LIB (ODBC 1.0) | Uma cadeia de caracteres terminada em nulo que contém o nome de uma biblioteca que contém as funções SQLDriverToDataSource e SQLDataSourceToDriver que o driver acessa para executar tarefas como conversão de conjunto de caracteres. Essa opção só poderá ser especificada se o driver tiver se conectado à fonte de dados. A configuração desse atributo persistirá entre as conexões. Para obter mais informações sobre como converter 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 de sinalizador de 32 bits que é passado para a DLL de conversão. Esse atributo só poderá ser especificado se o driver tiver se conectado à fonte de dados. Para obter informações sobre como converter 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 conexão atual. Um aplicativo deve chamar SQLEndTran para confirmar ou reverter todas as transações abertas em uma conexão, antes de chamar SQLSetConnectAttr com essa opção. Os valores válidos para ValuePtr podem ser determinados chamando SQLGetInfo com InfoType igual a SQL_TXN_ISOLATION_OPTIONS. Para obter uma descrição dos níveis de isolamento de transação, consulte a descrição do tipo de informação SQL_DEFAULT_TXN_ISOLATION em SQLGetInfo e Níveis de Isolamento de Transação. |
[1] Essas funções podem ser chamadas de forma assíncrona somente se o descritor for um descritor de implementação, não um descritor de aplicativo.
Exemplo de código
Consulte SQLConnect.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Alocando um identificador | Função SQLAllocHandle |
| Retornando a configuração de um atributo de conexão | Função SQLGetConnectAttr |