Função SQLInstallDriverEx

Compatibilidade
Versão introduzida: ODBC 3.0

Resumo
SQLInstallDriverEx adiciona informações sobre o driver à entrada Odbcinst.ini nas informações do sistema e incrementa o UsageCount do driver em 1. No entanto, se uma versão do driver já existir, mas o valor UsageCount do driver não existir, o novo valor UsageCount será definido como 2.

Esta função não copia nenhum arquivo. É responsabilidade do programa de chamada copiar os arquivos do driver para o diretório de destino corretamente.

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

Sintaxe

  
BOOL SQLInstallDriverEx(  
     LPCSTR    lpszDriver,  
     LPCSTR    lpszPathIn,  
     LPSTR     lpszPathOut,  
     WORD      cbPathOutMax,  
     WORD *    pcbPathOut,  
     WORD      fRequest,  
     LPDWORD   lpdwUsageCount);  

Argumentos

lpszDriver
[Entrada] A descrição do driver (geralmente o nome do DBMS associado) apresentada aos usuários em vez do nome do driver físico. O argumento lpszDriver deve conter uma lista duplamente terminada em nulo de pares de valores-chave que descrevem o driver. Para obter mais informações sobre pares de palavra-chave-valor, consulte Subchaves de especificação de driver. Para obter mais informações sobre a cadeia de caracteres duplamente terminada em nulo, consulte Função ConfigDSN.

lpszPathIn
[Entrada] Caminho completo do diretório de destino da instalação ou um ponteiro nulo. Se lpszPathIn for um ponteiro nulo, os drivers serão instalados no diretório do sistema.

lpszPathOut
[Saída] Caminho do diretório de destino em que o driver deve ser instalado. Se o driver não tiver sido instalado anteriormente, lpszPathOut deverá ser o mesmo que lpszPathIn. Se o driver foi instalado anteriormente, lpszPathOut é o caminho da instalação anterior.

cbPathOutMax
[Entrada] Comprimento de lpszPathOut.

pcbCaminhoSaída
[Saída] Número total de bytes (excluindo o caractere de terminação nula) disponíveis para retornar em lpszPathOut. Se o número de bytes disponíveis para retorno for maior ou igual a cbPathOutMax, o caminho de saída em lpszPathOut será truncado para cbPathOutMax menos o caractere de terminação nula. O argumento pcbPathOut pode ser um ponteiro nulo.

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

ODBC_INSTALL_INQUIRY: Informe-se sobre onde um driver pode ser instalado.

ODBC_INSTALL_COMPLETE: Conclua a solicitação de instalação.

lpdwUsageCount
[Saída] A contagem de uso do driver depois que essa função for chamada.

Os aplicativos não devem definir a contagem de uso. O ODBC manterá essa contagem.

Devoluções

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

Diagnósticos

Quando SQLInstallDriverEx 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.

*pfCódigo de erro	Erro	Descrição
ODBC_ERROR_GENERAL_ERR	Erro geral do instalador	Ocorreu um erro para o qual não houve erro específico do instalador.
ODBC_ERROR_INVALID_BUFF_LEN	Comprimento do buffer inválido	O argumento lpszPathOut não era grande o suficiente para conter o caminho de saída. O buffer contém o caminho truncado. O argumento cbPathOutMax era 0 e fRequest era ODBC_INSTALL_COMPLETE.
ODBC_ERROR_INVALID_REQUEST_TYPE	Tipo de solicitação inválido	O argumento fRequest não foi um dos seguintes: ODBC_INSTALL_INQUIRY ODBC_INSTALL_COMPLETE
ODBC_ERROR_INVALID_KEYWORD_VALUE	Pares de valores-chave inválidos	O argumento lpszDriver continha um erro de sintaxe.
ODBC_ERROR_INVALID_PATH	Caminho de instalação inválido	O argumento lpszPathIn continha um caminho inválido.
ODBC_ERROR_LOAD_LIBRARY_FAILED	Não foi possível carregar a biblioteca de configuração do driver ou do tradutor	A biblioteca de configuração do driver não pôde ser carregada.
ODBC_ERROR_INVALID_PARAM_SEQUENCE	Sequência de parâmetros inválida	O argumento lpszDriver não continha uma lista de pares de valores-palavra-chave.
ODBC_ERROR_USAGE_UPDATE_FAILED	Não foi possível incrementar ou diminuir a contagem de uso do componente	O instalador falhou ao incrementar a contagem de uso do driver.

Comentários

O argumento lpszDriver é uma lista de atributos na forma de pares de valores-chave. Cada par é encerrado com um byte nulo e toda a lista é encerrada com um byte nulo. (Ou seja, dois bytes nulos marcam o final da lista.) O formato desta lista é o seguinte:

driver-desc\ 0Driver=driver-DLL-filename\0[Configuração=de configuração-DLL-filename\0]

[driver-attr-keyword1=value1\0][driver-attr-keyword2=value2\0]...\0

