Función SQLDriverConnect
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.
Funciones relacionadas
| 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
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de