Função SQLDriverConnect

Artigo
05/23/2023

Conformidade
Versão introduzida: ODBC 1.0 Standards Compliance: ODBC

Resumo
SQLDriverConnect é uma alternativa ao SQLConnect. Ele dá suporte a fontes de dados que exigem mais informações de conexão do que os três argumentos no SQLConnect, caixas de diálogo para solicitar ao usuário todas as informações de conexão e fontes de dados que não são definidas nas informações do sistema. Para obter mais informações, consulte Conectando-se com SQLDriverConnect.

Sintaxe

  
SQLRETURN SQLDriverConnect(  
     SQLHDBC         ConnectionHandle,  
     SQLHWND         WindowHandle,  
     SQLCHAR *       InConnectionString,  
     SQLSMALLINT     StringLength1,  
     SQLCHAR *       OutConnectionString,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLength2Ptr,  
     SQLUSMALLINT    DriverCompletion);

Argumentos

ConnectionHandle
[Entrada] Identificador de conexão.

Windowhandle
[Entrada] Identificador de janela. O aplicativo poderá passar o identificador da janela pai, se aplicável, ou um ponteiro nulo se o identificador de janela não for aplicável ou o SQLDriverConnect não apresentará nenhuma caixa de diálogo.

InConnectionString
[Entrada] Uma cadeia de conexão completa (consulte a sintaxe em "Comentários"), uma cadeia de conexão parcial ou uma cadeia de caracteres vazia.

StringLength1
[Entrada] Comprimento de *InConnectionString, em caracteres se a cadeia de caracteres for Unicode ou bytes se a cadeia de caracteres for ANSI ou DBCS.

OutConnectionString
[Saída] Ponteiro para um buffer para a cadeia de conexão concluída. Após a conexão bem-sucedida com a fonte de dados de destino, esse buffer contém a cadeia de conexão concluída. Os aplicativos devem alocar pelo menos 1.024 caracteres para esse buffer.

Se OutConnectionString for NULL, StringLength2Ptr ainda retornará o número total de caracteres (excluindo o caractere de terminação nula para dados de caractere) disponíveis para retornar no buffer apontado por OutConnectionString.

BufferLength
[Entrada] Comprimento do buffer *OutConnectionString , em caracteres.

StringLength2Ptr
[Saída] Ponteiro para um buffer no qual retornar o número total de caracteres (excluindo o caractere de terminação nula) disponível para retornar em *OutConnectionString. Se o número de caracteres disponíveis para retornar for maior ou igual a BufferLength, a cadeia de conexão concluída em *OutConnectionString será truncada para BufferLength menos o comprimento de um caractere de terminação nula.

DriverCompletion
[Entrada] Sinalizador que indica se o Driver Manager ou o driver devem solicitar mais informações de conexão:

SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED ou SQL_DRIVER_NOPROMPT.

