Función ConfigDSN

Conformidad
Versión introducida: ODBC 1.0

Resumen
ConfigDSN agrega, modifica o elimina orígenes de datos de la información del sistema. Puede solicitar al usuario información de conexión. Puede estar en el archivo DLL del controlador o en un archivo DLL de instalación independiente.

Sintaxis

  
BOOL ConfigDSN(  
     HWND     hwndParent,  
     WORD     fRequest,  
     LPCSTR   lpszDriver,  
     LPCSTR   lpszAttributes);  

Argumentos

hwndParent
[Entrada] Identificador de ventana principal. La función no mostrará ningún cuadro de diálogo si el identificador es NULL.

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

ODBC_ADD_DSN: agregue un nuevo origen de datos.

ODBC_CONFIG_DSN: configure (modifique) un origen de datos existente.

ODBC_REMOVE_DSN: quite un origen de datos existente.

lpszDriver
[Entrada] Descripción del controlador (normalmente el nombre del DBMS asociado) presentado a los usuarios en lugar del nombre del controlador físico.

lpszAttributes
[Entrada] Lista duplicada de atributos terminada en NULL en forma de pares de palabra clave-valor. Para obtener más información, vea "Comentarios".

Devoluciones

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

Diagnóstico

Cuando ConfigDSN devuelve FALSE, se publica un valor *pfErrorCode asociado en el búfer de errores del instalador mediante una llamada a SQLPostInstallerError y se puede obtener 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_INVALID_HWND	Identificador de ventana no válido	El argumento hwndParent no era válido.
ODBC_ERROR_INVALID_KEYWORD_VALUE	Pares de palabra clave-valor no válidos	El argumento lpszAttributes contenía un error de sintaxis.
ODBC_ERROR_INVALID_NAME	Nombre de controlador o traductor no válido	El argumento lpszDriver no era válido. No se encontró en el registro.
ODBC_ERROR_INVALID_REQUEST_TYPE	Tipo de solicitud no válido	El argumento fRequest no era uno de los siguientes: ODBC_ADD_DSN ODBC_CONFIG_DSN ODBC_REMOVE_DSN
ODBC_ERROR_REQUEST_FAILED	Error de solicitud	No se pudo realizar la operación solicitada por el argumento fRequest .
ODBC_ERROR_DRIVER_SPECIFIC	Error específico del controlador o traductor	Error específico del controlador para el que no hay ningún error de instalador ODBC definido. El argumento SzError de una llamada a la función SQLPostInstallerError debe contener el mensaje de error específico del controlador.

Comentarios

ConfigDSN recibe información de conexión del archivo DLL del instalador como 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 NULOs marcan el final de la lista). No se permiten espacios alrededor del signo igual en el par palabra clave-valor. ConfigDSN puede aceptar palabras clave que no son palabras clave válidas para SQLBrowseConnect y SQLDriverConnect. ConfigDSN no admite necesariamente todas las palabras clave válidas para SQLBrowseConnect y SQLDriverConnect. (ConfigDSN no acepta la palabra clave DRIVER ). Las palabras clave usadas por la función ConfigDSN deben admitir todas las opciones necesarias para volver a crear el origen de datos mediante la característica de instalación AUTOMÁTICA del instalador. Cuando los usos de los valores configDSN y los valores de cadena de conexión son los mismos, se deben usar las mismas palabras clave.

Como en SQLBrowseConnect y SQLDriverConnect, las palabras clave y sus valores no deben contener []{}(),;? *=!@ caracteres y el valor de la palabra clave DSN no puede constar solo de espacios en blanco. Debido a la gramática del Registro, las palabras clave y los nombres de origen de datos no pueden contener el carácter de barra diagonal inversa (\).

ConfigDSN debe llamar a SQLValidDSN para comprobar la longitud del nombre del origen de datos y para comprobar que no se incluyen caracteres no válidos en el nombre. Si el nombre del origen de datos es mayor que SQL_MAX_DSN_LENGTH o incluye caracteres no válidos, SQLValidDSN devuelve un error y ConfigDSN devuelve un error. SQLWriteDSNToIni también comprueba la longitud del nombre del origen de datos.

Por ejemplo, para configurar un origen de datos que requiera un identificador de usuario, una contraseña y un nombre de base de datos, una aplicación de instalación podría pasar los siguientes pares de palabra clave-valor:

DSN=Personnel Data\0UID=Smith\0PWD=Sesame\0DATABASE=Personnel\0\0  

