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 |