(Para obter informações adicionais, consulte "Comentários".

Retornos

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_STILL_EXECUTING.

Diagnósticos

Quando SQLDriverConnect retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um fHandleType de SQL_HANDLE_DBC e um hHandle de ConnectionHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLDriverConnect 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.

SQLSTATE	Erro	Descrição
01000	Aviso geral	Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.)
01004	Dados de cadeia de caracteres, truncados à direita	O buffer *OutConnectionString não era grande o suficiente para retornar toda a cadeia de conexão, portanto, a cadeia de conexão foi truncada. O comprimento da cadeia de conexão não confiável é retornado em *StringLength2Ptr. (A função retorna SQL_SUCCESS_WITH_INFO.)
01S00	Atributo de cadeia de conexão inválida	Uma palavra-chave de atributo inválida foi especificada na cadeia de conexão (InConnectionString), mas o driver conseguiu se conectar à fonte de dados de qualquer maneira. (A função retorna SQL_SUCCESS_WITH_INFO.)
01S02	Valor da opção alterado	O driver não deu suporte ao valor especificado apontado pelo argumento ValuePtr em SQLSetConnectAttr e substituiu um valor semelhante. (A função retorna SQL_SUCCESS_WITH_INFO.)
01S08	Erro ao salvar o arquivo DSN	A cadeia de caracteres em InConnectionString continha uma palavra-chave FILESN* , mas o arquivo .dsn não foi salvo. (A função retorna SQL_SUCCESS_WITH_INFO.)
01S09	Palavra-chave inválida	(DM) A cadeia de caracteres em InConnectionString continha uma palavra-chave SAVEFILE* , mas não uma palavra-chave DRIVER ou FILEDSN . (A função retorna SQL_SUCCESS_WITH_INFO.)
08001	O cliente não consegue estabelecer a conexão	O driver não pôde estabelecer uma conexão com a fonte de dados.
08002	Nome da conexão em uso	(DM) O ConnectionHandle especificado já havia sido usado para estabelecer uma conexão com uma fonte de dados e a conexão ainda estava aberta.
08004	O servidor rejeitou a conexão	A fonte de dados rejeitou o estabelecimento da conexão por motivos definidos pela implementação.
08S01	Falha no link de comunicação	O link de comunicação entre o driver e a fonte de dados à qual o driver estava tentando se conectar falhou antes que a função SQLDriverConnect concluísse o processamento.
28000	Especificação de autorização inválida	O identificador de usuário ou a cadeia de caracteres de autorização, ou ambos, conforme especificado na cadeia de conexão (InConnectionString), violaram as restrições definidas pela fonte de dados.
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 szMessageText* descreve o erro e sua causa.
HY000	Erro geral: dsn de arquivo inválido	(DM) A cadeia de caracteres em *InConnectionString continha uma palavra-chave FILESN, mas o nome do arquivo .dsn não foi encontrado.
HY000	Erro geral: não é possível criar o buffer de arquivos	(DM) A cadeia de caracteres em *InConnectionString continha uma palavra-chave FILESN, mas o arquivo .dsn era ilegível.
HY001	Erro de alocação de memória	O Gerenciador de Driver não pôde alocar a memória necessária para dar suporte à execução ou à conclusão da função SQLDriverConnect . 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 foi chamada e, antes de concluir a execução, a função SQLCancelHandle foi chamada no ConnectionHandle e, em seguida, a função SQLDriverConnect foi chamada novamente no ConnectionHandle. Ou, a função SQLDriverConnect foi chamada e, antes de concluir a execução, SQLCancelHandle foi chamado no ConnectionHandle de um thread diferente em um aplicativo multithread.
HY010	Erro de sequência de funções	(DM) Outra função de execução assíncrona (não SQLDriverConnect) foi chamada para ConnectionHandle e ainda estava em execução quando a função SQLDriverConnect foi chamada.
HY013	Erro de gerenciamento de memória	A chamada de função SQLDriverConnect 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 insuficiente.
HY090	Comprimento de buffer ou cadeia de caracteres inválido	(DM) O valor especificado para o argumento StringLength1 era menor que 0 e não era igual a SQL_NTS. (DM) O valor especificado para o argumento BufferLength era menor que 0.
HY092	Identificador de atributo/opção inválido	(DM) O argumento DriverCompletion foi SQL_DRIVER_PROMPT e o argumento WindowHandle era um ponteiro nulo.
HY110	Conclusão inválida do driver	(DM) O valor especificado para o argumento DriverCompletion não era igual a SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED ou SQL_DRIVER_NOPROMPT. (DM) O pool de conexões foi habilitado e o valor especificado para o argumento DriverCompletion não era igual a SQL_DRIVER_NOPROMPT.
HYC00	Recurso opcional não implementado	O driver não dá suporte à versão do comportamento ODBC que o aplicativo solicitou.
HYT00	Tempo limite esgotado	O período de tempo limite de logon expirou antes da conexão com a fonte de dados ser concluída. O período de tempo limite é definido por meio de SQLSetConnectAttr, SQL_ATTR_LOGIN_TIMEOUT.
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 correspondente ao nome da fonte de dados especificado não dá suporte à função .
IM002	Fonte de dados não encontrada e nenhum driver padrão especificado	(DM) O nome da fonte de dados especificado na cadeia de conexão (InConnectionString) não foi encontrado nas informações do sistema e não havia nenhuma especificação de driver padrão. Não foi possível encontrar a fonte de dados ODBC e as informações padrão do driver nas informações do sistema.
IM003	Não foi possível carregar o driver especificado	(DM) O driver listado na especificação da fonte de dados nas informações do sistema ou especificado pela palavra-chave DRIVER não foi encontrado ou não pôde ser carregado por algum outro motivo.
IM004	Falha no SQLAllocHandle do driver no SQL_HANDLE_ENV	(DM) Durante o SQLDriverConnect, o Gerenciador de Driver chamou a função SQLAllocHandle do driver com um fHandleType de SQL_HANDLE_ENV e o driver retornou um erro.
IM005	O SQLAllocHandle do driver no SQL_HANDLE_DBC falhou.	(DM) Durante o SQLDriverConnect, o Gerenciador de Driver chamou a função SQLAllocHandle do driver com um fHandleType de SQL_HANDLE_DBC e o driver retornou um erro.
IM006	Falha no SQLSetConnectAttr do driver	(DM) Durante o SQLDriverConnect, o Gerenciador de Driver chamou a função SQLSetConnectAttr do driver e o driver retornou um erro.
IM007	Nenhuma fonte de dados ou driver especificado; caixa de diálogo proibida	Nenhum nome de fonte de dados ou driver foi especificado na cadeia de conexão e DriverCompletion foi SQL_DRIVER_NOPROMPT.
IM008	Falha na caixa de diálogo	O driver tentou exibir sua caixa de diálogo de logon e falhou. WindowHandle era um ponteiro nulo e DriverCompletion não era SQL_DRIVER_NO_PROMPT.
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 fonte de dados ou para a conexão.
IM010	Nome da fonte de dados muito longo	(DM) O valor do atributo para a palavra-chave DSN era maior que SQL_MAX_DSN_LENGTH caracteres.
IM011	Nome do driver muito longo	(DM) O valor do atributo para a palavra-chave DRIVER tinha mais de 255 caracteres.
IM012	Erro de sintaxe da palavra-chave DRIVER	(DM) O par palavra-chave-valor da palavra-chave DRIVER continha um erro de sintaxe. (DM) A cadeia de caracteres em InConnectionString continha uma palavra-chave FILESN* , mas o arquivo .dsn não continha uma palavra-chave DRIVER ou uma palavra-chave DSN .
IM014	O DSN especificado contém uma incompatibilidade de arquitetura entre o driver e o aplicativo	(DM) O aplicativo de 32 bits usa um DSN que se conecta a um driver de 64 bits; ou vice-versa.
IM015	Falha no SQLDriverConnect do driver no SQL_HANDLE_DBC_INFO_HANDLE	Se um driver retornar SQL_ERROR, o Gerenciador de Driver retornará SQL_ERROR ao aplicativo e a conexão falhará. Para obter mais informações sobre SQL_HANDLE_DBC_INFO_TOKEN, consulte Developing Connection-Pool Awareness in an ODBC Driver.
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	Quando o driver não dá suporte à notificação assíncrona, você não pode definir SQL_ATTR_ASYNC_DBC_EVENT ou SQL_ATTR_ASYNC_DBC_RETCODE_PTR.

