Función SQLConnect

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.

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

Funciones relacionadas

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC