Función SQLDriverConnect

Article
05/23/2023

Conformidad
Versión introducida: Cumplimiento de estándares odbc 1.0: ODBC

Resumen
SQLDriverConnect es una alternativa a SQLConnect. Admite orígenes de datos que requieren más información de conexión que los tres argumentos de SQLConnect, cuadros de diálogo para solicitar al usuario toda la información de conexión y orígenes de datos que no están definidos en la información del sistema. Para obtener más información, vea Conexión con SQLDriverConnect.

Sintaxis

  
SQLRETURN SQLDriverConnect(  
     SQLHDBC         ConnectionHandle,  
     SQLHWND         WindowHandle,  
     SQLCHAR *       InConnectionString,  
     SQLSMALLINT     StringLength1,  
     SQLCHAR *       OutConnectionString,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLength2Ptr,  
     SQLUSMALLINT    DriverCompletion);

Argumentos

ConnectionHandle
[Entrada] Identificador de conexión.

WindowHandle
[Entrada] Identificador de ventana. La aplicación puede pasar el identificador de la ventana primaria, si procede, o un puntero nulo si el identificador de ventana no es aplicable o SQLDriverConnect no presentará ningún cuadro de diálogo.

InConnectionString
[Entrada] Una cadena de conexión completa (vea la sintaxis en "Comments"), una cadena de conexión parcial o una cadena vacía.

StringLength1
[Entrada] Longitud de *InConnectionString, en caracteres si la cadena es Unicode o bytes si la cadena es ANSI o DBCS.

OutConnectionString
[Salida] Puntero a un búfer para la cadena de conexión completada. Tras una conexión correcta al origen de datos de destino, este búfer contiene la cadena de conexión completada. Las aplicaciones deben asignar al menos 1024 caracteres para este búfer.

Si OutConnectionString es NULL, StringLength2Ptr seguirá devolviendo el número total de caracteres (excepto el carácter de terminación NULL para los datos de caracteres) disponible 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 (excepto el carácter de terminación NULL) disponible para devolver en *OutConnectionString. Si el número de caracteres disponibles para devolver es mayor o igual que BufferLength, la cadena de conexión completada en *OutConnectionString se trunca en BufferLength menos la longitud de un carácter de terminación null.

DriverCompletion
[Entrada] Marca que indica si el administrador de controladores o el controlador deben solicitar más información de conexión:

SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED o SQL_DRIVER_NOPROMPT.

(Para obtener más información, vea "Comentarios").

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE o SQL_STILL_EXECUTING.

Diagnóstico

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. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLDriverConnect y se explica cada uno en el contexto de esta función; la notación "(DM)" precede a las descripciones de SQLSTATEs devueltas por el Administrador de controladores. El código de retorno asociado a cada valor SQLSTATE es SQL_ERROR, a menos que se indique lo contrario.

SQLSTATE	Error	Descripción
01000	Advertencia general	Mensaje informativo específico del controlador. (Function devuelve SQL_SUCCESS_WITH_INFO).
01004	Datos de cadena, truncados a la derecha	El búfer *OutConnectionString no era lo suficientemente grande como para devolver toda la cadena de conexión, por lo que la cadena de conexión se truncaba. La longitud de la cadena de conexión notruncada se devuelve en *StringLength2Ptr. (Function devuelve SQL_SUCCESS_WITH_INFO).
01S00	Atributo de cadena de conexión no válido	Se especificó una palabra clave de atributo no válida en la cadena de conexión (InConnectionString), pero el controlador pudo conectarse al origen de datos de todos modos. (Function devuelve SQL_SUCCESS_WITH_INFO).
01S02	Valor de opción cambiado	El controlador no admitía el valor especificado al que apunta el argumento ValuePtr en SQLSetConnectAttr y sustituyó un valor similar. (Function devuelve SQL_SUCCESS_WITH_INFO).
01S08	Error al guardar el archivo DSN	La cadena de InConnectionString contenía una palabra clave FILEDSN* , pero el archivo .dsn no se guardó. (Function devuelve SQL_SUCCESS_WITH_INFO).
01S09	Palabra clave no válida	(DM) La cadena de InConnectionString contenía una palabra clave SAVEFILE* , pero no una palabra clave DRIVER o FILEDSN . (Function devuelve SQL_SUCCESS_WITH_INFO).
08001	El cliente no puede establecer la conexión	El controlador no pudo establecer una conexión con el origen de datos.
08002	Nombre de conexión en uso	(DM) El connectionHandle especificado ya se había usado para establecer una conexión con un origen de datos y la conexión todavía estaba abierta.
08004	El servidor rechazó la conexión	El origen de datos rechazó el establecimiento de la conexión por motivos definidos por la implementación.
08S01	Error de vínculo de comunicación	Se produjo un error en el vínculo de comunicación entre el controlador y el origen de datos al que el controlador estaba intentando conectarse antes de que la función SQLDriverConnect completara el procesamiento.
28000	Especificación de autorización no válida	El identificador de usuario o la cadena de autorización, o ambos, como se especifica en la cadena de conexión (InConnectionString), infringen las restricciones definidas por el origen de datos.
HY000	Error general	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 no válido	(DM) La cadena de *InConnectionString contenía una palabra clave FILEDSN, pero no se encontró el nombre del archivo .dsn.
HY000	Error general: No se puede crear el búfer de archivos	(DM) La cadena de *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 memoria necesaria para admitir 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 se ha habilitado para ConnectionHandle. Se llamó a la función y antes de completar la ejecución, se llamó a la función SQLCancelHandle en ConnectionHandle y, a continuación, se llamó a la función SQLDriverConnect de nuevo en ConnectionHandle. O bien, se llamó a la función SQLDriverConnect y antes de completar la ejecución, se llamó a SQLCancelHandle en connectionHandle desde un subproceso diferente en una aplicación multiproceso.
HY010	Error de secuencia de función	(DM) Se llamó a otra función de ejecución asincrónica (no SQLDriverConnect) para ConnectionHandle y todavía se estaba ejecutando cuando se llamó a la función SQLDriverConnect .
HY013	Error de administración de memoria	No se pudo procesar la llamada a la función SQLDriverConnect porque no se pudo acceder a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja.
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 o opción no válido	(DM) El argumento DriverCompletion se SQL_DRIVER_PROMPT y el argumento WindowHandle era un puntero nulo.
HY110	Finalización de controladores no válida	(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 admite la versión del comportamiento ODBC solicitado por la aplicación.
HYT00	Tiempo de espera agotado	El período de tiempo de espera de inicio de sesión expiró antes de que se complete la conexión al origen de datos. El período de tiempo 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 del origen de datos especificado no admite la función .
IM002	No se encontró el origen de datos y no se especificó ningún controlador predeterminado.	(DM) El nombre del origen de datos especificado en la cadena de conexión (InConnectionString) no se encontró en la información del sistema y no había ninguna especificación de controlador predeterminada. (DM) No se encontró la información del controlador ODBC y la información predeterminada del controlador en la información del sistema.
IM003	No se pudo cargar el controlador especificado	(DM) El controlador enumerado en la especificación del origen de datos en la información del sistema o especificado por la palabra clave DRIVER no se encontró o no se pudo cargar por algún otro motivo.
IM004	Error de SQLAllocHandle del controlador en SQL_HANDLE_ENV	(DM) Durante SQLDriverConnect, el Administrador de controladores llamó a la función SQLAllocHandle del controlador con un fHandleType de SQL_HANDLE_ENV y el controlador devolvió un error.
IM005	Error de SQLAllocHandle del controlador en SQL_HANDLE_DBC.	(DM) Durante SQLDriverConnect, el Administrador de controladores llamó a la función SQLAllocHandle del controlador con un fHandleType de SQL_HANDLE_DBC y el controlador devolvió un error.
IM006	Error de SQLSetConnectAttr del controlador	(DM) Durante SQLDriverConnect, el Administrador de controladores llamó a la función SQLSetConnectAttr del controlador y el controlador devolvió un error.
IM007	No se ha especificado ningún origen de datos ni controlador; diálogo prohibido	No se especificó ningún nombre de origen de datos o controlador en la cadena de conexión y DriverCompletion se SQL_DRIVER_NOPROMPT.
IM008	Error en el cuadro de diálogo	El controlador intentó mostrar su cuadro de diálogo de inicio de sesión y produjo un error. WindowHandle era un puntero nulo y DriverCompletion no se SQL_DRIVER_NO_PROMPT.
IM009	No se puede cargar el archivo DLL de traducción	El controlador no pudo cargar la DLL de traducción especificada para el origen de datos o para la conexión.
IM010	Nombre del origen de datos demasiado largo	(DM) El valor de atributo de la palabra clave DSN era mayor que SQL_MAX_DSN_LENGTH caracteres.
IM011	El nombre del controlador es demasiado largo	(DM) El valor de atributo de la palabra clave DRIVER tenía más de 255 caracteres.
IM012	Error de sintaxis de palabra clave DRIVER	(DM) El par palabra clave-valor de la palabra clave DRIVER contenía un error de sintaxis. (DM) La cadena de 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 un error de coincidencia de arquitectura entre el controlador y la aplicación.	(DM) La aplicación de 32 bits usa un DSN que se conecta a un controlador de 64 bits; o viceversa.
IM015	Error de SQLDriverConnect del controlador en SQL_HANDLE_DBC_INFO_HANDLE	Si un controlador devuelve SQL_ERROR, el Administrador de controladores devolverá SQL_ERROR a la aplicación y se producirá un error en la conexión. Para obtener más información sobre SQL_HANDLE_DBC_INFO_TOKEN, vea Developing Connection-Pool Awareness in an ODBC Driver.
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 admite notificaciones asincrónicas	Cuando el controlador no admite notificaciones asincrónicas, no puede establecer SQL_ATTR_ASYNC_DBC_EVENT ni SQL_ATTR_ASYNC_DBC_RETCODE_PTR.

Comentarios

Una cadena de conexión tiene la siguiente sintaxis:

connection-string ::= empty-string[;] | attribute[;] | atributo; cadena de conexión

empty-string ::=attribute ::= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}]

attribute-keyword ::= DSN | UID | PWD | driver-defined-attribute-keyword

attribute-value ::= character-string

driver-defined-attribute-keyword ::= identifier

donde la cadena de caracteres tiene cero o más caracteres; el identificador tiene uno o varios caracteres; attribute-keyword no distingue mayúsculas de minúsculas; attribute-value puede distinguir mayúsculas de minúsculas; y el valor de la palabra clave DSN no consta únicamente de espacios en blanco.

Debido a la gramática del archivo de inicialización y cadena de conexión, palabras clave y valores de atributo que contienen los caracteres []{}(),;? *=!@ no debe evitarse entre llaves. El valor de la palabra clave DSN no puede constar únicamente 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 agregar llaves 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 llaves. 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 de cadena de conexión o DSN entre llaves ({}) que contiene cualquiera de los caracteres []{}(),;? *=!@ se pasa intacto al controlador. Sin embargo, cuando se usan estos caracteres en una palabra clave, el Administrador de controladores devuelve un error al trabajar con DSN de archivo, 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. Dado que la palabra clave DRIVER no usa información de la información del sistema, el controlador debe definir suficientes palabras clave para que un controlador pueda conectarse a un origen de datos usando solo la información de la cadena de conexión. (Para obtener más información, vea "Directrices para controladores", más adelante en esta sección). El controlador define las palabras clave necesarias para conectarse al origen de datos.

En la tabla siguiente se describen los valores de atributo de las palabras clave DSN, FILEDSN, DRIVER, UID, PWD y SAVEFILE .

Palabra clave	Descripción del valor del atributo
DSN	Nombre de un origen de datos tal como lo devuelve SQLDataSources o el cuadro de diálogo Orígenes de datos de SQLDriverConnect.
FILEDSN	Nombre de un archivo .dsn desde el que se compilará una cadena de conexión para el origen de datos. Estos orígenes de datos se denominan orígenes de datos de archivo.
CONDUCTOR	Descripción del controlador tal como lo devuelve la función SQLDrivers . Por ejemplo, Rdb o SQL Server.
UID	Un id. de usuario.
PWD	Contraseña correspondiente al identificador de usuario o una cadena vacía si no hay ninguna contraseña para el identificador de usuario (PWD=;).
SAVEFILE	El nombre de archivo de un archivo .dsn en el que se deben guardar los valores de atributo de las palabras clave usadas para crear la conexión actual y correcta.

Para obtener información sobre cómo una aplicación elige un origen de datos o un controlador, vea Elegir un origen de datos o un controlador.

Si alguna palabra clave se repite en la cadena de conexión, el controlador usa el valor asociado a la primera aparición de la palabra clave. Si las palabras clave DSN y DRIVER se incluyen en la misma cadena de conexión, el Administrador de controladores y el controlador usan la palabra clave que aparezca primero.

Las palabras clave FILEDSN y DSN son mutuamente excluyentes: cualquier palabra clave que aparezca en primer lugar y se omite la que aparece en segundo lugar. Las palabras clave FILEDSN y DRIVER , por otro lado, no son mutuamente excluyentes. Si alguna palabra clave aparece en una cadena de conexión con FILEDSN, el valor de atributo de la palabra clave en la cadena de conexión se usa en lugar del valor de atributo de la misma palabra clave en el archivo .dsn.

Si se usa la palabra clave FILEDSN , las palabras clave especificadas en un archivo .dsn se usan para crear una cadena de conexión. (Para obtener más información, vea "Orígenes de datos de archivos", más adelante en esta sección). La palabra clave UID es opcional; Se puede crear un archivo .dsn con solo 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 de acceso especificada por CommonFileDir en HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ Windows\CurrentVersion y "ODBC\DataSources". (Si CommonFileDir fuera "C:\Program Files\Common Files", el directorio predeterminado sería "C:\Program Files\Common Files\ODBC\Data Sources".)

Nota

Un archivo .dsn se puede manipular directamente llamando a las funciones SQLReadFileDSN y SQLWriteFileDSN en el archivo DLL del instalador.

Si se usa la palabra clave SAVEFILE , los valores de atributo de las palabras clave usadas para hacer el presente, la conexión correcta se guardará 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 bien la función devuelve SQL_SUCCESS_WITH_INFO con SQLSTATE 01S09 (palabra clave no válida). La palabra clave SAVEFILE debe aparecer antes de que la palabra clave DRIVER de la cadena de conexión o los resultados no estén definidos.

Instrucciones del Administrador de controladores

El Administrador de controladores construye una cadena de conexión para pasar al controlador en el argumento InConnectionString de la función SQLDriverConnect del controlador. El Administrador de controladores no modifica el argumento InConnectionString pasado a él por la aplicación.

La acción del Administrador de controladores se basa en el valor del argumento DriverCompletion :

SQL_DRIVER_PROMPT: si la cadena de conexión no contiene la palabra clave DRIVER, DSN o FILEDSN , el Administrador de controladores muestra el cuadro de diálogo Orígenes de datos. Construye una cadena de conexión a partir del nombre del origen de datos devuelto por el cuadro de diálogo y cualquier otra palabra clave que le pase la aplicación. Si el nombre del origen 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á un origen de datos con el nombre "Predeterminado").
SQL_DRIVER_COMPLETE o SQL_DRIVER_COMPLETE_REQUIRED: si la cadena de conexión especificada por la aplicación incluye la palabra clave DSN , el Administrador de controladores copia la cadena de conexión especificada por la aplicación. De lo contrario, realiza las mismas acciones que cuando DriverCompletion se SQL_DRIVER_PROMPT.
SQL_DRIVER_NOPROMPT: el Administrador de controladores copia la cadena de conexión especificada por la aplicación.

