Função SQLInstallTranslatorEx

Conformidade
Versão introduzida: ODBC 3.0

Resumo
SQLInstallTranslatorEx adiciona informações sobre um tradutor à seção Odbcinst.ini das informações do sistema (chave do Registro HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\Tradutores ODBC).

A funcionalidade de SQLInstallTranslatorEx também pode ser acessada com ODBCCONF.EXE.

Sintaxe

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

Argumentos

lpszTranslator
[Entrada] Isso deve conter uma lista duplamente terminada em nulo de pares chave-valor que descrevem o tradutor. Para obter mais informações sobre a sintaxe do par palavra-chave-valor, consulte Subchaves de Especificação do Tradutor.

As palavras-chave Translator e Setup devem ser incluídas na cadeia de caracteres lpszTranslator . A DLL de tradução é listada com a palavra-chave Translator e a DLL de configuração do tradutor é listada com a palavra-chave Setup . Cada par é encerrado com um byte NULL e toda a lista é encerrada com um byte NULL. (Ou seja, dois bytes NULL marcam o final da lista.) O formato de lpszTranslator é o seguinte:

\0Translator=translator-DLL-filename\0[Setup=setup-DLL-filename\0]\0

lpszPathIn
[Entrada] Caminho completo de onde o tradutor deve ser instalado ou um ponteiro nulo. Se lpszPath for um ponteiro nulo, os tradutores serão instalados no diretório Sistema.

lpszPathOut
[Saída] O caminho do diretório de destino em que o tradutor deve ser instalado. Se o tradutor nunca tiver sido instalado, lpszPathOut será o mesmo que lpszPathIn. Se houver uma instalação anterior do tradutor, lpszPathOut será o caminho da instalação anterior.

cbPathOutMax
[Entrada] Comprimento de lpszPathOut.

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

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

ODBC_INSTALL_INQUIRY: consulte onde um tradutor pode ser instalado.

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

lpdwUsageCount
[Saída] A contagem de uso do tradutor após essa função ter sido chamada.

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

Retornos

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

Diagnósticos

Quando SQLInstallTranslatorEx 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 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 o argumento fRequest era ODBC_INSTALL_COMPLETE.
ODBC_ERROR_INVALID_REQUEST_TYPE	Tipo inválido de solicitação	O argumento fRequest não foi um dos seguintes: ODBC_INSTALL_INQUIRY ODBC_INSTALL_COMPLETE
ODBC_ERROR_INVALID_KEYWORD_VALUE	Pares de palavra-chave-valor inválidos	O argumento lpszTranslator 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_INVALID_PARAM_SEQUENCE	Sequência de parâmetro inválida	O argumento lpszTranslator não continha uma lista de pares chave-valor.
ODBC_ERROR_USAGE_UPDATE_FAILED	Não foi possível incrementar ou decrementar a contagem de uso de componentes do Registro	O instalador falhou ao incrementar a contagem de uso do tradutor.

Comentários

SQLInstallTranslatorEx fornece um mecanismo para instalar apenas o tradutor. Na verdade, essa função não copia nenhum arquivo. O programa de chamada é responsável por copiar os arquivos do tradutor.

SQLInstallTranslatorEx incrementa a contagem de uso do componente para o tradutor instalado em 1. Se uma versão do tradutor já existir, mas a contagem de uso do componente para o tradutor 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 de tradução e manter a contagem de uso de arquivos. Se o arquivo de tradução não tiver sido instalado anteriormente, o programa de instalação do aplicativo deverá copiar o arquivo ou arquivos e criar a contagem de uso de arquivos ou arquivos. Se o arquivo tiver sido instalado anteriormente, o programa de instalação simplesmente incrementará a contagem de uso de arquivos.

Se uma versão mais antiga do tradutor tiver sido instalada anteriormente pelo aplicativo, o tradutor deverá ser desinstalado e reinstalado para que a contagem de uso do componente tradutor seja válida. SQLRemoveTranslator deve ser chamado para diminuir a contagem de uso do componente e, em seguida, SQLInstallTranslatorEx deve ser chamado para incrementar a contagem de uso do componente. O programa de instalação do aplicativo deve substituir o arquivo ou arquivos antigos pelo novo arquivo. A contagem de uso de arquivos permanecerá a mesma, e outros aplicativos que usaram o arquivo de versão mais antigo agora usarão a versão mais recente.

O comprimento do caminho em lpszPathOut no SQLInstallTranslatorEx permite um processo de instalação em duas fases, para que um aplicativo possa determinar qual deve ser cbPathOutMax chamando SQLInstallTranslatorEx com um fRequest do modo ODBC_INSTALL_INQUIRY. Isso retornará o número total de bytes disponíveis no buffer pcbPathOut . SQLInstallTranslatorEx 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 nula.

Se você optar por não usar o modelo de duas fases para SQLInstallTranslatorEx, 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, SQLInstallTranslatorEx 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 retornar for maior ou igual a cbPathOutMax, com o resultado de que ocorre truncamento.

Funções relacionadas

Para obter informações sobre	Consulte
Retornando uma opção de tradução padrão	ConfigTranslator
Selecionando tradutores	SQLGetTranslator
Removendo tradutores	SQLRemoveTranslator