onde \0 é um byte nulo e driver-attr-keywordn é qualquer palavra-chave de atributo de driver. As palavras-chave devem aparecer na ordem especificada. Por exemplo, suponha que um driver para arquivos de texto formatados tenha driver separado e DLLs de configuração e possa usar arquivos com as extensões .txt e .csv. O argumento lpszDriver para esse driver pode ser o seguinte:

Text\0Driver=TEXT.DLL\0Setup=TXTSETUP.DLL\0FileUsage=1\0  
FileExtns=*.txt,*.csv\0\0  

Suponha que um driver para SQL Server não tenha uma DLL de instalação separada e não tenha nenhuma palavra-chave de atributo de driver. O argumento lpszDriver para esse driver pode ser o seguinte:

SQL Server\0Driver=SQLSRVR.DLL\0\0  

Depois que SQLInstallDriverEx recupera informações sobre o driver do argumento lpszDriver , ele adiciona a descrição do driver à seção [ODBC Drivers] da entrada Odbcinst.ini nas informações do sistema. Em seguida, ele cria uma seção intitulada com a descrição do driver e adiciona os caminhos completos da DLL do driver e da DLL de instalação. Por fim, ele retorna o caminho do diretório de destino da instalação, mas não copia os arquivos do driver para ele. O programa de chamada deve realmente copiar os arquivos de driver para o diretório de destino.

SQLInstallDriverEx incrementa a contagem de uso do componente para o driver instalado em 1. Se uma versão do driver já existir, mas a contagem de uso do componente para o driver não existir, o novo valor de contagem de uso do componente será definido como 2.

O programa de instalação do aplicativo é responsável por copiar fisicamente o arquivo do driver e manter a contagem de uso do arquivo. Se o arquivo de driver não tiver sido instalado anteriormente, o programa de instalação do aplicativo deverá copiar o arquivo no caminho lpszPathIn e criar a contagem de uso do arquivo. Se o arquivo tiver sido instalado anteriormente, o programa de instalação simplesmente incrementará a contagem de uso do arquivo e retornará o caminho da instalação anterior no argumento lpszPathOut .

Observação

Para obter mais informações sobre contagens de uso de componentes e contagens de uso de arquivos, consulte Contagem de uso.

Se uma versão mais antiga do arquivo de driver tiver sido instalada anteriormente pelo aplicativo, o driver deverá ser desinstalado e reinstalado, para que a contagem de uso do componente de driver seja válida. SQLConfigDriver (com um fRequest de ODBC_REMOVE_DRIVER) deve ser chamado primeiro e, em seguida , SQLRemoveDriver deve ser chamado para diminuir a contagem de uso do componente. SQLInstallDriverEx deve ser chamado para reinstalar o driver, incrementando a contagem de uso do componente. O programa de instalação do aplicativo deve substituir o arquivo antigo pelo novo. A contagem de uso do arquivo permanecerá a mesma e qualquer outro aplicativo que usava o arquivo da versão mais antiga agora usará a versão mais recente.

Observação

Se o driver tiver sido instalado anteriormente e SQLInstallDriverEx for chamado para instalar o driver em um diretório diferente, a função retornará TRUE, mas lpszPathOut incluirá o diretório em que o driver já foi instalado. Ele não incluirá o diretório inserido no argumento lpszDriver .

O comprimento do caminho em lpszPathOut em SQLInstallDriverEx permite um processo de instalação em duas fases, para que um aplicativo possa determinar o que cbPathOutMax deve ser chamando SQLInstallDriverEx com um fRequest do modo ODBC_INSTALL_INQUIRY. Isso retornará o número total de bytes disponíveis no buffer pcbPathOut . SQLInstallDriverEx pode ser chamado com um fRequest de ODBC_INSTALL_COMPLETE e o argumento cbPathOutMax definido como o valor no buffer pcbPathOut , além do caractere de terminação nulo.

Se você optar por não usar o modelo de duas fases para SQLInstallDriverEx, deverá definir cbPathOutMax, que define o tamanho do armazenamento para o caminho do diretório de destino, para o valor _MAX_PATH, conforme definido em Stdlib.h, para evitar truncamento.

Quando fRequest é ODBC_INSTALL_COMPLETE, SQLInstallDriverEx não permite que lpszPathOut seja NULL (ou cbPathOutMax seja 0). Se fRequest for ODBC_INSTALL_COMPLETE, FALSE será retornado quando o número de bytes disponíveis para retorno for maior ou igual a cbPathOutMax, com o resultado de que ocorre truncamento.

Depois que SQLInstallDriverEx tiver sido chamado e o programa de instalação do aplicativo tiver copiado o arquivo de driver (se necessário), a DLL de instalação do driver deverá chamar SQLConfigDriver para definir a configuração do driver.

Funções relacionadas

Para obter informações sobre	Consulte
Instalando o Gerenciador de Driver	SQLInstallDriverManager