Si la cadena de conexión especificada por la aplicación contiene la palabra clave DRIVER , el Administrador de controladores copia la cadena de conexión especificada por la aplicación.

Con la cadena de conexión que ha construido, el Administrador de controladores determina qué controlador usar, se conecta a ese controlador y pasa la cadena de conexión que ha construido al controlador; para obtener más información sobre la interacción del Administrador de controladores y el controlador, vea la sección "Comentarios" de la función SQLConnect. Si la cadena de conexión no contiene la palabra clave DRIVER , el Administrador de controladores determina qué controlador debe usar de la siguiente manera:

Si la cadena de conexión contiene la palabra clave DSN , el Administrador de controladores recupera el controlador asociado al origen de datos de la información del sistema.
Si la cadena de conexión no contiene la palabra clave DSN o no se encuentra el origen de datos, el Administrador de controladores recupera el controlador asociado al origen de datos Predeterminado de la información del sistema. (Para obtener más información, vea Subclave predeterminada). El Administrador de controladores cambia el valor de la palabra clave DSN en la cadena de conexión a "DEFAULT".
Si la palabra clave DSN de la cadena de conexión está establecida en "DEFAULT", el Administrador de controladores recupera el controlador asociado al origen de datos Predeterminado de la información del sistema.
Si no se encuentra el origen de datos y no se encuentra el origen de datos Predeterminado, el Administrador de controladores devuelve SQL_ERROR con SQLSTATE IM002 (no se encontró el origen de datos y no se ha especificado ningún controlador predeterminado).

Orígenes de datos de archivo

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 se sustituye por la palabra clave DSN o DRIVER , el Administrador de controladores crea una cadena de conexión con la información del archivo .dsn y el argumento InConnectionString . El Administrador de controladores continúa de la siguiente manera:

Comprueba si el nombre de archivo del archivo .dsn es válido. Si no es así, devuelve SQL_ERROR con SQLSTATE IM014 (nombre no válido del DSN de archivo). Si el nombre de archivo es una cadena vacía ("") y no se especifica SQL_DRIVER_NOPROMPT, se muestra el cuadro de diálogo Abrir archivo. Si el nombre de archivo contiene una ruta de acceso válida pero ningún nombre de archivo o un nombre de archivo no válido y no se especifica SQL_DRIVER_NOPROMPT, el cuadro de diálogo Abrir archivo se muestra con el directorio actual establecido en el especificado en el nombre de archivo. Si el nombre de archivo es una cadena vacía ("") o el nombre de archivo contiene una ruta de acceso válida, pero ningún nombre de archivo o un nombre de archivo no válido, y se especifica SQL_DRIVER_NOPROMPT, se devuelve SQL_ERROR con SQLSTATE IM014 (nombre no válido de DSN de archivo).
Lee todas las palabras clave de la sección [ODBC] del archivo .dsn. Si la palabra clave DRIVER no está presente, devuelve SQL_ERROR con SQLSTATE IM012 (error de sintaxis de palabra clave driver), excepto donde el archivo .dsn no se puede compartir y, por tanto, contiene solo la palabra clave DSN .

Si el origen de datos del archivo no se puede compartir, el Administrador de controladores lee el valor de la palabra clave DSN y se conecta según sea necesario al origen de datos del usuario o del sistema al que apunta el origen de datos del archivo no compartido. No se realizan los pasos del 3 al 5.
Construye una cadena de conexión para el controlador. 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 de la aplicación original. Las reglas para la construcción de la cadena de conexión del controlador donde las palabras clave se superponen 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 iguales en el archivo .dsn y la cadena de conexión de la aplicación, se omite la información del controlador en el archivo .dsn y se usa 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 la cadena de conexión de la aplicación, donde todas las palabras clave se superponen, las especificadas en la cadena de conexión de la aplicación tienen prioridad sobre las especificadas en el archivo .dsn.
- En la nueva cadena de conexión, se elimina la palabra clave FILEDSN .
Carga el controlador buscando en la entrada del Registro HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\<Nombre> del controlador\Controlador donde <se especifica el nombre> del controlador mediante la palabra clave DRIVER .
Pasa al controlador la nueva cadena de conexiones.

Para obtener ejemplos de archivos .dsn, consulte Conexión mediante orígenes de datos de archivos.

Palabra clave SAVEFILE

Si la cadena de conexión especificada por la aplicación contiene la palabra clave SAVEFILE , el Administrador de controladores guarda la cadena de conexión en un archivo .dsn. El Administrador de controladores continúa de la siguiente manera:

Comprueba si el nombre de archivo del archivo .dsn incluido como valor de atributo de la palabra clave SAVEFILE es válido. Si no es así, devuelve SQL_ERROR con SQLSTATE IM014 (nombre no válido del DSN de archivo). La validez del nombre de archivo viene determinada por las reglas de nomenclatura del sistema estándar. Si el nombre de archivo es una cadena vacía ("") y el argumento DriverCompletion no se SQL_DRIVER_NOPROMPT, el nombre de archivo es válido. Si el nombre de archivo ya existe, si DriverCompletion es SQL_DRIVER_NOPROMPT, el archivo se sobrescribe. Si DriverCompletion está SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE o SQL_DRIVER_COMPLETE_REQUIRED, un cuadro de diálogo solicita al usuario que especifique si se debe sobrescribir el archivo. Si no se escribe, aparecerá el cuadro de diálogo Archivo-Guardar .
Si el controlador devuelve SQL_SUCCESS y el nombre de archivo no era una cadena vacía, 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 de archivo era una cadena vacía (""), el Administrador de controladores llama al cuadro de diálogo común Guardar archivo con el hwnd especificado y escribe la información de conexión devuelta 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 la cadena de conexión a la aplicación.
Si el controlador devuelve SQL_SUCCESS_WITH_INFO o SQL_ERROR, el Administrador de controladores devuelve SQLSTATE a la aplicación.

Directrices para controladores

El controlador comprueba si la cadena de conexión que le ha pasado el Administrador de controladores contiene la palabra clave DSN o DRIVER . Si la cadena de conexión contiene la palabra clave DRIVER , el controlador no puede recuperar información sobre el origen de datos de la información del sistema. Si la cadena de conexión contiene la palabra clave DSN o no contiene el DSN o la palabra clave DRIVER , el controlador puede recuperar información sobre el origen de datos 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 del origen de datos especificado.
Si la cadena de conexión no contiene la palabra clave DSN , no se encuentra el origen de datos especificado o la palabra clave DSN se establece en "DEFAULT", el controlador recupera la información del origen de datos predeterminado.

El controlador usa cualquier información que recupera de la información del sistema para aumentar la información que se le pasa en la cadena de conexión. Si la información de la información del sistema duplica la información de la cadena de conexión, el controlador usa 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 identificador de usuario y la contraseña, y se conecta al origen de datos:

SQL_DRIVER_PROMPT: el controlador muestra un cuadro de diálogo, usando los valores de la cadena de conexión e información del sistema (si existe) como valores iniciales. Cuando el usuario sale del cuadro de diálogo, el controlador se conecta al origen 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 devuelta 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 la cadena de conexión contiene suficiente información y esa información es correcta, el controlador se conecta al origen de datos y copia *InConnectionString en *OutConnectionString. Si falta información o no es correcta, el controlador realiza las mismas acciones que cuando DriverCompletion está SQL_DRIVER_PROMPT, excepto si DriverCompletion está SQL_DRIVER_COMPLETE_REQUIRED, el controlador deshabilita los controles para cualquier información que no sea necesaria para conectarse al origen de datos.
SQL_DRIVER_NOPROMPT: si la cadena de conexión contiene suficiente información, el controlador se conecta al origen de datos y copia *InConnectionString en *OutConnectionString. De lo contrario, el controlador devuelve SQL_ERROR para SQLDriverConnect.

