Função SQLSetConnectAttr
Conformidade
Versão introduzida: ODBC 3.0 Standards Compliance: ISO 92
Resumo
SQLSetConnectAttr define atributos que regem aspectos das conexões.
Observação
Para obter mais informações sobre como o Gerenciador de Driver mapeia essa função para 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
ConnectionHandle
[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 o comprimento fixo, consulte a seção Comentários para obter detalhes.
Stringlength
[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.
Retornos
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 Identificador 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 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 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 foi conectado falhou antes da conclusão do processamento da função. |
| 24.000 | 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 DTC (conexão de transação distribuída) 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 do 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 nenhum 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ções | (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 retornados SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes de os dados serem 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 de os dados serem enviados para todos os parâmetros ou colunas de dados em execução. (DM) SQLBrowseConnect foi chamado para o ConnectionHandle e retornou 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 foi SQL_ATTR_TRACEFILE ou SQL_ATTR_TRANSLATE_LIB e ValuePtr era uma cadeia de caracteres vazia. |
| HY090 | Comprimento de buffer ou cadeia de caracteres inválida | (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íncronas. |
| HY117 | A conexão é suspensa devido ao estado de transação desconhecido. 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 de Driver-Aware não podem ser habilitados ao mesmo tempo | Para obter mais informações, consulte Pooling 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 era compatível com o driver. |
| HYT01 | O tempo limite da conexão expirou | O período de tempo limite da conexão expirou antes da fonte de dados responder à 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 dá suporte a essa 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 tradução especificada para a conexão. Esse erro só pode ser retornado 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 é compatível com o 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 no momento e a versão do ODBC em que foram introduzidos são mostrados na tabela posteriormente nesta seção; espera-se que mais atributos sejam definidos para aproveitar diferentes fontes de dados. Um intervalo de atributos é reservado 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 de 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 da instrução.
Os drivers ODBC 3*.x* só precisarão dar suporte a essa funcionalidade se precisarem trabalhar 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, confira Mapeamento SQLSetConnectOption no Apêndice G: Diretrizes do 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 que o aplicativo se conecte a um driver diferente na conexão.
Alguns atributos de conexão só podem ser definidos antes de uma conexão ser feita; outras podem ser definidas somente depois que uma conexão for 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. 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 | [1] |
| SQL_ATTR_ASYNC_DBC_EVENT | Você pode usar o |
| SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE | [4] |
| SQL_ATTR_ASYNC_DBC_PCALLBACK | Você pode usar o |
| SQL_ATTR_ASYNC_DBC_PCONTEXT | Você pode usar o |
| SQL_ATTR_ASYNC_ENABLE | [2] |
| SQL_ATTR_AUTO_IPD | Você pode usar o |
| SQL_ATTR_AUTOCOMMIT | [5] |
| SQL_ATTR_CONNECTION_DEAD | After (após) |
| SQL_ATTR_CONNECTION_TIMEOUT | Você pode usar o |
| SQL_ATTR_CURRENT_CATALOG | [1] |
| SQL_ATTR_DBC_INFO_TOKEN | After (após) |
| SQL_ATTR_ENLIST_IN_DTC | After (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 | After (após) |
| SQL_ATTR_TRANSLATE_OPTION | After (após) |
| SQL_ATTR_TXN_ISOLATION | [3] |
[1] SQL_ATTR_ACCESS_MODE e SQL_ATTR_CURRENT_CATALOG podem ser definidos antes ou depois da conexão, dependendo do driver. No entanto, aplicativos interoperáveis os definem antes de se conectarem porque alguns drivers não dão suporte à alteração após a conexão.
[2] SQL_ATTR_ASYNC_ENABLE deve ser definido antes de haver uma instrução ativa.
[3] SQL_ATTR_TXN_ISOLATION só poderá 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 de 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íncronas, 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 é indicado 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 de ValuePtr |
|---|---|
| SQL_ATTR_ACCESS_MODE (ODBC 1.0) | Um valor SQLUINTEGER. SQL_MODE_READ_ONLY é usado pelo driver ou pela fonte de dados como um indicador de que a conexão não é necessária para dar suporte a instruções SQL que fazem com que as atualizações ocorram. 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 à 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. Nota: Não há suporte para o método de notificação com a biblioteca de cursores. Um aplicativo receberá uma mensagem de erro se tentar habilitar a biblioteca de cursores por meio de SQLSetConnectAttr, quando o método de notificação estiver 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 Sondagem). SQL_ASYNC_DBC_ENABLE_ON = Habilitar operação assíncrona para funções relacionadas à conexão especificadas. SQL_ASYNC_DBC_ENABLE_OFF = (Padrão) Desabilitar operação assíncrona para funções relacionadas à conexão especificadas. Definir SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE é sempre síncrono (ou seja, ele 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 = Habilitar 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ções 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 a população automática do IPD após uma chamada para SQLPrepare : SQL_TRUE = a população automática do IPD após uma chamada para SQLPrepare é compatível com o driver. SQL_FALSE = a população automática do IPD após uma chamada para SQLPrepare não tem suporte do driver. Os servidores que não dão 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 a população automática 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 manual ou de confirmação automática deve ser usado: SQL_AUTOCOMMIT_OFF = O driver usa o modo de confirmação manual e o aplicativo deve confirmar ou reverter transações explicitamente com SQLEndTran. SQL_AUTOCOMMIT_ON = O driver usa o modo de confirmação automática. Cada instrução é confirmada imediatamente após a execução. 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 alterar 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 fontes 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 nãoquery é executada ou quando o cursor é 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. Todo o lote pode ser tratado como uma unidade de confirmação automática ou cada instrução em um lote é tratada como uma unidade de confirmação automática. 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 de confirmação automática ou se cada instrução individual dentro do lote é confirmação automática. |
| 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 estará ativa. |
| SQL_ATTR_CONNECTION_TIMEOUT (ODBC 3.0) | Um valor SQLUINTEGER correspondente ao número de segundos a 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 expirar em uma situação não associada à execução ou logon da consulta. 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, em SQL Server, o catálogo é um banco de dados, portanto, o driver envia uma instrução USEdatabase 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 for 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 a configuração SQL_ATTR_DBC_INFO_TOKEN, a conexão obtida do pool será liberada. Em seguida, o Gerenciador de Driver tentará obter outra conexão do pool. Consulte Desenvolvendo Connection-Pool Reconhecimento 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 pelo Microsoft Component Services. Passe um objeto de transação OLE DTC que especifica 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 representa 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 de 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 depende 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 de 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 string 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 usa literalmente o que está 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, consulte Argumentos em funções de catálogo. |
| SQL_ATTR_ODBC_CURSORS (ODBC 2.0) | Um valor SQLULEN que especifica 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 no 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. Essa é a configuração padrão. Para obter mais informações sobre a biblioteca de cursores ODBC, consulte 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 um novo trabalho de desenvolvimento e planeje modificar aplicativos que atualmente usam esse recurso. 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 não dão suporte a essa opção ou só podem 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 de janela não for um ponteiro nulo, ele deverá ser o identificador de janela pai do aplicativo. Esse é o padrão. O driver usa esse identificador para exibir caixas de diálogo. Nota: 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 deseja executar o rastreamento: 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. Nota: 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 acrescentará ao arquivo. Caso contrário, ele criará o arquivo. Se o rastreamento estiver ativado e nenhum arquivo de rastreamento tiver sido especificado, o Gerenciador de Driver gravará no SQL do arquivo. FAÇA LOGOn 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 somente 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 está 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 conexões. Para obter mais informações sobre como traduzir dados, consulte Referência de função de DLLs de tradução e DLL de tradução. |
| SQL_ATTR_TRANSLATE_OPTION (ODBC 1.0) | Um valor de sinalizador de 32 bits que é passado para a DLL de tradução. Esse atributo só poderá ser especificado se o driver tiver se conectado à fonte de dados. Para obter informações sobre como traduzir 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 da transação, consulte a descrição do tipo de informações SQL_DEFAULT_TXN_ISOLATION em NÍVEIS de isolamentode transação e SQLGetInfo. |
[1] Essas funções só poderão ser chamadas de forma assíncrona 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 |
Consulte Também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de