Comentários

Uma cadeia de conexão tem a seguinte sintaxe:

connection-string ::= empty-string[;] | attribute[;] | atributo; cadeia de conexão

empty-string ::=attribute ::= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}]

attribute-keyword ::= DSN | UID | PWD | driver-defined-attribute-keyword

attribute-value ::= character-string

driver-defined-attribute-keyword ::= identifier

em que character-string tem zero ou mais caracteres; O identificador tem um ou mais caracteres; attribute-keyword não diferencia maiúsculas de minúsculas; attribute-value pode diferenciar maiúsculas de minúsculas; e o valor da palavra-chave DSN não consiste apenas em espaços em branco.

Devido à cadeia de conexão e à gramática do arquivo de inicialização, palavras-chave e valores de atributo que contêm os caracteres []{}();? *=!@ não entre chaves deve ser evitado. O valor da palavra-chave DSN não pode consistir apenas em espaços em branco e não deve conter espaços em branco à esquerda. Devido à gramática das informações do sistema, palavras-chave e nomes de fonte de dados não podem conter o caractere de barra invertida (\).

Os aplicativos não precisam adicionar chaves ao redor do valor do atributo após a palavra-chave DRIVER , a menos que o atributo contenha um ponto e vírgula (;), nesse caso, as chaves são necessárias. Se o valor do atributo que o driver recebe incluir chaves, o driver não deve removê-los, mas deve fazer parte da cadeia de conexão retornada.