Si la conexión se realiza correctamente al origen de datos, el controlador también establece *StringLength2Ptr en 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 Administrador de controladores o el controlador, SQLDriverConnect devuelve SQL_NO_DATA.

Para obtener información sobre cómo interactúa el Administrador de controladores y el controlador durante el proceso de conexión, vea Función SQLConnect.

Si un controlador admite SQLDriverConnect, la sección de palabras clave driver de la información del sistema para el controlador debe contener la palabra clave ConnectFunctions con el segundo carácter establecido en "Y".

Conexión cuando la agrupación de conexiones está habilitada

La agrupación de conexiones permite a una aplicación reutilizar una conexión que ya se ha creado. Cuando se llama a SQLDriverConnect , el Administrador de controladores intenta realizar la conexión mediante una conexión que forma parte de un grupo de conexiones en un entorno designado para la agrupación de conexiones. Para obtener más información sobre la agrupación de conexiones, vea Función SQLConnect.

Una aplicación puede establecer SQL_ATTR_RESET_CONNECTION antes de llamar a SQLDisconnect en una conexión en la que está habilitada la agrupación. Para obtener más información, vea Función SQLSetConnectAttr.

Las restricciones siguientes 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 se especifica la palabra clave SAVEFILE en la cadena de conexión.
Si la agrupación de conexiones está habilitada, solo se puede llamar a SQLDriverConnect con un argumento DriverCompletion de SQL_DRIVER_NOPROMPT; Si se llama a SQLDriverConnect con cualquier otra driverCompletion, se devolverá SQLSTATE HY110 (finalización del controlador no válido).

Atributos de conexión

El atributo de conexión SQL_ATTR_LOGIN_TIMEOUT, establecido mediante SQLSetConnectAttr, define el número de segundos que se deben esperar a que una solicitud de inicio de sesión se complete con una conexión correcta por el controlador antes de volver a la aplicación. Si se solicita al usuario que complete la cadena de conexión, comienza un período 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 SQL_MODE_READ_WRITE modo de acceso de forma predeterminada. Para establecer el modo de acceso en 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 el origen de datos, el controlador lo carga. Se puede cargar otra biblioteca de traducción llamando a SQLSetConnectAttr con el atributo SQL_ATTR_TRANSLATE_LIB. Se puede especificar una opción de traducción llamando a SQLSetConnectAttr con la opción SQL_ATTR_TRANSLATE_OPTION.

Para obtener más información, vea Conexión 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);  
   }  
}

Consulte también Programa ODBC de ejemplo.

Para información acerca de	Vea
Asignar un identificador	Función SQLAllocHandle
Detección y enumeración de valores necesarios para conectarse a un origen de datos	Función SQLBrowseConnect
Conectarse a un origen de datos	Función SQLConnect
Desconexión de un origen de datos	Función SQLDisconnect
Devolver descripciones y atributos del controlador	Función SQLDrivers
Liberar un identificador	Función SQLFreeHandle
Establecimiento de un atributo de conexión	Función SQLSetConnectAttr

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC

Comparteix a través de

Función SQLDriverConnect

Sintaxis

Argumentos

Devoluciones

Diagnóstico

Comentarios

Instrucciones del Administrador de controladores

Orígenes de datos de archivo

Palabra clave SAVEFILE

Directrices para controladores

Conexión cuando la agrupación de conexiones está habilitada

Atributos de conexión

Consulte también

Comentaris

Recursos addicionals

Comparteix a través de

Función SQLDriverConnect

Sintaxis

Argumentos

Devoluciones

Diagnóstico

Comentarios

Instrucciones del Administrador de controladores

Orígenes de datos de archivo

Palabra clave SAVEFILE

Directrices para controladores

Conexión cuando la agrupación de conexiones está habilitada

Atributos de conexión

Funciones relacionadas

Consulte también

Comentaris

Recursos addicionals