Función SQLConnect

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

Resumen
SQLConnect establece conexiones con un controlador y una fuente de datos. El handle de conexión hace referencia al almacenamiento de toda la información sobre la conexión a la fuente de datos, incluyendo estado, estado de la transacción e información de error.

Syntax

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

Arguments

ConnectionHandle
[Entrada] Identificador de conexión.

ServerName
[Entrada] Nombre de la fuente 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 información sobre cómo una aplicación elige una fuente de datos, consulte Elección de una fuente de datos o controlador.

NameLength1
[Entrada] Longitud de *Nombre del Servidor en caracteres.

UserName
[Entrada] Identificador de usuario.

NameLength2
[Entrada] Longitud de *Nombre de usuario en caracteres.

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

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

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE o SQL_STILL_EXECUTING.

Diagnostics

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 Handle de ConnectionHandle. La siguiente tabla enumera los valores de SQLSTATE que normalmente devuelve SQLConnect y explica cada uno en el contexto de esta función; la notación "(DM)" precede a las descripciones de los SQLSTATE devueltas por el Driver Manager. El código de retorno asociado a cada valor SQLSTATE es SQL_ERROR, a menos que se indique lo contrario.

Comentarios

Para información sobre por qué una aplicación utiliza SQLConnect, véase 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 Driver Manager funciona con sus propios mandos y gestiona 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á actualmente conectado para el HandleConnection 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 Driver Manager devuelve SQLSTATE IM006 (falló la opción SQLSetConnectOption del controlador) y SQL_SUCCESS_WITH_INFO para la función de conexión si el controlador devolvió un error para SQLSetConnectAttr. Para más información, consulte Conexión a una fuente de datos o controlador.

• Si el controlador especificado ya está conectado en el 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 del ConnectionHandle mantengan sus ajustes actuales.

• Si se conecta a otro controlador, el Gestor de Controladores llama a SQLFreeHandle con un HandleType de SQL_HANDLE_DBC y, si no hay ningún otro controlador conectado en ese entorno, llama a SQLFreeHandle con un HandleType de SQL_HANDLE_ENV en el controlador conectado y luego desconecta ese controlador. Luego realiza las mismas operaciones que cuando un controlador no está conectado.

El controlador entonces asigna manillas y se 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 aplicaciones que se conectan y desconectan repetidamente de una fuente de datos. Cuando la aplicación llama a SQLFreeHandle con un HandleType de SQL_HANDLE_DBC, el Driver Manager llama a SQLFreeHandle con un HandleType de SQL_HANDLE_DBC y luego SQLFreeHandle con un HandleType de SQL_HANDLE_ENV en el controlador, y después desconecta el controlador.

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

Directrices para el Gestor de Pilotos

El contenido de *NombreServidor afecta a cómo el Administrador de Controladores y un controlador trabajan juntos para establecer una conexión con una fuente de datos.

• Si *NameServidor contiene un nombre válido de fuente de datos, el Gestor de Controladores localiza la especificación correspondiente de la fuente de datos 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 puede encontrar el nombre de la fuente de datos o ServerName es un puntero nulo, el Driver Manager localiza la especificación predeterminada de la fuente de datos y se conecta al controlador asociado. El Administrador de Controladores pasa al controlador los argumentos de Nombre de Usuario y Autenticación sin modificar, y "DEFAULT" para el argumento Nombreservidor .

• Si el argumento Nombreservidor es "DEFAULT", el Administrador de Controladores localiza la especificación de la fuente de datos predeterminada y se conecta al controlador asociado. El Administrador de Controladores pasa cada argumento SQLConnect al controlador.

• Si no se puede encontrar el nombre de la fuente de datos o ServerName es un puntero nulo, y la especificación predeterminada de la fuente de datos no existe, el Driver Manager SQL_ERROR devuelve con SQLSTATE IM002 (Nombre de la fuente de datos no encontrado y sin driver predeterminado especificado).

Una vez que el Driver Manager lo conecta, el driver puede localizar su especificación de fuente de datos correspondiente en la información del sistema y utilizar la información específica del driver de dicha especificación para completar su conjunto de datos de conexión requeridos.

Si se especifica una biblioteca de traducción predeterminada en la información del sistema para la fuente de datos, el controlador se conecta a ella. Se puede conectar a una biblioteca de traducción diferente llamando 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 soporta SQLConnect, la sección de la palabra clave del controlador en la información del sistema debe contener la palabra clave ConnectFunctions con el primer carácter asignado a "Y".

Agrupar conexiones

El pooling de conexiones permite a una aplicación reutilizar una conexión que ya ha sido creada. Cuando se habilita la agrupación de conexiones y se llama a SQLConnect , el Gestor de Controladores intenta establecer la conexión utilizando una conexión que forma parte de un conjunto de conexiones en un entorno designado para la agrupación de conexiones. Este entorno es compartido y utilizado por todas las aplicaciones que utilizan las conexiones del pool.