Um valor de cadeia de conexão ou DSN entre chaves ({}) que contém qualquer um dos caracteres []{}();? *=!@ é passado intacto para o driver. No entanto, ao usar esses caracteres em uma palavra-chave, o Gerenciador de Driver retorna um erro ao trabalhar com DSNs de arquivo, mas passa a cadeia de conexão para o driver para cadeias de conexão regulares. Evite usar chaves inseridas em um valor de palavra-chave.

A cadeia de conexão pode incluir qualquer número de palavras-chave definidas pelo driver. Como a palavra-chave DRIVER não usa informações das informações do sistema, o driver deve definir palavras-chave suficientes para que um driver possa se conectar a uma fonte de dados usando apenas as informações na cadeia de conexão. (Para obter mais informações, confira "Diretrizes de driver", mais adiante nesta seção.) O driver define quais palavras-chave são necessárias para se conectar à fonte de dados.

A tabela a seguir descreve os valores de atributo das palavras-chave DSN, FILEDSN, DRIVER, UID, PWD e SAVEFILE .

Palavra-chave	Descrição do valor do atributo
DSN	Nome de uma fonte de dados, conforme retornado por SQLDataSources ou pela caixa de diálogo fontes de dados do SQLDriverConnect.
FILEDSN	Nome de um arquivo .dsn do qual uma cadeia de conexão será criada para a fonte de dados. Essas fontes de dados são chamadas de fontes de dados de arquivo.
DRIVER	Descrição do driver conforme retornado pela função SQLDrivers . Por exemplo, Rdb ou SQL Server.
UID	Uma ID de usuário.
PWD	A senha correspondente à ID de usuário ou uma cadeia de caracteres vazia se não houver senha para a ID de usuário (PWD=;).
SAVEFILE	O nome do arquivo de um arquivo .dsn no qual os valores de atributo de palavras-chave usados na criação da conexão atual e bem-sucedida devem ser salvos.

Para obter informações sobre como um aplicativo escolhe uma fonte de dados ou driver, consulte Escolhendo uma fonte de dados ou driver.

Se alguma palavra-chave for repetida na cadeia de conexão, o driver usará o valor associado à primeira ocorrência da palavra-chave. Se as palavras-chave DSN e DRIVER forem incluídas na mesma cadeia de conexão, o Gerenciador de Driver e o driver usarão qualquer palavra-chave exibida primeiro.

As palavras-chave FILEDSN e DSN são mutuamente exclusivas: qualquer palavra-chave exibida primeiro é usada e a que aparece em segundo é ignorada. As palavras-chave FILEDSN e DRIVER , por outro lado, não são mutuamente exclusivas. Se qualquer palavra-chave aparecer em uma cadeia de conexão com FILESN, o valor do atributo da palavra-chave na cadeia de conexão será usado em vez do valor do atributo da mesma palavra-chave no arquivo .dsn.

Se a palavra-chave FILESN for usada, as palavras-chave especificadas em um arquivo .dsn serão usadas para criar uma cadeia de conexão. (Para obter mais informações, confira "Fontes de dados de arquivo", mais adiante nesta seção.) A palavra-chave UID é opcional; um arquivo .dsn pode ser criado apenas com a palavra-chave DRIVER . A palavra-chave PWD não é armazenada em um arquivo .dsn. O diretório padrão para salvar e carregar um arquivo .dsn será uma combinação do caminho especificado por CommonFileDir em HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ Windows\CurrentVersion e "ODBC\DataSources". (Se CommonFileDir fosse "C:\Arquivos de Programas\Arquivos Comuns", o diretório padrão seria "C:\Arquivos de Programas\Arquivos Comuns\ODBC\Fontes de Dados".)

Observação

Um arquivo .dsn pode ser manipulado diretamente chamando as funções SQLReadFileDSN e SQLWriteFileDSN na DLL do instalador.

Se a palavra-chave SAVEFILE for usada, os valores de atributo das palavras-chave usadas na criação da conexão atual e bem-sucedida serão salvos como um arquivo .dsn com o nome do valor do atributo da palavra-chave SAVEFILE . A palavra-chave SAVEFILE deve ser usada em conjunto com a palavra-chave DRIVER , a palavra-chave FILEDSN ou ambas, ou a função retorna SQL_SUCCESS_WITH_INFO com SQLSTATE 01S09 (palavra-chave inválida). A palavra-chave SAVEFILE deve aparecer antes da palavra-chave DRIVER na cadeia de conexão ou os resultados serão indefinidos.