Para obtener más información sobre estas palabras clave, vea SQLDriverConnect y la documentación de cada controlador.

Para mostrar un cuadro de diálogo, hwndParent no debe ser NULL.

Agregar un origen de datos

Si se pasa un nombre de origen de datos a ConfigDSN en lpszAttributes, ConfigDSN comprueba que el nombre es válido. Si el nombre del origen de datos coincide con un nombre de origen de datos existente y hwndParent es null, ConfigDSN sobrescribe el nombre existente. Si coincide con un nombre existente y hwndParent no es null, ConfigDSN solicita al usuario que sobrescriba el nombre existente.

Si lpszAttributes contiene suficiente información para conectarse a un origen de datos, ConfigDSN puede agregar el origen de datos o mostrar un cuadro de diálogo con el que el usuario puede cambiar la información de conexión. Si lpszAttributes no contiene suficiente información para conectarse a un origen de datos, ConfigDSN debe determinar la información necesaria; Si hwndParent no es null, muestra un cuadro de diálogo para recuperar la información del usuario.

Si ConfigDSN muestra un cuadro de diálogo, debe mostrar cualquier información de conexión que se le pase en lpszAttributes. En concreto, si se le pasó un nombre de origen de datos, ConfigDSN muestra ese nombre, pero no permite al usuario cambiarlo. ConfigDSN puede proporcionar valores predeterminados para la información de conexión que no se le pasa en lpszAttributes.

Si ConfigDSN no puede obtener información de conexión completa para un origen de datos, devuelve FALSE.

Si ConfigDSN puede obtener información de conexión completa para un origen de datos, llama a SQLWriteDSNToIni en el archivo DLL del instalador para agregar la nueva especificación del origen de datos al archivo Odbc.ini (o registro). SQLWriteDSNToIni agrega el nombre del origen de datos a la sección [Orígenes de datos ODBC], crea la sección especificación del origen de datos y agrega la palabra clave DRIVER con la descripción del controlador como valor. ConfigDSN llama a SQLWritePrivateProfileString en el archivo DLL del instalador para agregar cualquier palabra clave y valores adicionales que use el controlador.

Modificar un origen de datos

Para modificar un origen de datos, se debe pasar un nombre de origen de datos a ConfigDSN en lpszAttributes. ConfigDSN comprueba que el nombre del origen de datos está en el archivo Odbc.ini (o registro).

Si hwndParent es null, ConfigDSN usa la información de lpszAttributes para modificar la información en el archivo Odbc.ini (o registro). Si hwndParent no es null, ConfigDSN muestra un cuadro de diálogo con la información de lpszAttributes; para obtener información no en lpszAttributes, utiliza información de la información del sistema. El usuario puede modificar la información antes de que ConfigDSN la almacene en la información del sistema.

Si se cambió el nombre del origen de datos, ConfigDSN llama primero a SQLRemoveDSNFromIni en el archivo DLL del instalador para quitar la especificación del origen de datos existente del archivo Odbc.ini (o registro). A continuación, sigue los pasos de la sección anterior para agregar la nueva especificación del origen de datos. Si no se cambió el nombre del origen de datos, ConfigDSN llama a SQLWritePrivateProfileString en el archivo DLL del instalador para realizar cualquier otro cambio. Es posible que ConfigDSN no elimine ni cambie el valor de la palabra clave Driver.

Eliminar un origen de datos

Para eliminar un origen de datos, se debe pasar un nombre de origen de datos a ConfigDSN en lpszAttributes. ConfigDSN comprueba que el nombre del origen de datos está en el archivo Odbc.ini (o registro). A continuación, llama a SQLRemoveDSNFromIni en el archivo DLL del instalador para quitar el origen de datos.

Nota

Si escribe una versión Unicode de esta rutina, se debe llamar ConfigDSNW, con argumentos LPCWSTR en lugar de LPCSTR.

Funciones relacionadas

Para información acerca de	Vea
Agregar, modificar o quitar un origen de datos	SQLConfigDataSource
Obtención de un valor del archivo Odbc.ini o del registro	SQLGetPrivateProfileString
Eliminación del origen de datos predeterminado	SQLRemoveDefaultDataSource
Quitar un nombre de origen de datos de Odbc.ini (o registro)	SQLRemoveDSNFromIni
Agregar un nombre de origen de datos a Odbc.ini (o registro)	SQLWriteDSNToIni
Escribir un valor en el archivo Odbc.ini o en el Registro	SQLWritePrivateProfileString