Compartilhar via

Função SQLConfigDriver

  • Artigo

Conformidade
Versão introduzida: ODBC 2.5

Resumo
SQLConfigDriver carrega a DLL de configuração de driver apropriada e chama a função ConfigDriver .

A funcionalidade do SQLConfigDriver também pode ser acessada com ODBCCONF.EXE.

Sintaxe

  
BOOL SQLConfigDriver(  
     HWND     hwndParent,  
     WORD     fRequest,  
     LPCSTR   lpszDriver,  
     LPCSTR   lpszArgs,  
     LPSTR    lpszMsg,  
     WORD     cbMsgMax,  
     WORD *   pcbMsgOut);

Argumentos

hwndParent
[Entrada] Identificador de janela pai. A função não exibirá nenhuma caixa de diálogo se o identificador for nulo.

fRequest
[Entrada] Tipo de solicitação. fRequest deve conter um dos seguintes valores:

ODBC_CONFIG_DRIVER: altera o tempo limite de pool de conexões usado pelo driver.

ODBC_INSTALL_DRIVER: instala um novo driver.

ODBC_REMOVE_DRIVER: remove um driver existente.

Essa opção também pode ser específica do driver, caso em que o fRequest para a primeira opção deve começar do ODBC_CONFIG_DRIVER_MAX+1. A fRequest para qualquer opção adicional também deve começar com um valor maior que ODBC_CONFIG_DRIVER_MAX+1.

lpszDriver
[Entrada] O nome do driver conforme registrado nas informações do sistema.

lpszArgs
[Entrada] Uma cadeia de caracteres terminada em nulo que contém argumentos para um fRequest específico do driver.

lpszMsg
[Saída] Uma cadeia de caracteres terminada em nulo que contém uma mensagem de saída da configuração do driver.

cbMsgMax
[Entrada] Comprimento de lpszMsg.

pcbMsgOut
[Saída] Número total de bytes disponíveis para retornar em lpszMsg. Se o número de bytes disponíveis para retornar for maior ou igual a cbMsgMax, a mensagem de saída em lpszMsg será truncada para cbMsgMax menos o caractere de terminação nula. O argumento pcbMsgOut pode ser um ponteiro nulo.

Retornos

A função retornará TRUE se for bem-sucedida, FALSE se falhar.

Diagnósticos

Quando SQLConfigDriver retorna FALSE, um valor *pfErrorCode associado pode ser obtido chamando SQLInstallerError. A tabela a seguir lista os valores *pfErrorCode que podem ser retornados por SQLInstallerError e explica cada um deles no contexto dessa função.

*pfErrorCode Erro Descrição
ODBC_ERROR_GENERAL_ERR Erro geral do instalador Ocorreu um erro para o qual não houve nenhum erro específico do instalador.
ODBC_ERROR_INVALID_BUFF_LEN Comprimento do buffer inválido O argumento lpszMsg era inválido.
ODBC_ERROR_INVALID_HWND Identificador de janela inválido O argumento hwndParent era inválido.
ODBC_ERROR_INVALID_REQUEST_TYPE Tipo inválido de solicitação O argumento fRequest não foi um dos seguintes:

ODBC_INSTALL_DRIVER ODBC_REMOVE_DRIVER

O argumento fRequest era uma opção específica do driver que era menor ou igual a ODBC_CONFIG_DRIVER_MAX.
ODBC_ERROR_INVALID_NAME Nome do driver ou tradutor inválido O argumento lpszDriver era inválido. Não foi possível encontrá-lo no registro.
ODBC_ERROR_INVALID_KEYWORD_VALUE Pares de palavra-chave-valor inválidos O argumento lpszArgs continha um erro de sintaxe.
ODBC_ERROR_REQUEST_FAILED Falha na solicitação O instalador não pôde executar a operação solicitada pelo argumento fRequest . Falha na chamada para ConfigDriver .
ODBC_ERROR_LOAD_LIBRARY_FAILED Não foi possível carregar o driver ou a biblioteca de configuração do tradutor Não foi possível carregar a biblioteca de configuração do driver.
ODBC_ERROR_OUT_OF_MEM Memória insuficiente O instalador não pôde executar a função devido à falta de memória.

Comentários

SQLConfigDriver permite que um aplicativo chame a rotina ConfigDriver de um driver sem precisar saber o nome e carregar a DLL de configuração específica do driver. Um programa de instalação chama essa função depois que a DLL de instalação do driver é instalada. O programa de chamada deve estar ciente de que essa função pode não estar disponível para todos os drivers. Nesse caso, o programa de chamada deve continuar sem erros.

Opções do Driver-Specific

Um aplicativo pode solicitar recursos específicos do driver expostos pelo driver usando o argumento fRequest . A fRequest para a primeira opção será ODBC_CONFIG_DRIVER_MAX+1 e opções adicionais serão incrementadas em 1 desse valor. Todos os argumentos exigidos pelo driver para essa função devem ser fornecidos em uma cadeia de caracteres terminada em nulo passada no argumento lpszArgs . Os drivers que fornecem essa funcionalidade devem manter uma tabela de opções específicas do driver. As opções devem estar totalmente documentadas na documentação do driver. Os gravadores de aplicativos que usam opções específicas do driver devem estar cientes de que esse uso tornará o aplicativo menos interoperável.

Definindo o tempo limite do pool de conexões

As propriedades de tempo limite do pool de conexões podem ser definidas quando você define a configuração do driver. SQLConfigDriver é chamado com um fRequest de ODBC_CONFIG_DRIVER e lpszArgs definidos como CPTimeout. CPTimeout determina o período de tempo em que uma conexão pode permanecer no pool de conexões sem ser usada. Quando o tempo limite expira, a conexão é fechada e removida do pool. O tempo limite padrão é de 60 segundos.

Quando SQLConfigDriver é chamado com fRequest definido como ODBC_INSTALL_DRIVER ou ODBC_REMOVE_DRIVER, o Gerenciador de Driver carrega a DLL de configuração de driver apropriada e chama a função ConfigDriver . Quando SQLConfigDriver é chamado com um fRequest de ODBC_CONFIG_DRIVER, todo o processamento é executado no instalador ODBC, para que a DLL de instalação do driver não precise ser carregada.

Mensagens

Uma rotina de configuração de driver pode enviar uma mensagem de texto para um aplicativo como cadeias de caracteres terminadas em nulo no buffer lpszMsg . A mensagem será truncada para cbMsgMax menos o caractere de terminação nula pela função ConfigDriver se for maior ou igual a caracteres cbMsgMax .

Para obter informações sobre Consulte
Adicionar, modificar ou remover um driver ConfigDriver(na DLL de instalação)
Removendo a fonte de dados padrão SQLRemoveDefaultDataSource