Diretrizes do Gerenciador de Driver

O Gerenciador de Driver constrói uma cadeia de conexão para passar para o driver no argumento InConnectionString da função SQLDriverConnect do driver. O Gerenciador de Driver não modifica o argumento InConnectionString passado para ele pelo aplicativo.

A ação do Gerenciador de Driver baseia-se no valor do argumento DriverCompletion :

SQL_DRIVER_PROMPT: se a cadeia de conexão não contiver a palavra-chave DRIVER, DSN ou FILESN , o Gerenciador de Driver exibirá a caixa de diálogo Fontes de Dados. Ele constrói uma cadeia de conexão com base no nome da fonte de dados retornado pela caixa de diálogo e quaisquer outras palavras-chave passadas para ela pelo aplicativo. Se o nome da fonte de dados retornado pela caixa de diálogo estiver vazio, o Gerenciador de Driver especificará o par chave-valor DSN=Default. (Essa caixa de diálogo não exibirá uma fonte de dados com o nome "Padrão".)
SQL_DRIVER_COMPLETE ou SQL_DRIVER_COMPLETE_REQUIRED: se a cadeia de conexão especificada pelo aplicativo incluir a palavra-chave DSN , o Gerenciador de Driver copiará a cadeia de conexão especificada pelo aplicativo. Caso contrário, ele executa as mesmas ações que quando DriverCompletion é SQL_DRIVER_PROMPT.
SQL_DRIVER_NOPROMPT: o Gerenciador de Driver copia a cadeia de conexão especificada pelo aplicativo.

Se a cadeia de conexão especificada pelo aplicativo contiver a palavra-chave DRIVER , o Gerenciador de Driver copiará a cadeia de conexão especificada pelo aplicativo.

Usando a cadeia de conexão construída, o Gerenciador de Driver determina qual driver usar, conecta-se a esse driver e passa a cadeia de conexão que construiu para o driver; para obter mais informações sobre a interação do Gerenciador de Driver e do driver, consulte a seção "Comentários" na Função SQLConnect. Se a cadeia de conexão não contiver a palavra-chave DRIVER , o Gerenciador de Driver determinará qual driver usar da seguinte maneira:

Se a cadeia de conexão contiver a palavra-chave DSN , o Gerenciador de Driver recuperará o driver associado à fonte de dados das informações do sistema.
Se a cadeia de conexão não contiver a palavra-chave DSN ou a fonte de dados não for encontrada, o Gerenciador de Driver recuperará o driver associado à fonte de dados Padrão das informações do sistema. (Para obter mais informações, consulte Subchave Padrão.) O Gerenciador de Driver altera o valor da palavra-chave DSN na cadeia de conexão para "DEFAULT".
Se a palavra-chave DSN na cadeia de conexão estiver definida como "DEFAULT", o Gerenciador de Driver recuperará o driver associado à fonte de dados Padrão das informações do sistema.
Se a fonte de dados não for encontrada e a fonte de dados Padrão não for encontrada, o Gerenciador de Driver retornará SQL_ERROR com SQLSTATE IM002 (fonte de dados não encontrada e nenhum driver padrão especificado).

Fontes de dados do arquivo

Se a cadeia de conexão especificada pelo aplicativo na chamada para SQLDriverConnect contiver a palavra-chave FILESN e essa palavra-chave não for substituída pela palavra-chave DSN ou DRIVER , o Gerenciador de Driver criará uma cadeia de conexão usando as informações no arquivo .dsn e o argumento InConnectionString . O Gerenciador de Driver continua da seguinte maneira:

Verifica se o nome do arquivo .dsn é válido. Caso contrário, ele retornará SQL_ERROR com SQLSTATE IM014 (nome inválido do DSN do arquivo). Se o nome do arquivo for uma cadeia de caracteres vazia ("") e SQL_DRIVER_NOPROMPT não for especificado, a caixa de diálogo Abrir Arquivo será exibida. Se o nome do arquivo contiver um caminho válido, mas nenhum nome de arquivo ou um nome de arquivo inválido e SQL_DRIVER_NOPROMPT não for especificado, a caixa de diálogo Abrir Arquivo será exibida com o diretório atual definido como aquele especificado no nome do arquivo. Se o nome do arquivo for uma cadeia de caracteres vazia ("") ou o nome do arquivo contiver um caminho válido, mas nenhum nome de arquivo ou um nome de arquivo inválido e SQL_DRIVER_NOPROMPT for especificado, SQL_ERROR será retornado com SQLSTATE IM014 (nome inválido do arquivo DSN).
Lê todas as palavras-chave na seção [ODBC] do arquivo .dsn. Se a palavra-chave DRIVER não estiver presente, ela retornará SQL_ERROR com SQLSTATE IM012 (erro de sintaxe da palavra-chave driver), exceto quando o arquivo .dsn for incompartível e, portanto, conterá apenas a palavra-chave DSN .

Se a fonte de dados do arquivo for incompartilhada, o Gerenciador de Driver lerá o valor da palavra-chave DSN e se conectará conforme necessário à fonte de dados do usuário ou do sistema apontada pela fonte de dados de arquivo não compartilhada. As etapas 3 a 5 não são executadas.
Constrói uma cadeia de conexão para o driver. A cadeia de conexão do driver é a união das palavras-chave especificadas no arquivo .dsn e as especificadas na cadeia de conexão do aplicativo original. As regras para a construção da cadeia de conexão do driver em que as palavras-chave se sobrepõem são as seguintes:
- Se a palavra-chave DRIVER existir na cadeia de conexão do aplicativo e os drivers especificados pelas palavras-chave DRIVER não forem os mesmos no arquivo .dsn e na cadeia de conexão do aplicativo, as informações do driver no arquivo .dsn serão ignoradas e as informações do driver na cadeia de conexão do aplicativo serão usadas. Se os drivers especificados pela palavra-chave DRIVER forem os mesmos no arquivo .dsn e na cadeia de conexão do aplicativo, em que todas as palavras-chave se sobrepõem, as especificadas na cadeia de conexão do aplicativo terão precedência sobre as especificadas no arquivo .dsn.
- Na nova cadeia de conexão, a palavra-chave FILEDSN é eliminada.
Carrega o driver examinando a entrada do Registro HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\<Nome> do Driver\Driver em <que o Nome> do Driver é especificado pela palavra-chave DRIVER .
Passa ao driver a nova cadeia de conexões.

Para obter exemplos de arquivos .dsn, consulte Conectando-se usando fontes de dados de arquivo.

Palavra-chave SAVEFILE

Se a cadeia de conexão especificada pelo aplicativo contiver a palavra-chave SAVEFILE , o Gerenciador de Driver salvará a cadeia de conexão em um arquivo .dsn. O Gerenciador de Driver continua da seguinte maneira:

Verifica se o nome do arquivo .dsn incluído como o valor do atributo da palavra-chave SAVEFILE é válido. Caso contrário, ele retornará SQL_ERROR com SQLSTATE IM014 (nome inválido do DSN do arquivo). A validade do nome do arquivo é determinada pelas regras de nomenclatura padrão do sistema. Se o nome do arquivo for uma cadeia de caracteres vazia ("") e o argumento DriverCompletion não for SQL_DRIVER_NOPROMPT, o nome do arquivo será válido. Se o nome do arquivo já existir, se DriverCompletion for SQL_DRIVER_NOPROMPT, o arquivo será substituído. Se DriverCompletion for SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE ou SQL_DRIVER_COMPLETE_REQUIRED, uma caixa de diálogo solicitará que o usuário especifique se o arquivo deve ser substituído. Se Não for inserido, a caixa de diálogo Salvar Arquivo será exibida.
Se o driver retornar SQL_SUCCESS e o nome do arquivo não for uma cadeia de caracteres vazia, o Gerenciador de Driver gravará as informações de conexão retornadas no argumento OutConnectionString no arquivo especificado com o formato especificado na seção "Cadeias de Conexão" anteriormente nesta seção.
Se o driver retornar SQL_SUCCESS e o nome do arquivo for uma cadeia de caracteres vazia (""), o Gerenciador de Driver chamará a caixa de diálogo comum File-Save com o hwnd especificado e gravará as informações de conexão retornadas em OutConnectionString no arquivo especificado na caixa de diálogo comum File-Save com o formato especificado na seção "Cadeias de Conexão" anteriormente nesta seção.
Se o driver retornar SQL_SUCCESS, ele retornará o argumento OutConnectionString que contém a cadeia de conexão para o aplicativo.
Se o driver retornar SQL_SUCCESS_WITH_INFO ou SQL_ERROR, o Gerenciador de Driver retornará o SQLSTATE para o aplicativo.

