Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Conformidad
Versión introducida: Cumplimiento de Normas ODBC 1.0: ODBC
Resumen
SQLDriverConnect es una alternativa a SQLConnect. Soporta fuentes de datos que requieren más información de conexión que los tres argumentos de SQLConnect, cuadros de diálogo para pedir al usuario toda la información de conexión y fuentes de datos que no están definidas en la información del sistema. Para más información, véase Conectando con SQLDriverConnect.
Syntax
SQLRETURN SQLDriverConnect(
SQLHDBC ConnectionHandle,
SQLHWND WindowHandle,
SQLCHAR * InConnectionString,
SQLSMALLINT StringLength1,
SQLCHAR * OutConnectionString,
SQLSMALLINT BufferLength,
SQLSMALLINT * StringLength2Ptr,
SQLUSMALLINT DriverCompletion);
Arguments
ConnectionHandle
[Entrada] Identificador de conexión.
WindowHandle
[Entrada] Manilla de la ventana. La aplicación puede pasar el handle de la ventana madre, si corresponde, o un puntero nulo si el handle de ventana no es aplicable o SQLDriverConnect no presenta ningún cuadro de diálogo.
InConnectionString
[Entrada] Una cadena de conexión completa (véase la sintaxis en "Comentarios"), una cadena de conexión parcial o una cadena vacía.
LongitudlongitudCuerda1
[Entrada] Longitud de *InConnectionString, en caracteres si la cadena es Unicode, o bytes si la cadena es ANSI o DBCS.
CadenaConexiónExterior
[Salida] Puntero a un buffer para la cadena de conexión completada. Tras la conexión exitosa a la fuente de datos objetivo, este búfer contiene la cadena de conexión completa. Las aplicaciones deben asignar al menos 1.024 caracteres para este búfer.
Si OutConnectionString es NULL, StringLength2Ptr seguirá devolviendo el número total de caracteres (excluyendo el carácter de terminación nula para los datos de caracteres) disponibles para devolver en el búfer al que apunta OutConnectionString.
BufferLength
[Entrada] Longitud del búfer *OutConnectionString , en caracteres.
StringLength2Ptr
[Salida] Puntero a un búfer en el que devolver el número total de caracteres (excluyendo el carácter de terminación nula) disponibles para devolver en *OutConnectionString. Si el número de caracteres disponibles para devolver es mayor o igual a BufferLength, la cadena de conexión completada en *OutConnectionString se trunca a BufferLength menos la longitud de un carácter de terminación nula.
PilotoCompletación
[Entrada] Bandera que indica si el Driver Manager o el conductor deben solicitar más información de conexión:
SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED o SQL_DRIVER_NOPROMPT.
(Para más información, véase "Comentarios.")
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE o SQL_STILL_EXECUTING.
Diagnostics
Cuando SQLDriverConnect devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando a SQLGetDiagRec con un fHandleType de SQL_HANDLE_DBC y un hHandle de ConnectionHandle. La siguiente tabla enumera los valores SQLSTATE que suele devolver SQLDriverConnect y explica cada uno en el contexto de esta función; la notación "(DM)" precede a las descripciones de los SQLSTATE devueltas por el Driver Manager. El código de retorno asociado a cada valor SQLSTATE es SQL_ERROR, a menos que se indique lo contrario.
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | Advertencia general | Mensaje informativo específico del controlador. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 01004 | Datos de cadena, truncados a la derecha | El buffer *OutConnectionString no era lo suficientemente grande para devolver toda la cadena de conexión, por lo que la cadena de conexión se truncó. La longitud de la string de conexión no arruinada se devuelve en *StringLong2Ptr. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 01S00 | Atributo de cadena de conexión inválido | Se especificaba una palabra clave de atributos inválida en la cadena de conexión (InConnectionString), pero el controlador podía conectarse a la fuente de datos de todos modos. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 01S02 | Valor de opción cambiado | El controlador no soportaba el valor especificado al que apuntaba el argumento ValuePtr en SQLSetConnectAttr y sustituía por un valor similar. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 01S08 | Archivo de guardado de error DSN | La cadena en *InConnectionString contenía una palabra clave FILEDSN , pero el archivo .dsn no se guardó. (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 01S09 | Palabra clave inválida | (DM) La cadena en *InConnectionString contenía una palabra clave SAVEFILE pero no un DRIVER ni una palabra clave FILEDSN . (Function devuelve SQL_SUCCESS_WITH_INFO). |
| 08001 | El cliente no puede establecer la conexión | El conductor no pudo establecer una conexión con la fuente de datos. |
| 08002 | Nombre de la conexión en uso | (DM) El ConnectionHandle especificado ya se había utilizado para establecer una conexión con una fuente de datos, y la conexión seguía abierta. |
| 08004 | El servidor rechazó la conexión | La fuente de datos rechazó el establecimiento de la conexión por razones definidas por la implementación. |
| 08S01 | Error de vínculo de comunicación | El enlace de comunicación entre el controlador y la fuente de datos a la que intentaba conectarse falló antes de que la función SQLDriverConnect completara el procesamiento. |
| 28000 | Especificación de autorización inválida | Ya sea el identificador de usuario o la cadena de autorización, o ambos, según lo especificado en la cadena de conexión (InConnectionString), violaron las restricciones definidas por la fuente de datos. |
| HY000 | Error genérico | Se produjo un error para el que no había ningún SQLSTATE específico y para el que no se definió SQLSTATE específico de la implementación. El mensaje de error devuelto por SQLGetDiagRec en el búfer *szMessageText describe el error y su causa. |
| HY000 | Error general: archivo dsn inválido | (DM) La cadena en *InConnectionString contenía una palabra clave FILEDSN, pero no se encontró el nombre del archivo .dsn. |
| HY000 | Error general: No se puede crear buffer de archivos | (DM) La cadena en *InConnectionString contenía una palabra clave FILEDSN, pero el archivo .dsn era ilegible. |
| HY001 | Error de asignación de memoria | El Administrador de Controladores no pudo asignar la memoria necesaria para soportar la ejecución o finalización de la función SQLDriverConnect . El controlador no pudo asignar memoria necesaria para admitir la ejecución o finalización de la función. |
| HY008 | Operación cancelada | El procesamiento asincrónico estaba habilitado para el ConnectionHandle. Se llamaba a la función y, antes de que completara su ejecución, se llamaba la función SQLCancelHandle en el ConnectionHandle, y luego la función SQLDriverConnect se llamaba de nuevo en el ConnectionHandle. O bien, se llamaba a la función SQLDriverConnect y, antes de que completara su ejecución, se llamaba SQLCancelHandle en el ConnectionHandle desde otro hilo en una aplicación multihilo. |
| HY010 | Error de secuencia de funciones | (DM) Se llamaba otra función que se ejecutaba de forma asíncrona (no SQLDriverConnect) para el ConnectionHandle y seguía ejecutándose cuando se llamaba a la función SQLDriverConnect . |
| HY013 | Error de administración de memoria | La llamada a la función SQLDriverConnect no podía procesarse porque no se podía acceder a los objetos de memoria subyacentes, posiblemente debido a condiciones de baja memoria. |
| HY090 | Longitud de búfer o cadena no válida | (DM) El valor especificado para el argumento StringLength1 era menor que 0 y no era igual a SQL_NTS. (DM) El valor especificado para el argumento BufferLength era menor que 0. |
| HY092 | Identificador de atributo/opción inválido | (DM) El argumento DriverCompletion era SQL_DRIVER_PROMPT, y el argumento WindowHandle era un puntero nulo. |
| HY110 | Completación del controlador inválido | (DM) El valor especificado para el argumento DriverCompletion no era igual a SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED o SQL_DRIVER_NOPROMPT. (DM) Se habilitó la agrupación de conexiones, y el valor especificado para el argumento DriverCompletion no era igual a SQL_DRIVER_NOPROMPT. |
| HYC00 | Característica opcional no implementada | El controlador no soporta la versión del comportamiento ODBC que la aplicación solicitó. |
| HYT00 | Se ha agotado el tiempo de espera | El periodo de espera de inicio de sesión expiró antes de que se completara la conexión a la fuente de datos. El periodo de espera se establece a través de SQLSetConnectAttr, SQL_ATTR_LOGIN_TIMEOUT. |
| HYT01 | Se ha agotado el tiempo de espera de la conexión. | El período de tiempo de espera de conexión expiró antes de que el origen de datos respondiera a la solicitud. El período de tiempo de espera de conexión se establece a través de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | El controlador no admite esta función | (DM) El controlador correspondiente al nombre de la fuente de datos especificado no soporta la función. |
| IM002 | Fuente de datos no encontrada y sin driver por defecto especificado | (DM) El nombre de la fuente de datos especificado en la cadena de conexión (InConnectionString) no se encontraba en la información del sistema, y no había una especificación predeterminada del controlador. (DM) La fuente de datos ODBC y la información de los controladores por defecto no se podían encontrar en la información del sistema. |
| IM003 | El controlador especificado no pudo cargarse | (DM) El controlador listado en la especificación de la fuente de datos en la información del sistema o especificado por la palabra clave DRIVER no fue encontrado o no pudo cargarse por alguna otra razón. |
| IM004 | El SQLAllocHandle del controlador en SQL_HANDLE_ENV falló | (DM) Durante SQLDriverConnect, el Administrador de Controladores llamaba a la función SQLAllocHandle del controlador con un fHandleType de SQL_HANDLE_ENV y el controlador devolvía un error. |
| IM005 | El SQLAllocHandle del controlador en SQL_HANDLE_DBC falló. | (DM) Durante SQLDriverConnect, el Administrador de Controladores llamaba a la función SQLAllocHandle del controlador con un fHandleType de SQL_HANDLE_DBC y el controlador devolvía un error. |
| IM006 | El SQLSetConnectAttr del controlador falló | (DM) Durante SQLDriverConnect, el Administrador de Controladores llamaba a la función SQLSetConnectAttr del controlador y el controlador devolvía un error. |
| IM007 | No se especifica ninguna fuente de datos ni controlador; Diálogo prohibido | No se especificó ningún nombre de fuente de datos ni controlador en el cadena de conexión, y DriverCompletion fue SQL_DRIVER_NOPROMPT. |
| IM008 | Diálogo fallido | El controlador intentó mostrar su cuadro de diálogo de inicio de sesión y falló. WindowHandle era un puntero nulo, y DriverCompletion no era SQL_DRIVER_NO_PROMPT. |
| IM009 | No se puede cargar la DLL de traducción | El controlador no podía cargar la DLL de traducción especificada para la fuente de datos ni para la conexión. |
| IM010 | Nombre de la fuente de datos demasiado largo | (DM) El valor del atributo para la palabra clave DSN era mayor que SQL_MAX_DSN_LENGTH caracteres. |
| IM011 | Nombre del conductor demasiado largo | (DM) El valor del atributo para la palabra clave DRIVER era superior a 255 caracteres. |
| IM012 | Error de sintaxis de la palabra clave DRIVER | (DM) El par de palabras clave-valor para la palabra clave DRIVER contenía un error de sintaxis. (DM) La cadena en *InConnectionString contenía una palabra clave FILEDSN , pero el archivo .dsn no contenía una palabra clave DRIVER ni una palabra clave DSN . |
| IM014 | El DSN especificado contiene una discrepancia arquitectónica entre el controlador y la aplicación | (DM) La aplicación de 32 bits utiliza una DSN conectada a un controlador de 64 bits; O viceversa. |
| IM015 | El SQLDriverConnect del controlador en SQL_HANDLE_DBC_INFO_HANDLE falló | Si un controlador devuelve SQL_ERROR, el Gestor de Controladores devolverá SQL_ERROR a la aplicación y la conexión fallará. Para más información sobre SQL_HANDLE_DBC_INFO_TOKEN, véase Desarrollo de la conciencia Connection-Pool en un controlador ODBC. |
| IM017 | El sondeo está deshabilitado en modo de notificación asincrónica | Cada vez que se usa el modelo de notificación, el sondeo está deshabilitado. |
| IM018 | No se ha llamado a SQLCompleteAsync para completar la operación asincrónica anterior en este identificador. | Si la llamada de función anterior en el identificador devuelve SQL_STILL_EXECUTING y si el modo de notificación está habilitado, se debe llamar a SQLCompleteAsync en el identificador para realizar el procesamiento posterior y completar la operación. |
| S1118 | El controlador no soporta notificaciones asíncronas | Cuando el controlador no soporta notificaciones asíncronas, no puedes configurar SQL_ATTR_ASYNC_DBC_EVENT ni SQL_ATTR_ASYNC_DBC_RETCODE_PTR. |
Comentarios
Una cadena de conexión tiene la siguiente sintaxis:
cadena de conexión ::= cadena vacía[;] | atributo[;] | atributo; Cadena de conexión
cadena vacía ::=atributo ::= atributo-palabra=clave-atributovalor-valor | DRIVER=[{]valor-atributo[}]
palabra clave de atributos ::= DSN | UID | PWD | Palabra clave atributo-definida-driver
valor-atributo ::= cadena de caracteres
Palabra clave de atributo definido por driver ::= identificador
donde la cadena de caracteres tiene cero o más caracteres; el identificador tiene uno o más caracteres; la palabra clave atributo no distingue mayúsculas y minúsculas; el valor de atributo puede ser sensible a mayúsculas y mayúsculas; y el valor de la palabra clave DSN no consiste únicamente en espacios en blanco.
Debido a la gramática de la cadena de conexión y el archivo de inicialización, las palabras clave y los valores de atributos que contienen los caracteres []{}(),;? *=!@ no se debe evitar que no esté encerrado con brackets. El valor de la palabra clave DSN no puede constar solo de espacios en blanco y no debe contener espacios en blanco iniciales. Debido a la gramática de la información del sistema, las palabras clave y los nombres de origen de datos no pueden contener el carácter de barra diagonal inversa (\).
Las aplicaciones no tienen que añadir férulas alrededor del valor del atributo después de la palabra clave DRIVER , a menos que el atributo contenga un punto y coma (;), en cuyo caso se requieren las férulas. Si el valor de atributo que recibe el controlador incluye llaves, el controlador no debe quitarlos, pero deben formar parte de la cadena de conexión devuelta.
¿Un valor DSN o cadena de conexión encerrado con brackets ({}) que contenga cualquiera de los caracteres []{}(),;? *=!@ se pasa intacto al conductor. Sin embargo, al usar estos caracteres en una palabra clave, el Driver Manager devuelve un error al trabajar con DSN de archivos, pero pasa la cadena de conexión al controlador para las cadenas de conexión normales. Evite usar llaves incrustadas en un valor de palabra clave.
La cadena de conexión puede incluir cualquier número de palabras clave definidas por el controlador. Como la palabra clave DRIVER no utiliza información de la información del sistema, el controlador debe definir suficientes palabras clave para que pueda conectarse a una fuente de datos usando únicamente la información de la cadena de conexión. (Para más información, véase "Directrices para conductores", más adelante en esta sección.) El controlador define qué palabras clave deben conectarse a la fuente de datos.
La siguiente tabla describe los valores de atributos de las palabras clave DSN,FILEDSN, DRIVER,UID,PWD y SAVEFILE .
| Keyword | Descripción del valor del atributo |
|---|---|
| DSN | Nombre de una fuente de datos devuelto por SQLDataSources o por el cuadro de diálogo de fuentes de datos de SQLDriverConnect. |
| ARCHIVEDSN | Nombre de un archivo .dsn a partir del cual se construirá una cadena de conexión para la fuente de datos. Estas fuentes de datos se denominan fuentes de datos de archivo. |
| DRIVER | Descripción del controlador tal como se devuelve mediante la función SQLDrivers . Por ejemplo, Rdb o SQL Server. |
| UID | Identificador de usuario. |
| PWD | La contraseña correspondiente al ID de usuario, o una cadena vacía si no hay contraseña para el ID de usuario (PWD=;). |
| ARCHIVO GUARDADO | El nombre del archivo de un archivo .dsn en el que se deben guardar los valores de atributos de las palabras clave utilizadas para crear la conexión actual y exitosa. |
Para información sobre cómo una aplicación elige una fuente de datos o un controlador, consulte Elección de una fuente de datos o controlador.
Si se repiten palabras clave en la cadena de conexión, el controlador utiliza el valor asociado a la primera aparición de la palabra clave. Si las palabras clave DSN y DRIVER están incluidas en la misma cadena de conexión, el Driver Manager y el driver usan la palabra clave que aparezca primero.
Las palabras clave FILEDSN y DSN son mutuamente excluyentes: se utiliza la palabra clave que aparece primero y se ignora la que aparece en segundo lugar. Las palabras clave FILEDSN y DRIVER , en cambio, no son mutuamente excluyentes. Si aparece alguna palabra clave en una cadena de conexión con FILEDSN, entonces se utiliza el valor de atributo de la palabra clave en la cadena de conexión en lugar del valor de atributo de la misma palabra clave en el archivo .dsn.
Si se utiliza la palabra clave FILEDSN, las palabras clave especificadas en un archivo .dsn se utilizan para crear una cadena de conexión. (Para más información, véase "Fuentes de datos de archivo", más adelante en esta sección.) La palabra clave UID es opcional; un archivo .dsn puede crearse solo con la palabra clave DRIVER . La palabra clave PWD no se almacena en un archivo .dsn. El directorio predeterminado para guardar y cargar un archivo .dsn será una combinación de la ruta especificada por CommonFileDir en HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ Windows\CurrentVersion y "ODBC\DataSources". (Si CommonFileDir fuera "C:\Program Files\Common Files", el directorio por defecto sería "C:\Program Files\Common Files\ODBC\Data Sources".)
Note
Un archivo .dsn puede manipularse directamente llamando a las funciones SQLReadFileDSN y SQLWriteFileDSN en la DLL del instalador.
Si se utiliza la palabra clave SAVEFILE , los valores de atributos de las palabras clave usadas para crear la conexión actual y exitosa se guardarán como un archivo .dsn con el nombre del valor de atributo de la palabra clave SAVEFILE . La palabra clave SAVEFILE debe usarse junto con la palabra clave DRIVER , la palabra clave FILEDSN o ambas, o la función devuelve SQL_SUCCESS_WITH_INFO con SQLSTATE 01S09 (palabra clave inválida). La palabra clave SAVEFILE debe aparecer antes que la palabra clave DRIVER en la cadena de conexión, o los resultados quedarán indefinidos.
Directrices para el Gestor de Pilotos
El Driver Manager construye una cadena de conexión para pasar al controlador en el argumento InConnectionString de la función SQLDriverConnect del driver. El Driver Manager no modifica el argumento InConnectionString que le ha pasado la aplicación.
La acción del Driver Manager se basa en el valor del argumento DriverCompleting :
SQL_DRIVER_PROMPT: Si el cadena de conexión no contiene ni la palabra clave DRIVER, DSN ni FILEDSN, el Administrador de Controladores muestra el cuadro de diálogo Fuentes de Datos. Construye una cadena de conexión a partir del nombre de la fuente de datos devuelto por el cuadro de diálogo y cualquier otra palabra clave que le pase la aplicación. Si el nombre de la fuente de datos devuelto por el cuadro de diálogo está vacío, el Administrador de Controladores especifica el par de palabras clave-valor DSN=Default. (Este cuadro de diálogo no mostrará una fuente de datos con el nombre "Default".)
SQL_DRIVER_COMPLETE o SQL_DRIVER_COMPLETE_REQUIRED: Si el cadena de conexión especificado por la aplicación incluye la palabra clave DSN, el Driver Manager copia el cadena de conexión especificado por la aplicación. De lo contrario, realiza las mismas acciones que cuando DriverCompletion está SQL_DRIVER_PROMPT.
SQL_DRIVER_NOPROMPT: El Driver Manager copia el cadena de conexión especificado por la aplicación.
Si la cadena de conexión especificada por la aplicación contiene la palabra clave DRIVER, el Driver Manager copia la cadena de conexión especificada por la aplicación.
Usando la cadena de conexión que ha construido, el Administrador de Controladores determina qué controlador usar, se conecta a ese controlador y pasa la string de conexión que ha construido al controlador; para más información sobre la interacción entre el Administrador de Controladores y el controlador, consulte la sección "Comentarios" en la Función SQLConnect. Si la cadena de conexión no contiene la palabra clave DRIVER, el Driver Manager determina qué controlador usar de la siguiente manera:
Si la cadena de conexión contiene la palabra clave DSN, el Driver Manager recupera el controlador asociado a la fuente de datos de la información del sistema.
Si la cadena de conexión no contiene la palabra clave DSN o no se encuentra la fuente de datos, el Driver Manager recupera el controlador asociado con la fuente de datos predeterminada a partir de la información del sistema. (Para más información, véase Subclave predeterminada.) El Driver Manager cambia el valor de la palabra clave DSN en la cadena de conexión a "DEFAULT".
Si la palabra clave DSN en la cadena de conexión está configurada como "DEFAULT", el Administrador de Controladores recupera el controlador asociado a la fuente de datos predeterminada de la información del sistema.
Si no se encuentra la fuente de datos y no se encuentra la fuente predeterminada, el Driver Manager SQL_ERROR devuelve con SQLSTATE IM002 (Fuente de datos no encontrada y sin driver predeterminado especificado).
Orígenes de datos de archivos
Si la cadena de conexión especificada por la aplicación en la llamada a SQLDriverConnect contiene la palabra clave FILEDSN, y esta palabra clave no es reemplazada ni por la palabra clave DSN ni por DRIVER, entonces el Driver Manager crea una cadena de conexión usando la información del archivo .dsn y el argumento InConnectionString. El Driver Manager procede de la siguiente manera:
Comprueba si el nombre del archivo .dsn es válido. Si no, SQL_ERROR devuelve con SQLSTATE IM014 (nombre inválido del archivo DSN). Si el nombre del archivo es una cadena vacía ("") y no se especifica SQL_DRIVER_NOPROMPT, entonces se muestra el cuadro de diálogo Abrir archivo . Si el nombre del archivo contiene una ruta válida pero no tiene nombre o un nombre de archivo inválido, y SQL_DRIVER_NOPROMPT no se especifica, entonces se muestra el cuadro de diálogo Apertura de Archivo con el directorio actual establecido en el especificado en el nombre del archivo. Si el nombre del archivo es una cadena vacía ("") o contiene una ruta válida pero sin nombre de archivo o un nombre de archivo inválido, y se especifica SQL_ERROR SQL_DRIVER_NOPROMPT, entonces se devuelve con SQLSTATE IM014 (nombre inválido del archivo DSN).
Lee todas las palabras clave en la sección [ODBC] del archivo .dsn. Si la palabra clave DRIVER no está presente, SQL_ERROR devuelve con SQLSTATE IM012 (error de sintaxis de la palabra clave Driver), excepto cuando el archivo .dsn no es compartible y por tanto contiene solo la palabra clave DSN .
Si la fuente de datos del archivo no es compartible, el Driver Manager lee el valor de la palabra clave DSN y se conecta según sea necesario a la fuente de datos del usuario o del sistema a la que apunta la fuente de datos del archivo no compartible. No se realizan los pasos 3 a 5.
Construye una cadena de conexión para el driver. La cadena de conexión del controlador es la unión de las palabras clave especificadas en el archivo .dsn y las especificadas en la cadena de conexión original de la aplicación. Las reglas para la construcción de la cadena de conexión de drivers donde las palabras clave se solapan son las siguientes:
Si la palabra clave DRIVER existe en la cadena de conexión de la aplicación y los controladores especificados por las palabras clave DRIVER no son los mismos en el archivo .dsn y en la cadena de conexión de la aplicación, entonces la información del controlador en el archivo .dsn se ignora y se utiliza la información del controlador en la cadena de conexión de la aplicación. Si los controladores especificados por la palabra clave DRIVER son los mismos en el archivo .dsn y en la cadena de conexión de la aplicación, entonces donde todas las palabras clave se solapan, las especificadas en la cadena de conexión de la aplicación tienen precedencia sobre las especificadas en el archivo .dsn.
En la nueva cadena de conexión, se elimina la palabra clave FILEDSN.
Carga el controlador mirando en la entrada del registro HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\<Nombre> del controlador\Controlador, donde <el Nombre> del controlador se especifica mediante la palabra clave DRIVER .
Pasa al driver la nueva cadena de conexiones.
Para ejemplos de archivos .dsn, véase Conexión usando fuentes de datos de archivo.
Palabra clave SAVEFILE
Si la cadena de conexión especificada por la aplicación contiene la palabra clave SAVEFILE, entonces el Driver Manager guarda la cadena de conexión en un archivo .dsn. El Driver Manager procede de la siguiente manera:
Comprueba si el nombre del archivo .dsn incluido como valor de atributo de la palabra clave SAVEFILE es válido. Si no, SQL_ERROR devuelve con SQLSTATE IM014 (nombre inválido del archivo DSN). La validez del nombre del archivo está determinada por las reglas estándar de nombres del sistema. Si el nombre del archivo es una cadena vacía ("") y el argumento DriverCompletion no es SQL_DRIVER_NOPROMPT, entonces el nombre del archivo es válido. Si el nombre del archivo ya existe, entonces si DriverCompletion está SQL_DRIVER_NOPROMPT, el archivo se sobrescribe. Si DriverCompletion es SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE o SQL_DRIVER_COMPLETE_REQUIRED, un cuadro de diálogo pide al usuario que especifique si el archivo debe ser sobrescribido. Si se introduce No, aparece el cuadro de diálogo Guardar archivos .
Si el controlador devuelve SQL_SUCCESS y el nombre del archivo no era una cadena vacía, entonces el Administrador de Controladores escribe la información de conexión devuelta en el argumento OutConnectionString en el archivo especificado con el formato especificado en la sección "Cadenas de conexión" anteriormente en esta sección.
Si el controlador devuelve SQL_SUCCESS y el nombre del archivo era una cadena vacía (""), entonces el Administrador de Controladores llama al cuadro de diálogo común File-Save con el hwnd especificado y escribe la información de conexión devuelto en OutConnectionString en el archivo especificado en el cuadro de diálogo común File-Save con el formato especificado en la sección "Cadenas de conexión" anteriormente en esta sección.
Si el controlador devuelve SQL_SUCCESS, devuelve el argumento OutConnectionString que contiene el cadena de conexión a la aplicación.
Si el controlador devuelve SQL_SUCCESS_WITH_INFO o SQL_ERROR, entonces el Administrador de Controladores devuelve el estado SQL a la aplicación.
Directrices para conductores
El controlador comprueba si la cadena de conexión que le pasa el Driver Manager contiene la palabra clave DSN o DRIVER. Si la cadena de conexión contiene la palabra clave DRIVER, el controlador no puede obtener información sobre la fuente de datos a partir de la información del sistema. Si la cadena de conexión contiene la palabra clave DSN o no contiene ni la palabra clave DSN ni DRIVER, el controlador puede obtener información sobre la fuente de datos a partir de la información del sistema de la siguiente manera:
Si la cadena de conexión contiene la palabra clave DSN, el controlador recupera la información para la fuente de datos especificada.
Si la cadena de conexión no contiene la palabra clave DSN, no se encuentra la fuente de datos especificada, o la palabra clave DSN se establece en "DEFAULT", el controlador recupera la información para la fuente de datos predeterminada.
El controlador utiliza cualquier información que recupere de la información del sistema para complementar la información que le pasa en la cadena de conexión. Si la información en la información del sistema duplica la información de la cadena de conexión, el controlador utiliza la información de la cadena de conexión.
En función del valor de DriverCompletion, el controlador solicita al usuario información de conexión, como el ID de usuario y la contraseña, y se conecta a la fuente de datos:
SQL_DRIVER_PROMPT: El controlador muestra un cuadro de diálogo, usando los valores del cadena de conexión y la información del sistema (si los hay) como valores iniciales. Cuando el usuario sale del cuadro de diálogo, el controlador se conecta a la fuente de datos. También construye una cadena de conexión a partir del valor de la palabra clave DSN o DRIVER en *InConnectionString y la información devuelto desde el cuadro de diálogo. Coloca esta cadena de conexión en el búfer *OutConnectionString.
SQL_DRIVER_COMPLETE o SQL_DRIVER_COMPLETE_REQUIRED: Si el cadena de conexión contiene suficiente información y esa información es correcta, el controlador se conecta a la fuente de datos y copia *InConnectionString a *OutConnectionString. Si falta información o es incorrecta, el controlador realiza las mismas acciones que cuando se SQL_DRIVER_PROMPT DriverCompleting , salvo que si DriverCompletion está SQL_DRIVER_COMPLETE_REQUIRED, el controlador desactiva los controles para cualquier información que no sea necesaria para conectarse a la fuente de datos.
SQL_DRIVER_NOPROMPT: Si el cadena de conexión contiene suficiente información, el controlador se conecta a la fuente de datos y copia *InConnectionString a *OutConnectionString. De lo contrario, el controlador devuelve SQL_ERROR para SQLDriverConnect.
Tras la conexión exitosa a la fuente de datos, el controlador también establece *StringLength2Ptr a la longitud de la cadena de conexión de salida que está disponible para devolver en *OutConnectionString.
Si el usuario cancela un cuadro de diálogo presentado por el Driver Manager o el driver, SQLDriverConnect devuelve SQL_NO_DATA.
Para información sobre cómo interactúan el Administrador de Controladores y el controlador durante el proceso de conexión, consulte Función SQLConnect.
Si un controlador soporta SQLDriverConnect, la sección de palabras clave del controlador en la información del sistema debe contener la palabra clave ConnectFunctions con el segundo carácter asignado a "Y".
Conexión cuando está habilitado el pooling de conexiones
El pooling de conexiones permite a una aplicación reutilizar una conexión que ya ha sido creada. Cuando se llama a SQLDriverConnect , el Administrador de Controladores intenta establecer la conexión usando una conexión que forma parte de un conjunto de conexiones en un entorno designado para la agrupación de conexiones. Para más información sobre la agrupación de conexiones, véase Función SQLConnect.
Una aplicación puede establecer SQL_ATTR_RESET_CONNECTION antes de llamar a SQLDisconnect en una conexión donde el pooling esté habilitado. Para obtener más información, vea Función SQLSetConnectAttr.
Las siguientes restricciones se aplican cuando una aplicación llama a SQLDriverConnect para conectarse a una conexión agrupada:
No se realiza ningún procesamiento de agrupación de conexiones cuando la palabra clave SAVEFILE se especifica en la string de conexión.
Si el pooling de conexiones está habilitado, SQLDriverConnect solo puede llamarse con un argumento DriverCompletion de SQL_DRIVER_NOPROMPT; si se llama a SQLDriverConnect con cualquier otro DriverCompletion, se devolverá SQLSTATE HY110 (Completación de controlador inválida).
Atributos de conexión
El atributo de conexión SQL_ATTR_LOGIN_TIMEOUT, establecido mediante SQLSetConnectAttr, define el número de segundos para esperar a que una solicitud de inicio de sesión se complete con una conexión exitosa por parte del controlador antes de volver a la aplicación. Si se pide al usuario que complete la cadena de conexión, comienza un periodo de espera para cada solicitud de inicio de sesión cuando el controlador inicia el proceso de conexión.
El controlador abre la conexión en modo acceso SQL_MODE_READ_WRITE por defecto. Para configurar el modo de acceso a SQL_MODE_READ_ONLY, la aplicación debe llamar a SQLSetConnectAttr con el atributo SQL_ATTR_ACCESS_MODE antes de llamar a SQLDriverConnect.
Si se especifica una biblioteca de traducción predeterminada en la información del sistema para la fuente de datos, el controlador la carga. Se puede cargar una biblioteca de traducción diferente llamando a SQLSetConnectAttr con el SQL_ATTR_TRANSLATE_LIB attribute. Se puede especificar una opción de traducción llamando a SQLSetConnectAttr con la opción SQL_ATTR_TRANSLATE_OPTION.
Para más información, véase Conectando con SQLDriverConnect.
// SQLDriverConnect_ref.cpp
// compile with: odbc32.lib user32.lib
#include <windows.h>
#include <sqlext.h>
int main() {
SQLHENV henv;
SQLHDBC hdbc;
SQLHSTMT hstmt;
SQLRETURN retcode;
SQLCHAR OutConnStr[255];
SQLSMALLINT OutConnStrLen;
HWND desktopHandle = GetDesktopWindow(); // desktop's window handle
// Allocate environment handle
retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
// Set the ODBC version environment attribute
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);
// Allocate connection handle
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
// Set login timeout to 5 seconds
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);
retcode = SQLDriverConnect( // SQL_NULL_HDBC
hdbc,
desktopHandle,
(SQLCHAR*)"driver=SQL Server",
_countof("driver=SQL Server"),
OutConnStr,
255,
&OutConnStrLen,
SQL_DRIVER_PROMPT );
// Allocate statement handle
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
// Process data
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
}
SQLDisconnect(hdbc);
}
SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
}
}
SQLFreeHandle(SQL_HANDLE_ENV, henv);
}
}
Véase también Programa ODBC de ejemplo.
Funciones relacionadas
| Para obtener información sobre | Vea |
|---|---|
| Asignación de un handle | Función SQLAllocHandle |
| Descubrir y enumerar los valores necesarios para conectarse a una fuente de datos | Función SQLBrowseConnect |
| Conexión a un origen de datos | Función SQLConnect |
| Desconexión de una fuente de datos | Función SQLDisconnect |
| Descripción y atributos de los pilotos que regresan | Función SQLDrivers |
| Liberar un mango | Función SQLFreeHandle |
| Establecer un atributo de conexión | Función SQLSetConnectAttr |