Función SQLInstallDriverEx

Conformidad
Versión introducida: ODBC 3.0

Resumen
SQLInstallDriverEx agrega información sobre el controlador a la entrada Odbcinst.ini en la información del sistema e incrementa el usageCount del controlador en 1. Sin embargo, si ya existe una versión del controlador, pero el valor UsageCount del controlador no existe, el nuevo valor UsageCount se establece en 2.

Esta función no copia realmente ningún archivo. Es responsabilidad del programa de llamada copiar correctamente los archivos del controlador en el directorio de destino.

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

Sintaxis

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

Argumentos

lpszDriver
[Entrada] Descripción del controlador (normalmente el nombre del DBMS asociado) presentado a los usuarios en lugar del nombre del controlador físico. El argumento lpszDriver debe contener una lista doblemente terminada en null de pares de palabra clave-valor que describen el controlador. Para obtener más información sobre los pares de palabra clave-valor, vea Subclaves de especificación del controlador. Para obtener más información sobre la cadena terminada doblemente en null, vea Función ConfigDSN.

lpszPathIn
[Entrada] Ruta de acceso completa del directorio de destino de la instalación o un puntero nulo. Si lpszPathIn es un puntero nulo, los controladores se instalarán en el directorio del sistema.

lpszPathOut
[Salida] Ruta de acceso del directorio de destino donde se debe instalar el controlador. Si el controlador no se ha instalado anteriormente, lpszPathOut debe ser el mismo que lpszPathIn. Si el controlador se instaló anteriormente, lpszPathOut es la ruta de acceso de la instalación anterior.

cbPathOutMax
[Entrada] Longitud de lpszPathOut.

pcbPathOut
[Salida] Número total de bytes (excepto el carácter de terminación null) disponible 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 en cbPathOutMax menos el carácter de terminación null. El argumento pcbPathOut puede ser un puntero nulo.

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

ODBC_INSTALL_INQUIRY: pregunte dónde se puede instalar un controlador.

ODBC_INSTALL_COMPLETE: complete la solicitud de instalación.

lpdwUsageCount
[Salida] Recuento de uso del controlador 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 ejecuta correctamente, FALSE si se produce un error.

Diagnóstico

Cuando SQLInstallDriverEx 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 en el contexto de esta función.

*pfErrorCode	Error	Descripción
ODBC_ERROR_GENERAL_ERR	Error general del instalador	Error por el que no se produjo 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 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 lpszDriver contenía un error de sintaxis.
ODBC_ERROR_INVALID_PATH	Ruta de acceso de instalación no válida	El argumento lpszPathIn contenía una ruta de acceso no válida.
ODBC_ERROR_LOAD_LIBRARY_FAILED	No se pudo cargar el controlador ni la biblioteca de instalación del traductor	No se pudo cargar la biblioteca de configuración del controlador.
ODBC_ERROR_INVALID_PARAM_SEQUENCE	Secuencia de parámetros no válida	El argumento lpszDriver no contenía una lista de pares de palabra clave-valor.
ODBC_ERROR_USAGE_UPDATE_FAILED	No se pudo incrementar ni disminuir el recuento de uso de componentes	El instalador no pudo incrementar el número de uso del controlador.

Comentarios

El argumento lpszDriver es una lista de atributos en forma de pares de palabra clave-valor. Cada par finaliza con un byte nulo y toda la lista finaliza con un byte nulo. (Es decir, dos bytes NULL marcan el final de la lista). El formato de esta lista es el siguiente:

driver-desc\0Driver=driver-DLL-filename\0[Setup=setup-DLL-filename\0]

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

donde \0 es un byte nulo y driver-attr-keywordn es cualquier palabra clave de atributo de controlador. Las palabras clave deben aparecer en el orden especificado. Por ejemplo, supongamos que un controlador para archivos de texto con formato tiene archivos DLL independientes de configuración y controlador y puede usar archivos con las extensiones .txt y .csv. El argumento lpszDriver para este controlador puede ser el siguiente:

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

Supongamos que un controlador para SQL Server no tiene un archivo DLL de configuración independiente y no tiene ninguna palabra clave de atributo de controlador. El argumento lpszDriver para este controlador puede ser el siguiente:

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

Después de que SQLInstallDriverEx recupere información sobre el controlador del argumento lpszDriver , agrega la descripción del controlador a la sección [Controladores ODBC] de la entrada Odbcinst.ini en la información del sistema. A continuación, crea una sección titulada con la descripción del controlador y agrega las rutas de acceso completas del archivo DLL del controlador y el archivo DLL de instalación. Por último, devuelve la ruta de acceso del directorio de destino de la instalación, pero no copia los archivos del controlador en él. El programa de llamada debe copiar realmente los archivos de controlador en el directorio de destino.

SQLInstallDriverEx incrementa el recuento de uso de componentes para el controlador instalado en 1. Si ya existe una versión del controlador, pero el recuento de uso de componentes para el controlador 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 del controlador y mantener el recuento de uso de archivos. Si el archivo de controlador no se ha instalado anteriormente, el programa de instalación de la aplicación debe copiar el archivo en la ruta de acceso lpszPathIn y crear el recuento de uso de archivos. Si el archivo se instaló anteriormente, el programa de instalación simplemente incrementa el recuento de uso de archivos y devuelve la ruta de acceso de la instalación anterior en el argumento lpszPathOut .

Nota

Para obtener más información sobre los recuentos de uso de componentes y los recuentos de uso de archivos, consulte Recuento de uso.

Si la aplicación instaló anteriormente una versión anterior del archivo de controlador, el controlador debe desinstalarse y volver a instalarse para que el recuento de uso de componentes del controlador sea válido. Primero se debe llamar a SQLConfigDriver (con fRequest de ODBC_REMOVE_DRIVER) y, a continuación, se debe llamar a SQLRemoveDriver para disminuir el número de uso de componentes. A continuación, se debe llamar a SQLInstallDriverEx para reinstalar el controlador, lo que incrementa el número de uso de componentes. El programa de instalación de la aplicación debe reemplazar el archivo antiguo por el nuevo archivo. El recuento de uso de archivos seguirá siendo el mismo y cualquier otra aplicación que use el archivo de versión anterior ahora usará la versión más reciente.

Nota

Si el controlador se instaló anteriormente y se llama a SQLInstallDriverEx para instalar el controlador en un directorio diferente, la función devolverá TRUE, pero lpszPathOut incluirá el directorio donde el controlador ya estaba instalado. No incluirá el directorio especificado en el argumento lpszDriver .

La longitud de la ruta de acceso en lpszPathOut en SQLInstallDriverEx permite un proceso de instalación en dos fases, por lo que una aplicación puede determinar qué cbPathOutMax debe ser llamando a SQLInstallDriverEx con un fRequest del 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 SQLInstallDriverEx 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 SQLInstallDriverEx, debe establecer cbPathOutMax, que define el tamaño del almacenamiento para la ruta de acceso del directorio de destino, al valor _MAX_PATH, tal como se define en Stdlib.h, para evitar el truncamiento.

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

Después de llamar a SQLInstallDriverEx y el programa de instalación de la aplicación ha copiado el archivo de controlador (si es necesario), el archivo DLL de instalación del controlador debe llamar a SQLConfigDriver para establecer la configuración del controlador.

Funciones relacionadas

Para información acerca de	Vea
Instalación del Administrador de controladores	SQLInstallDriverManager