Diretrizes de driver

O driver verifica se a cadeia de conexão passada para ela pelo Gerenciador de Driver contém a palavra-chave DSN ou DRIVER . Se a cadeia de conexão contiver a palavra-chave DRIVER , o driver não poderá recuperar informações sobre a fonte de dados das informações do sistema. Se a cadeia de conexão contiver a palavra-chave DSN ou não contiver a palavra-chave DSN ou DRIVER , o driver poderá recuperar informações sobre a fonte de dados das informações do sistema da seguinte maneira:

Se a cadeia de conexão contiver a palavra-chave DSN , o driver recuperará as informações da fonte de dados especificada.
Se a cadeia de conexão não contiver a palavra-chave DSN , a fonte de dados especificada não for encontrada ou a palavra-chave DSN for definida como "DEFAULT", o driver recuperará as informações para a fonte de dados Padrão.

O driver usa todas as informações que recupera das informações do sistema para aumentar as informações passadas para ele na cadeia de conexão. Se as informações nas informações do sistema duplicarem as informações na cadeia de conexão, o driver usará as informações na cadeia de conexão.

Com base no valor de DriverCompletion, o driver solicita ao usuário informações de conexão, como a ID de usuário e a senha, e se conecta à fonte de dados:

SQL_DRIVER_PROMPT: o driver exibe uma caixa de diálogo, usando os valores da cadeia de conexão e informações do sistema (se houver) como valores iniciais. Quando o usuário sai da caixa de diálogo, o driver se conecta à fonte de dados. Ele também constrói uma cadeia de conexão com base no valor da palavra-chave DSN ou DRIVER em *InConnectionString e as informações retornadas da caixa de diálogo. Ele coloca essa cadeia de conexão no buffer *OutConnectionString .
SQL_DRIVER_COMPLETE ou SQL_DRIVER_COMPLETE_REQUIRED: se a cadeia de conexão contiver informações suficientes e essas informações estiverem corretas, o driver se conectará à fonte de dados e copiará *InConnectionString para *OutConnectionString. Se alguma informação estiver ausente ou incorreta, o driver executará as mesmas ações que quando DriverCompletion estiver SQL_DRIVER_PROMPT, exceto que, se DriverCompletion for SQL_DRIVER_COMPLETE_REQUIRED, o driver desabilitará os controles para obter informações não necessárias para se conectar à fonte de dados.
SQL_DRIVER_NOPROMPT: se a cadeia de conexão contiver informações suficientes, o driver se conectará à fonte de dados e copiará *InConnectionString para *OutConnectionString. Caso contrário, o driver retornará SQL_ERROR para SQLDriverConnect.

Na conexão bem-sucedida com a fonte de dados, o driver também define *StringLength2Ptr para o comprimento da cadeia de conexão de saída que está disponível para retornar em *OutConnectionString.

Se o usuário cancelar uma caixa de diálogo apresentada pelo Gerenciador de Driver ou pelo driver, SQLDriverConnect retornará SQL_NO_DATA.

Para obter informações sobre como o Gerenciador de Driver e o driver interagem durante o processo de conexão, consulte Função SQLConnect.

Se um driver der suporte a SQLDriverConnect, a seção de palavra-chave do driver das informações do sistema para o driver deverá conter a palavra-chave ConnectFunctions com o segundo caractere definido como "Y".

Conectando quando o pool de conexões está habilitado

O pool de conexões permite que um aplicativo reutilize uma conexão que já foi criada. Quando SQLDriverConnect é chamado, o Gerenciador de Driver tenta fazer a conexão usando uma conexão que faz parte de um pool de conexões em um ambiente designado para pool de conexões. Para obter mais informações sobre o pool de conexões, consulte Função SQLConnect.

Um aplicativo pode definir SQL_ATTR_RESET_CONNECTION antes de chamar SQLDisconnect em uma conexão em que o pooling está habilitado. Para obter mais informações, consulte Função SQLSetConnectAttr.

As seguintes restrições se aplicam quando um aplicativo chama SQLDriverConnect para se conectar a uma conexão em pool:

Nenhum processamento de pool de conexões é executado quando a palavra-chave SAVEFILE é especificada na cadeia de conexão.
Se o pool de conexões estiver habilitado, SQLDriverConnect só poderá ser chamado com um argumento DriverCompletion de SQL_DRIVER_NOPROMPT; se SQLDriverConnect for chamado com qualquer outro DriverCompletion, SQLSTATE HY110 (conclusão inválida do driver) será retornado.

Atributos de conexão

O atributo de conexão SQL_ATTR_LOGIN_TIMEOUT, definido usando SQLSetConnectAttr, define o número de segundos para aguardar a conclusão de uma solicitação de logon com uma conexão bem-sucedida pelo driver antes de retornar ao aplicativo. Se o usuário for solicitado a concluir a cadeia de conexão, um período de espera para cada solicitação de logon começará quando o driver iniciar o processo de conexão.

O driver abre a conexão no modo de acesso SQL_MODE_READ_WRITE por padrão. Para definir o modo de acesso como SQL_MODE_READ_ONLY, o aplicativo deve chamar SQLSetConnectAttr com o atributo SQL_ATTR_ACCESS_MODE antes de chamar SQLDriverConnect.

Se uma biblioteca de tradução padrão for especificada nas informações do sistema para a fonte de dados, o driver a carregará. Uma biblioteca de tradução diferente pode ser carregada chamando SQLSetConnectAttr com o atributo SQL_ATTR_TRANSLATE_LIB. Uma opção de tradução pode ser especificada chamando SQLSetConnectAttr com a opção SQL_ATTR_TRANSLATE_OPTION.

Para obter mais informações, consulte Conectando-se com SQLDriverConnect.

// SQLDriverConnect_ref.cpp  
// compile with: odbc32.lib user32.lib  
#include <windows.h>  
#include <sqlext.h>  
  
int main() {  
   SQLHENV henv;  
   SQLHDBC hdbc;  
   SQLHSTMT hstmt;  
   SQLRETURN retcode;  
  
   SQLCHAR OutConnStr[255];  
   SQLSMALLINT OutConnStrLen;  
  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
  
   // Allocate environment handle  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
  
   // Set the ODBC version environment attribute  
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
      retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
      // Allocate connection handle  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
         retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
  
         // Set login timeout to 5 seconds  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
            SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
            retcode = SQLDriverConnect( // SQL_NULL_HDBC  
               hdbc,   
               desktopHandle,   
               (SQLCHAR*)"driver=SQL Server",   
               _countof("driver=SQL Server"),  
               OutConnStr,  
               255,   
               &OutConnStrLen,  
               SQL_DRIVER_PROMPT );  
  
            // Allocate statement handle  
            if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {                 
               retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);   
  
               // Process data  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
                  SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
               }  
  
               SQLDisconnect(hdbc);  
            }  
  
            SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
         }  
      }  
      SQLFreeHandle(SQL_HANDLE_ENV, henv);  
   }  
}

Confira também Exemplo de Programa ODBC.

Para obter informações sobre	Consulte
Alocando um identificador	Função SQLAllocHandle
Descobrir e enumerar valores necessários para se conectar a uma fonte de dados	Função SQLBrowseConnect
Conectando-se a uma fonte de dados	Função SQLConnect
Desconectando-se de uma fonte de dados	Função SQLDisconnect
Retornando descrições e atributos do driver	Função SQLDrivers
Liberando um identificador	Função SQLFreeHandle
Configurando um atributo de conexão	Função SQLSetConnectAttr

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC

Compartilhar via

Função SQLDriverConnect

Sintaxe

Argumentos

Retornos

Diagnósticos

Comentários

Diretrizes do Gerenciador de Driver

Fontes de dados do arquivo

Palavra-chave SAVEFILE

Diretrizes de driver

Conectando quando o pool de conexões está habilitado

Atributos de conexão

Consulte Também

Comentários

Recursos adicionais

Compartilhar via

Função SQLDriverConnect

Sintaxe

Argumentos

Retornos

Diagnósticos

Comentários

Diretrizes do Gerenciador de Driver

Fontes de dados do arquivo

Palavra-chave SAVEFILE

Diretrizes de driver

Conectando quando o pool de conexões está habilitado

Atributos de conexão

Funções relacionadas

Consulte Também

Comentários

Recursos adicionais