Función SQLConnect

Artículo
05/23/2023

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

Resumen
SQLConnect establece conexiones a un controlador y a un origen de datos. La conexión controla el almacenamiento de referencias de toda la información sobre la conexión al origen de datos, incluido el estado, el estado de la transacción y la información de error.

Sintaxis

  
SQLRETURN SQLConnect(  
     SQLHDBC        ConnectionHandle,  
     SQLCHAR *      ServerName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      UserName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      Authentication,  
     SQLSMALLINT    NameLength3);

Argumentos

ConnectionHandle
[Entrada] Identificador de conexión.

ServerName
[Entrada] Nombre del origen de datos. Los datos pueden encontrarse en el mismo equipo que el programa o en otro equipo en algún lugar de una red. Para obtener información sobre cómo una aplicación elige un origen de datos, consulte Elección de un origen de datos o un controlador.

NameLength1
[Entrada] Longitud de *ServerName en caracteres.

UserName
[Entrada] Identificador de usuario.

NameLength2
[Entrada] Longitud de *UserName en caracteres.

Autenticación
[Entrada] Cadena de autenticación (normalmente la contraseña).

NameLength3
[Entrada] Longitud de *Autenticación en caracteres.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE o SQL_STILL_EXECUTING.

Diagnóstico

Cuando SQLConnect devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando a SQLGetDiagRec con un HandleType de SQL_HANDLE_DBC y un identificador de ConnectionHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLConnect 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).
01S02	Valor de opción cambiado	El controlador no admitía el valor especificado del argumento ValuePtr en SQLSetConnectAttr y sustituyó un valor similar. (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 o el usuario estaba navegando por una conexión.
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 completara el procesamiento.
28000	Especificación de autorización no válida	Valor especificado para el argumento UserName o el valor especificado para el argumento Authentication infringido 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 *MessageText describe el error y su causa.
HY001	Error de asignación de memoria	(DM) El Administrador de controladores 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 SQLConnect 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 SQLConnect de nuevo en ConnectionHandle. O bien, se llamó a la función SQLConnect 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 una función que ejecuta de forma asincrónica (no esta) para ConnectionHandle y todavía se estaba ejecutando cuando se llamó a esta función.
HY013	Error de administración de memoria	No se pudo procesar la llamada de función 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 NameLength1, NameLength2 o NameLength3 era menor que 0, pero no igual a SQL_NTS. (DM) El valor especificado para el argumento NameLength1 superó la longitud máxima de un nombre de origen de datos.
HYT00	Tiempo de espera agotado	El período de tiempo de espera de la consulta 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.
HY114	El controlador no admite la ejecución asincrónica de funciones asincrónicas de nivel de conexión	(DM) La aplicación habilitó la operación asincrónica en el identificador de conexión antes de realizar la conexión. Sin embargo, el controlador no admite operaciones asincrónicas en el identificador de conexión.
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 especificado por el nombre del origen de datos 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 el argumento ServerName no se encontró en la información del sistema, ni había una especificación de controlador predeterminada.
IM003	No se pudo conectar el controlador especificado a	(DM) El controlador enumerado en la especificación del origen de datos en la información del sistema no se encontró o no se pudo conectar a por algún otro motivo.
IM004	Error de SQLAllocHandle del controlador en SQL_HANDLE_ENV	(DM) Durante SQLConnect, el Administrador de controladores llamó a la función SQLAllocHandle del controlador con un HandleType de SQL_HANDLE_ENV y el controlador devolvió un error.
IM005	Error de SQLAllocHandle del controlador en SQL_HANDLE_DBC	(DM) Durante SQLConnect, el Administrador de controladores llamó a la función SQLAllocHandle del controlador con un HandleType de SQL_HANDLE_DBC y el controlador devolvió un error.
IM006	Error de SQLSetConnectAttr del controlador	Durante SQLConnect, el Administrador de controladores llamó a la función SQLSetConnectAttr del controlador y el controlador devolvió un error. (Function devuelve SQL_SUCCESS_WITH_INFO).
IM009	No se puede conectar al archivo DLL de traducción	El controlador no pudo conectarse al archivo DLL de traducción especificado para el origen de datos.
IM010	Nombre del origen de datos demasiado largo	(DM) *ServerName tenía más de SQL_MAX_DSN_LENGTH caracteres.
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 SQLConnect 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

Para obtener información sobre por qué una aplicación usa SQLConnect, consulte Conexión con SQLConnect.

El Administrador de controladores no se conecta a un controlador hasta que la aplicación llama a una función (SQLConnect, SQLDriverConnect o SQLBrowseConnect) para conectarse al controlador. Hasta ese momento, el Administrador de controladores funciona con sus propios identificadores y administra la información de conexión. Cuando la aplicación llama a una función de conexión, el Administrador de controladores comprueba si un controlador está conectado actualmente a para el connectionHandle especificado:

Si un controlador no está conectado, el Administrador de controladores se conecta al controlador y llama a SQLAllocHandle con un HandleType de SQL_HANDLE_ENV, SQLAllocHandle con un HandleType de SQL_HANDLE_DBC, SQLSetConnectAttr (si la aplicación especificó algún atributo de conexión) y la función de conexión en el controlador. El Administrador de controladores devuelve SQLSTATE IM006 (error de SQLSetConnectOption del controlador) y SQL_SUCCESS_WITH_INFO para la función de conexión si el controlador devolvió un error para SQLSetConnectAttr. Para obtener más información, consulte Conexión a un origen de datos o controlador.
Si el controlador especificado ya está conectado a en ConnectionHandle, el Administrador de controladores llama solo a la función de conexión en el controlador. En este caso, el controlador debe asegurarse de que todos los atributos de conexión para ConnectionHandle mantienen su configuración actual.
Si se conecta un controlador diferente, el Administrador de controladores llama a SQLFreeHandle con un HandleType de SQL_HANDLE_DBC y, a continuación, si ningún otro controlador está conectado a en ese entorno, llama a SQLFreeHandle con un HandleType de SQL_HANDLE_ENV en el controlador conectado y, a continuación, desconecta ese controlador. A continuación, realiza las mismas operaciones que cuando un controlador no está conectado a .

A continuación, el controlador asigna identificadores e inicializa a sí mismo.

Cuando la aplicación llama a SQLDisconnect, el Administrador de controladores llama a SQLDisconnect en el controlador. Sin embargo, no desconecta el controlador. Esto mantiene el controlador en memoria para las aplicaciones que se conectan y desconectan repetidamente de un origen de datos. Cuando la aplicación llama a SQLFreeHandle con un HandleType de SQL_HANDLE_DBC, el Administrador de controladores llama a SQLFreeHandle con un HandleType de SQL_HANDLE_DBC y, a continuación, SQLFreeHandle con un HandleType de SQL_HANDLE_ENV en el controlador y, a continuación, desconecta el controlador.

Una aplicación ODBC puede establecer más de una conexión.

Instrucciones del Administrador de controladores

El contenido de *ServerName afecta a cómo funcionan conjuntamente el Administrador de controladores y un controlador para establecer una conexión a un origen de datos.

Si *ServerName contiene un nombre de origen de datos válido, el Administrador de controladores busca la especificación de origen de datos correspondiente en la información del sistema y se conecta al controlador asociado. El Administrador de controladores pasa cada argumento SQLConnect al controlador.
Si no se encuentra el nombre del origen de datos o ServerName es un puntero nulo, el Administrador de controladores busca la especificación predeterminada del origen de datos y se conecta al controlador asociado. El Administrador de controladores pasa al controlador los argumentos UserName y Authentication sin modificar y "DEFAULT" para el argumento ServerName .
Si el argumento ServerName es "DEFAULT", el Administrador de controladores busca la especificación predeterminada del origen de datos y se conecta al controlador asociado. El Administrador de controladores pasa cada argumento SQLConnect al controlador.
Si no se encuentra el nombre del origen de datos o ServerName es un puntero nulo y la especificación predeterminada del origen de datos no existe, el Administrador de controladores devuelve SQL_ERROR con SQLSTATE IM002 (no se encontró el nombre del origen de datos y no se ha especificado ningún controlador predeterminado).

Después de conectarse a él por el Administrador de controladores, un controlador puede localizar su especificación de origen de datos correspondiente en la información del sistema y usar información específica del controlador de la especificación para completar su conjunto de información de conexión necesaria.

Si se especifica una biblioteca de traducción predeterminada en la información del sistema para el origen de datos, el controlador se conecta a ella. Una biblioteca de traducción diferente se puede conectar mediante una llamada a SQLSetConnectAttr con el atributo SQL_ATTR_TRANSLATE_LIB. Se puede especificar una opción de traducción llamando a SQLSetConnectAttr con el atributo SQL_ATTR_TRANSLATE_OPTION.

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

Agrupar conexiones

La agrupación de conexiones permite a una aplicación reutilizar una conexión que ya se ha creado. Cuando se habilita la agrupación de conexiones y se llama a SQLConnect , el Administrador de controladores intenta establecer 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. Este entorno es un entorno compartido que usan todas las aplicaciones que usan las conexiones del grupo.

La agrupación de conexiones está habilitada antes de que se asigne el entorno llamando a SQLSetEnvAttr para establecer SQL_ATTR_CONNECTION_POOLING en SQL_CP_ONE_PER_DRIVER (que especifica un máximo de un grupo por controlador) o SQL_CP_ONE_PER_HENV (que especifica un máximo de un grupo por entorno). En este caso, se llama a SQLSetEnvAttr con EnvironmentHandle establecido en null, lo que convierte el atributo en un atributo de nivel de proceso. Si SQL_ATTR_CONNECTION_POOLING se establece en SQL_CP_OFF, la agrupación de conexiones está deshabilitada.

Una vez habilitada la agrupación de conexiones, se llama a SQLAllocHandle con un HandleType de SQL_HANDLE_ENV para asignar un entorno. El entorno asignado por esta llamada es un entorno compartido porque se ha habilitado la agrupación de conexiones. Sin embargo, el entorno que se usará no se determina hasta que se llama a SQLAllocHandle con un HandleType de SQL_HANDLE_DBC.

SE llama a SQLAllocHandle con un HandleType de SQL_HANDLE_DBC para asignar una conexión. El Administrador de controladores intenta encontrar un entorno compartido existente que coincida con los atributos de entorno establecidos por la aplicación. Si no existe este entorno, se crea uno como un entorno compartido implícito. Si se encuentra un entorno compartido coincidente, se devuelve el identificador de entorno a la aplicación y se incrementa su recuento de referencias.

Sin embargo, la conexión que se usará no se determina hasta que se llame a SQLConnect . En ese momento, el Administrador de controladores intenta encontrar una conexión existente en el grupo de conexiones que coincida con los criterios solicitados por la aplicación. Estos criterios incluyen las opciones de conexión solicitadas en la llamada a SQLConnect (los valores de las palabras clave ServerName, UserName y Authentication ) y los atributos de conexión establecidos desde que se llamó a SQLAllocHandle con un HandleType de SQL_HANDLE_DBC. El Administrador de controladores comprueba estos criterios con respecto a las palabras clave y atributos de conexión correspondientes en las conexiones del grupo. Si se encuentra una coincidencia, se usa la conexión en el grupo. Si no se encuentra ninguna coincidencia, se crea una nueva conexión.

Si el atributo de entorno de SQL_ATTR_CP_MATCH se establece en SQL_CP_STRICT_MATCH, la coincidencia debe ser exacta para que se use una conexión en el grupo. Si el atributo de entorno SQL_ATTR_CP_MATCH se establece en SQL_CP_RELAXED_MATCH, las opciones de conexión de la llamada a SQLConnect deben coincidir, pero no todos los atributos de conexión deben coincidir.

Las reglas siguientes se aplican cuando se llama a un atributo de conexión, tal y como establece la aplicación antes de llamar a SQLConnect , no coincide con el atributo de conexión de la conexión en el grupo:

Si el atributo de conexión debe establecerse antes de que se realice la conexión:

Si SQL_ATTR_CP_MATCH es SQL_CP_STRICT_MATCH, SQL_ATTR_PACKET_SIZE de la conexión agrupada debe ser idéntica al atributo establecido por la aplicación. Si SQL_CP_RELAXED_MATCH, los valores de SQL_ATTR_PACKET_SIZE pueden ser diferentes.

El valor de SQL_ATTR_LOGIN_VALUE no afecta a la coincidencia.
Si el atributo de conexión se puede establecer antes o después de que se realice la conexión:

Si la aplicación no ha establecido el atributo de conexión, pero se ha establecido en la conexión del grupo y hay un valor predeterminado, el atributo de conexión de la conexión agrupada se vuelve a establecer en el valor predeterminado y se declara una coincidencia. Si no hay ningún valor predeterminado, la conexión agrupada no se considera una coincidencia.

Si la aplicación ha establecido el atributo de conexión, pero no se ha establecido en la conexión del grupo, el atributo de conexión del grupo cambia a ese establecido por la aplicación y se declara una coincidencia.

Si la aplicación ha establecido el atributo de conexión y también se ha establecido en la conexión del grupo, pero los valores son diferentes, se usa el valor del atributo de conexión de la aplicación y se declara una coincidencia.
Si los valores de los atributos de conexión específicos del controlador no son idénticos y SQL_ATTR_CP_MATCH se establece en SQL_CP_STRICT_MATCH, no se usa la conexión del grupo.

Cuando la aplicación llama a SQLDisconnect para desconectarse, la conexión se devuelve al grupo de conexiones y está disponible para su reutilización.

Optimización del rendimiento de la agrupación de conexiones

Cuando intervienen transacciones distribuidas, es posible optimizar el rendimiento de agrupación de conexiones mediante SQL_DTC_TRANSITION_COST, que es una máscara de bits SQLUINTEGER. Las transiciones a las que se hace referencia son las transiciones del atributo de conexión SQL_ATTR_ENLIST_IN_DTC que van del valor 0 al distinto de cero y viceversa. Se trata de una conexión que va de no estar incluida en una transacción distribuida para inscribirse en una transacción distribuida y viceversa. En función de cómo el controlador haya implementado la inscripción (establecer el atributo de conexión SQL_ATTR_ENLIST_IN_DTC), estas transiciones pueden ser costosas y, por tanto, deben evitarse para mejorar el rendimiento.

El valor devuelto por el controlador contiene cualquier combinación de los bits siguientes:

SQL_DTC_ENLIST_EXPENSIVE, cuando se establece, implica que la transición cero a cero es significativamente más costosa que una transición de cero a otro valor distinto de cero (al dar de alta una conexión previamente incluida en su siguiente transacción).
SQL_DTC_UNENLIST_EXPENSIVE, cuando se establece, implica que la transición distinta de cero es significativamente más costosa que el uso de una conexión cuyo atributo SQL_ATTR_ENLIST_IN_DTC ya está establecido en cero.

Hay un equilibrio entre el rendimiento y el uso de la conexión. Si un controlador indica que una o varias de estas transiciones son costosas, el agrupador de conexiones del administrador de controladores responde a esto manteniendo más conexiones en el grupo. Algunas de las conexiones del grupo son preferidas para el uso no transaccional y algunas son preferidas para el uso transaccional. Sin embargo, si el controlador indica que estas transiciones no son costosas, se pueden usar menos conexiones, quizás alternando entre el uso transaccional y no transaccional.

Los controladores que no admiten SQL_ATTR_ENLIST_IN_DTC no necesitan admitir SQL_DTC_TRANSITION_COST. En el caso de los controladores que admiten SQL_ATTR_ENLIST_IN_DTC pero no SQL_DTC_TRANSITION_COST, se supone que las transiciones no son costosas, como si el controlador devolviera 0 (sin conjuntos de bits) para este valor.

Aunque SQL_DTC_TRANSITION_COST se introdujo en ODBC 3.5, odbc 2. El controlador x también puede admitirlo porque el administrador de controladores consultará esta información independientemente de la versión del controlador.

Ejemplo de código

En el ejemplo siguiente, una aplicación asigna identificadores de entorno y conexión. A continuación, se conecta al origen de datos SalesOrders con el identificador de usuario JohnS y el sésamo de contraseña y procesa los datos. Cuando haya terminado de procesar los datos, se desconecta del origen de datos y libera los identificadores.

// SQLConnect_ref.cpp  
// compile with: odbc32.lib  
#include <windows.h>  
#include <sqlext.h>  
  
int main() {  
   SQLHENV henv;  
   SQLHDBC hdbc;  
   SQLHSTMT hstmt;  
   SQLRETURN retcode;  
  
   SQLCHAR * OutConnStr = (SQLCHAR * )malloc(255);  
   SQLSMALLINT * OutConnStrLen = (SQLSMALLINT *)malloc(255);  
  
   // 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, (void*)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);  
  
            // Connect to data source  
            retcode = SQLConnect(hdbc, (SQLCHAR*) "NorthWind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
  
            // 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);  
   }  
}

Para información acerca de	Vea
Asignación de un identificador	Función SQLAllocHandle
Detección y enumeración de valores necesarios para conectarse a un origen de datos	Función SQLBrowseConnect
Desconexión de un origen de datos	Función SQLDisconnect
Conexión a un origen de datos mediante una cadena de conexión o un cuadro de diálogo	Función SQLDriverConnect
Devolver la configuración de un atributo de conexión	Función SQLGetConnectAttr
Establecimiento de un atributo de conexión	Función SQLSetConnectAttr

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC

Función SQLConnect

Sintaxis

Argumentos

Devoluciones

Diagnóstico

Comentarios

Instrucciones del Administrador de controladores

Agrupar conexiones

Optimización del rendimiento de la agrupación de conexiones

Ejemplo de código

Funciones relacionadas

Consulte también

Comentarios

Comentarios

Recursos adicionales