El pooling de conexiones se habilita antes de asignar el entorno llamando a SQLSetEnvAttr para establecer SQL_ATTR_CONNECTION_POOLING a SQL_CP_ONE_PER_DRIVER (que especifica un máximo de un pool por driver) o SQL_CP_ONE_PER_HENV (que especifica un máximo de un pool por entorno). SQLSetEnvAttr en este caso se llama con EnvironmentHandle configurado en null, lo que convierte el atributo en un atributo a nivel de proceso. Si SQL_ATTR_CONNECTION_POOLING está configurado en SQL_CP_OFF, la agrupación de conexiones queda desactivada.

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 utilizará 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 Driver Manager intenta encontrar un entorno compartido existente que coincida con los atributos del entorno establecidos por la aplicación. Si no existe tal entorno, se crea uno como un entorno compartido implícito. Si se encuentra un entorno compartido coincidente, el handle del entorno se devuelve a la aplicación y su número de referencias se incrementa.

Sin embargo, la conexión que se usará no se determina hasta que se llama a SQLConnect . En ese momento, el Driver Manager intenta encontrar una conexión existente en el pool de conexiones que cumpla 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 NombreServidor, Nombre de Usuario y Autenticación ) y cualquier atributo de conexión establecido desde que SQLAllocHandle con un HandleType de SQL_HANDLE_DBC se llamó. El Driver Manager comprueba estos criterios con las palabras clave y atributos de conexión correspondientes en las conexiones del pool. Si se encuentra una coincidencia, se utiliza la conexión en el pool. Si no se encuentra ninguna coincidencia, se crea una nueva conexión.

Si el atributo de SQL_ATTR_CP_MATCH entorno está configurado como SQL_CP_STRICT_MATCH, la coincidencia debe ser exacta para que se utilice una conexión en el pool. Si el atributo de entorno SQL_ATTR_CP_MATCH está configurado como SQL_CP_RELAXED_MATCH, las opciones de conexión en la llamada a SQLConnect deben coincidir, pero no todos los atributos de conexión deben coincidir.

Las siguientes reglas se aplican cuando un atributo de conexión, tal como lo establece la aplicación antes de que se llame a SQLConnect , no coincide con el atributo de conexión de la conexión en el pool:

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

  Si SQL_ATTR_CP_MATCH es SQL_CP_STRICT_MATCH, SQL_ATTR_PACKET_SIZE en 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 pareja.

• Si el atributo de conexión puede establecerse antes o después de que se realice la conexión:

  Si el atributo de conexión no ha sido establecido por la aplicación pero sí en la conexión del pool, y hay un valor por defecto, el atributo de conexión en la conexión agrupada se vuelve a establecer al valor predeterminado y se declara una coincidencia. Si no hay defecto, la conexión agrupada no se considera una coincidencia.

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

  Si el atributo de conexión ha sido establecido por la aplicación, y también se ha establecido en la conexión del pool pero los valores son diferentes, se utiliza 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, la conexión en el pool no se utiliza.

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

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

Cuando hay transacciones distribuidas, es posible optimizar el rendimiento de la agrupación de conexiones usando SQL_DTC_TRANSITION_COST, que es una máscara de bits SQLUINTE. Las transiciones a las que se refiere son las transiciones del atributo de conexión SQL_ATTR_ENLIST_IN_DTC que van de 0 a distinto de cero, y viceversa. Esta es una conexión que va de no estar listado en una transacción distribuida a estar listado en una transacción distribuida, y viceversa. Dependiendo 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 lograr un mejor rendimiento.

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

• SQL_DTC_ENLIST_EXPENSIVE, cuando se establece, implica que la transición de cero a no nulo es significativamente más costosa que una transición de valor no nulo a otro valor no nulo (involucrando una conexión previamente registrada en su siguiente transacción).

• SQL_DTC_UNENLIST_EXPENSIVE, cuando se establece, implica que la transición no de cero a cero es significativamente más costosa que usar una conexión cuyo atributo SQL_ATTR_ENLIST_IN_DTC ya está en cero.

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

Los controladores que no soportan SQL_ATTR_ENLIST_IN_DTC no necesitan soportar SQL_DTC_TRANSITION_COST. Para los controladores que soportan SQL_ATTR_ENLIST_IN_DTC pero no SQL_DTC_TRANSITION_COST, se asume que las transiciones no son costosas, como si el controlador devolviera 0 (sin bits activados) para este valor.

Aunque SQL_DTC_TRANSITION_COST se introdujo en ODBC 3.5, un ODBC 2. El controlador X también puede soportarlo porque el gestor de controladores consultará esta información independientemente de la versión del controlador.

Ejemplo de código

En el siguiente ejemplo, una aplicación asigna el entorno y los handlers de conexión. Luego se conecta a la fuente de datos de SalesOrders con el ID de usuario JohnS y la contraseña Sesame y procesa los datos. Cuando termina de procesar datos, se desconecta de la fuente de datos y libera los handles.

// 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);  
   }  
}  

Funciones relacionadas

Véase también

Referencia de la API ODBC
Archivos de encabezado de ODBC