Función SQLInstallTranslatorEx

Conformidad
Versión introducida: ODBC 3.0

Resumen
SQLInstallTranslatorEx agrega información sobre un traductor a la sección Odbcinst.ini de la información del sistema (HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\clave del Registro de Translators ODBC).

También se puede acceder a la funcionalidad de SQLInstallTranslatorEx con ODBCCONF.EXE.

Sintaxis

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

Argumentos

lpszTranslator
[Entrada] Debe contener una lista doble terminada en null de pares de palabra clave-valor que describen el traductor. Para obtener más información sobre la sintaxis del par de palabra clave-valor, consulte Subclaves de especificación de Translator.

Las palabras clave Translator y Setup deben incluirse en la cadena lpszTranslator . El archivo DLL de traducción aparece con la palabra clave Translator y el archivo DLL de instalación del traductor aparece con la palabra clave Setup . Cada par finaliza con un byte NULL y toda la lista finaliza con un byte NULL. (Es decir, dos bytes NULL marcan el final de la lista). El formato de lpszTranslator es el siguiente:

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

lpszPathIn
[Entrada] Ruta de acceso completa de donde se va a instalar el traductor o un puntero nulo. Si lpszPath es un puntero nulo, los traductores se instalarán en el directorio Del sistema.

lpszPathOut
[Salida] Ruta de acceso del directorio de destino donde se debe instalar el traductor. Si el traductor nunca se ha instalado, lpszPathOut es el mismo que lpszPathIn. Si existe una instalación previa del traductor, lpszPathOut es la ruta de acceso de la instalación anterior.

cbPathOutMax
[Entrada] Longitud de lpszPathOut.

pcbPathOut
[Salida] Número total de bytes disponibles para devolver en lpszPathOut. Si el número de bytes disponibles para devolver es mayor o igual que cbPathOutMax, la ruta de acceso de salida de lpszPathOut se trunca a pcbPathOutMax menos el carácter de terminación null. El argumento pcbPathOut puede ser un puntero nulo.

fRequest
[Entrada] Tipo de solicitud. fRequest debe contener uno de los siguientes valores:

ODBC_INSTALL_INQUIRY: Consulte dónde se puede instalar un traductor.

ODBC_INSTALL_COMPLETE: complete la solicitud de instalación.

lpdwUsageCount
[Salida] Recuento de uso del traductor después de llamar a esta función.

Las aplicaciones no deben establecer el recuento de uso. ODBC mantendrá este recuento.

Devoluciones

La función devuelve TRUE si se realiza correctamente, FALSE si se produce un error.

Diagnóstico

Cuando SQLInstallTranslatorEx devuelve FALSE, se puede obtener un valor *pfErrorCode asociado llamando a SQLInstallerError. En la tabla siguiente se enumeran los valores *pfErrorCode que SQLInstallerError puede devolver y explica cada uno de ellos en el contexto de esta función.

*pfErrorCode	Error	Descripción
ODBC_ERROR_GENERAL_ERR	Error general del instalador	Se produjo un error para el que no hubo ningún error de instalador específico.
ODBC_ERROR_INVALID_BUFF_LEN	Longitud de búfer no válida	El argumento lpszPathOut no era lo suficientemente grande como para contener la ruta de acceso de salida. El búfer contiene la ruta de acceso truncada. El argumento cbPathOutMax era 0 y el argumento fRequest se ODBC_INSTALL_COMPLETE.
ODBC_ERROR_INVALID_REQUEST_TYPE	Tipo de solicitud no válido	El argumento fRequest no era uno de los siguientes: ODBC_INSTALL_INQUIRY ODBC_INSTALL_COMPLETE
ODBC_ERROR_INVALID_KEYWORD_VALUE	Pares de palabra clave-valor no válidos	El argumento lpszTranslator contenía un error de sintaxis.
ODBC_ERROR_INVALID_PATH	Ruta de instalación no válida	El argumento lpszPathIn contenía una ruta de acceso no válida.
ODBC_ERROR_INVALID_PARAM_SEQUENCE	Secuencia de parámetros no válida	El argumento lpszTranslator no contenía una lista de pares de palabra clave-valor.
ODBC_ERROR_USAGE_UPDATE_FAILED	No se pudo incrementar ni disminuir el número de uso de componentes del Registro	El instalador no pudo incrementar el número de uso del traductor.

Comentarios

SQLInstallTranslatorEx proporciona un mecanismo para instalar solo el traductor. Esta función no copia realmente ningún archivo. El programa de llamada es responsable de copiar los archivos de traductor.

SQLInstallTranslatorEx incrementa el recuento de uso de componentes para el traductor instalado en 1. Si ya existe una versión del traductor, pero el recuento de uso de componentes para el traductor no existe, el nuevo valor de recuento de uso de componentes se establece en 2.

El programa de instalación de la aplicación es responsable de copiar físicamente el archivo de traductor y mantener el recuento de uso de archivos. Si el archivo translator no se ha instalado previamente, el programa de instalación de la aplicación debe copiar el archivo o los archivos y crear el recuento de uso de archivos o archivos. Si el archivo se instaló anteriormente, el programa de instalación simplemente incrementa el recuento de uso de archivos.

Si la aplicación instaló previamente una versión anterior del traductor, el traductor se debe desinstalar y volver a instalar para que el recuento de uso del componente del traductor sea válido. Se debe llamar a SQLRemoveTranslator para reducir el recuento de uso de componentes y, a continuación, se debe llamar a SQLInstallTranslatorEx para incrementar el número de uso de componentes. El programa de instalación de la aplicación debe reemplazar el archivo o los archivos antiguos por el nuevo archivo. El recuento de uso de archivos seguirá siendo el mismo y otras aplicaciones que usaron el archivo de versión anterior ahora usarán la versión más reciente.

La longitud de la ruta de acceso en lpszPathOut en SQLInstallTranslatorEx permite un proceso de instalación en dos fases, por lo que una aplicación puede determinar qué cbPathOutMax debe ser llamando a SQLInstallTranslatorEx con un fRequest de modo ODBC_INSTALL_INQUIRY. Esto devolverá el número total de bytes disponibles en el búfer pcbPathOut . A continuación, se puede llamar a SQLInstallTranslatorEx con un fRequest de ODBC_INSTALL_COMPLETE y el argumento cbPathOutMax establecido en el valor del búfer pcbPathOut, además del carácter de terminación null.

Si decide no usar el modelo de dos fases para SQLInstallTranslatorEx, debe establecer cbPathOutMax, que define el tamaño del almacenamiento para la ruta de acceso del directorio de destino, al valor _MAX_PATH, tal y como se define en Stdlib.h, para evitar el truncamiento.

Cuando fRequest se ODBC_INSTALL_COMPLETE, SQLInstallTranslatorEx no permite que lpszPathOut sea NULL (o cbPathOutMax sea 0). Si fRequest es ODBC_INSTALL_COMPLETE, se devuelve FALSE cuando el número de bytes disponibles para devolver es mayor o igual que cbPathOutMax, con el resultado de que se produce el truncamiento.

Funciones relacionadas

Para información acerca de	Vea
Devolver una opción de traducción predeterminada	ConfigTranslator
Selección de traductores	SQLGetTranslator
Eliminación de traductores	SQLRemoveTranslator