Fonction SQLConnect

Conformité
Version introduite : Conformité aux normes ODBC 1.0 : ISO 92

Résumé
SQLConnect établit des connexions à un pilote et à une source de données. Le handle de connexion référence le stockage de toutes les informations sur la connexion à la source de données, y compris l’état, l’état de la transaction et les informations d’erreur.

Syntaxe

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

Arguments

ConnectionHandle
[Entrée] Handle de connexion.

ServerName
[Entrée] Nom de la source de données. Les données peuvent se trouver sur le même ordinateur que le programme ou sur un autre ordinateur quelque part sur un réseau. Pour plus d’informations sur la façon dont une application choisit une source de données, consultez Choix d’une source de données ou d’un pilote.

NameLength1
[Entrée] Longueur de *ServerName en caractères.

UserName
[Entrée] Identificateur d’utilisateur.

NameLength2
[Entrée] Longueur de *UserName en caractères.

Authentification
[Entrée] Chaîne d’authentification (généralement le mot de passe).

NameLength3
[Entrée] Longueur de *Authentification en caractères.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_STILL_EXECUTING.

Diagnostics

Lorsque SQLConnect retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec un HandleType de SQL_HANDLE_DBC et un handle de ConnectionHandle. Le tableau suivant répertorie les valeurs SQLSTATE généralement retournées par SQLConnect et explique chacune d’elles dans le contexte de cette fonction ; la notation « (DM) » précède les descriptions de SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.

Commentaires

Pour plus d’informations sur la raison pour laquelle une application utilise SQLConnect, consultez Connexion à SQLConnect.

Le Gestionnaire de pilotes ne se connecte pas à un pilote tant que l’application n’appelle pas une fonction (SQLConnect, SQLDriverConnect ou SQLBrowseConnect) pour se connecter au pilote. Jusqu’à ce stade, le Gestionnaire de pilotes fonctionne avec ses propres handles et gère les informations de connexion. Lorsque l’application appelle une fonction de connexion, le Gestionnaire de pilotes vérifie si un pilote est actuellement connecté à pour le ConnectionHandle spécifié :

• Si un pilote n’est pas connecté à, le Gestionnaire de pilotes se connecte au pilote et appelle SQLAllocHandle avec un HandleType de SQL_HANDLE_ENV, SQLAllocHandle avec un HandleType de SQL_HANDLE_DBC, SQLSetConnectAttr (si l’application a spécifié des attributs de connexion) et la fonction de connexion dans le pilote. Le Gestionnaire de pilotes retourne SQLSTATE IM006 (échec de SQLSetConnectOption du pilote) et SQL_SUCCESS_WITH_INFO pour la fonction de connexion si le pilote a retourné une erreur pour SQLSetConnectAttr. Pour plus d’informations, consultez Connexion à une source de données ou à un pilote.

• Si le pilote spécifié est déjà connecté à sur connectionHandle, le Gestionnaire de pilotes appelle uniquement la fonction de connexion dans le pilote. Dans ce cas, le pilote doit s’assurer que tous les attributs de connexion pour connectionHandle conservent leurs paramètres actuels.

• Si un autre pilote est connecté à, le Gestionnaire de pilotes appelle SQLFreeHandle avec un HandleType de SQL_HANDLE_DBC, puis, si aucun autre pilote n’est connecté dans cet environnement, il appelle SQLFreeHandle avec un HandleType de SQL_HANDLE_ENV dans le pilote connecté, puis déconnecte ce pilote. Il effectue ensuite les mêmes opérations que lorsqu’un pilote n’est pas connecté.

Le pilote alloue ensuite des handles et s’initialise lui-même.

Lorsque l’application appelle SQLDisconnect, le Gestionnaire de pilotes appelle SQLDisconnect dans le pilote. Toutefois, il ne déconnecte pas le pilote. Cela conserve le pilote en mémoire pour les applications qui se connectent à une source de données et se déconnectent à plusieurs reprises. Lorsque l’application appelle SQLFreeHandle avec un HandleType de SQL_HANDLE_DBC, le Gestionnaire de pilotes appelle SQLFreeHandle avec un HandleType de SQL_HANDLE_DBC, puis SQLFreeHandle avec un HandleType de SQL_HANDLE_ENV dans le pilote, puis déconnecte le pilote.

Une application ODBC peut établir plusieurs connexions.

Instructions du gestionnaire de pilotes

Le contenu de *ServerName affecte la façon dont le Gestionnaire de pilotes et un pilote travaillent ensemble pour établir une connexion à une source de données.

• Si *ServerName contient un nom de source de données valide, le Gestionnaire de pilotes localise la spécification de source de données correspondante dans les informations système et se connecte au pilote associé. Le Gestionnaire de pilotes transmet chaque argument SQLConnect au pilote.

• Si le nom de la source de données est introuvable ou si ServerName est un pointeur Null, le Gestionnaire de pilotes localise la spécification de la source de données par défaut et se connecte au pilote associé. Le Gestionnaire de pilotes transmet au pilote les arguments UserName et Authentication non modifiés, et « DEFAULT » pour l’argument ServerName .

• Si l’argument ServerName est « DEFAULT », le Gestionnaire de pilotes localise la spécification de source de données par défaut et se connecte au pilote associé. Le Gestionnaire de pilotes transmet chaque argument SQLConnect au pilote.

• Si le nom de la source de données est introuvable ou si ServerName est un pointeur Null et que la spécification de source de données par défaut n’existe pas, le Gestionnaire de pilotes retourne SQL_ERROR avec SQLSTATE IM002 (nom de la source de données introuvable et aucun pilote par défaut spécifié).

Une fois connecté à par le Gestionnaire de pilotes, un pilote peut localiser sa spécification de source de données correspondante dans les informations système et utiliser les informations spécifiques au pilote de la spécification pour compléter son ensemble d’informations de connexion requises.

Si une bibliothèque de traduction par défaut est spécifiée dans les informations système de la source de données, le pilote s’y connecte. Une bibliothèque de traduction différente peut être connectée en appelant SQLSetConnectAttr avec l’attribut SQL_ATTR_TRANSLATE_LIB. Vous pouvez spécifier une option de traduction en appelant SQLSetConnectAttr avec l’attribut SQL_ATTR_TRANSLATE_OPTION.

Si un pilote prend en charge SQLConnect, la section du mot clé pilote des informations système du pilote doit contenir le mot clé ConnectFunctions avec le premier caractère défini sur « Y ».

Regroupement de connexions

Le regroupement de connexions permet à une application de réutiliser une connexion qui a déjà été créée. Lorsque le regroupement de connexions est activé et que SQLConnect est appelé, le Gestionnaire de pilotes tente d’établir la connexion à l’aide d’une connexion qui fait partie d’un pool de connexions dans un environnement qui a été désigné pour le regroupement de connexions. Cet environnement est un environnement partagé qui est utilisé par toutes les applications qui utilisent les connexions dans le pool.

Le regroupement de connexions est activé avant l’allocation de l’environnement en appelant SQLSetEnvAttr pour définir SQL_ATTR_CONNECTION_POOLING sur SQL_CP_ONE_PER_DRIVER (qui spécifie un pool maximum par pilote) ou SQL_CP_ONE_PER_HENV (qui spécifie un pool maximum par environnement). DANS ce cas, SQLSetEnvAttr est appelé avec EnvironmentHandle défini sur null, ce qui fait de l’attribut un attribut au niveau du processus. Si SQL_ATTR_CONNECTION_POOLING est défini sur SQL_CP_OFF, le regroupement de connexions est désactivé.

Une fois le regroupement de connexions activé, SQLAllocHandle avec un HandleType de SQL_HANDLE_ENV est appelé pour allouer un environnement. L’environnement alloué par cet appel est un environnement partagé, car le regroupement de connexions a été activé. Toutefois, l’environnement qui sera utilisé n’est pas déterminé tant que SQLAllocHandle avec un HandleType de SQL_HANDLE_DBC n’est pas appelé.

SQLAllocHandle avec un HandleType de SQL_HANDLE_DBC est appelé pour allouer une connexion. Le Gestionnaire de pilotes tente de trouver un environnement partagé existant qui correspond aux attributs d’environnement définis par l’application. S’il n’existe aucun environnement de ce type, un environnement est créé en tant qu’environnement partagé implicite. Si un environnement partagé correspondant est trouvé, le handle d’environnement est retourné à l’application et son nombre de références est incrémenté.

Toutefois, la connexion qui sera utilisée n’est pas déterminée tant que SQLConnect n’est pas appelé. À ce stade, le Gestionnaire de pilotes tente de trouver une connexion existante dans le pool de connexions qui correspond aux critères demandés par l’application. Ces critères incluent les options de connexion demandées dans l’appel à SQLConnect (les valeurs des mots clés ServerName, UserName et Authentication ) et tous les attributs de connexion définis depuis que SQLAllocHandle avec un HandleType de SQL_HANDLE_DBC a été appelé. Le Gestionnaire de pilotes vérifie ces critères par rapport aux mots clés et attributs de connexion correspondants dans les connexions dans le pool. Si une correspondance est trouvée, la connexion dans le pool est utilisée. Si aucune correspondance n’est trouvée, une nouvelle connexion est créée.

Si l’attribut d’environnement SQL_ATTR_CP_MATCH est défini sur SQL_CP_STRICT_MATCH, la correspondance doit être exacte pour qu’une connexion dans le pool soit utilisée. Si l’attribut d’environnement SQL_ATTR_CP_MATCH est défini sur SQL_CP_RELAXED_MATCH, les options de connexion dans l’appel à SQLConnect doivent correspondre, mais tous les attributs de connexion ne doivent pas correspondre.

Les règles suivantes sont appliquées lorsqu’un attribut de connexion, tel que défini par l’application avant l’appel de SQLConnect , ne correspond pas à l’attribut de connexion de la connexion dans le pool :

• Si l’attribut de connexion doit être défini avant d’établir la connexion :

  Si SQL_ATTR_CP_MATCH est SQL_CP_STRICT_MATCH, SQL_ATTR_PACKET_SIZE dans la connexion mise en pool doit être identique à l’attribut défini par l’application. Si SQL_CP_RELAXED_MATCH, les valeurs de SQL_ATTR_PACKET_SIZE peuvent être différentes.

  La valeur de SQL_ATTR_LOGIN_VALUE n’affecte pas la correspondance.

• Si l’attribut de connexion peut être défini avant ou après la connexion :

  Si l’attribut de connexion n’a pas été défini par l’application, mais qu’il a été défini sur la connexion dans le pool et qu’il existe une valeur par défaut, l’attribut de connexion dans la connexion mise en pool est rétabli sur la valeur par défaut et une correspondance est déclarée. S’il n’existe aucune valeur par défaut, la connexion mise en pool n’est pas considérée comme une correspondance.

  Si l’attribut de connexion a été défini par l’application mais n’a pas été défini sur la connexion dans le pool, l’attribut de connexion sur le pool est remplacé par celui défini par l’application et une correspondance est déclarée.

  Si l’attribut de connexion a été défini par l’application et qu’il a également été défini sur la connexion dans le pool, mais que les valeurs sont différentes, la valeur de l’attribut de connexion de l’application est utilisée et une correspondance est déclarée.

• Si les valeurs des attributs de connexion spécifiques au pilote ne sont pas identiques et que SQL_ATTR_CP_MATCH est défini sur SQL_CP_STRICT_MATCH, la connexion dans le pool n’est pas utilisée.

Lorsque l’application appelle SQLDisconnect pour se déconnecter, la connexion est retournée au pool de connexions et peut être réutilisée.

Optimisation des performances du regroupement de connexions

Lorsque des transactions distribuées sont impliquées, il est possible d’optimiser les performances de regroupement de connexions à l’aide de SQL_DTC_TRANSITION_COST, qui est un masque de bits SQLUINTEGER. Les transitions mentionnées sont les transitions de l’attribut de connexion SQL_ATTR_ENLIST_IN_DTC allant de la valeur 0 à une valeur différente de zéro, et inversement. Il s’agit d’une connexion allant de non inscrit dans une transaction distribuée à inscrit dans une transaction distribuée, et inversement. Selon la façon dont le pilote a implémenté l’inscription (définition de l’attribut de connexion SQL_ATTR_ENLIST_IN_DTC), ces transitions peuvent être coûteuses et doivent donc être évitées pour de meilleures performances.

La valeur retournée par le pilote contient n’importe quelle combinaison des bits suivants :

• SQL_DTC_ENLIST_EXPENSIVE, lorsqu’elle est définie, implique que la transition de zéro à zéro est beaucoup plus coûteuse qu’une transition de zéro à une autre valeur différente de zéro (inscription d’une connexion précédemment inscrite dans sa transaction suivante).

• SQL_DTC_UNENLIST_EXPENSIVE, lorsqu’il est défini, implique que la transition de zéro à zéro est beaucoup plus coûteuse que l’utilisation d’une connexion dont l’attribut SQL_ATTR_ENLIST_IN_DTC est déjà défini sur zéro.

Il existe un compromis entre l’utilisation des performances et de l’utilisation de la connexion. Si un pilote indique qu’une ou plusieurs de ces transitions sont coûteuses, le pooleur de connexions du gestionnaire de pilotes répond à cela en conservant plus de connexions dans le pool. Certaines des connexions dans le pool sont recommandées pour une utilisation non transactionnelle, et d’autres pour une utilisation transactionnelle. Toutefois, si le pilote indique que ces transitions ne sont pas coûteuses, moins de connexions peuvent être utilisées, en alternant peut-être entre l’utilisation non transactionnelle et l’utilisation transactionnelle.

Les pilotes qui ne prennent pas en charge SQL_ATTR_ENLIST_IN_DTC n’ont pas besoin de prendre en charge SQL_DTC_TRANSITION_COST. Pour les pilotes qui prennent en charge SQL_ATTR_ENLIST_IN_DTC mais pas SQL_DTC_TRANSITION_COST, il est supposé que les transitions ne sont pas coûteuses, comme si le pilote a retourné 0 (aucun bits défini) pour cette valeur.

Bien que SQL_DTC_TRANSITION_COST ait été introduit dans ODBC 3.5, un ODBC 2. Le pilote x peut également le prendre en charge, car le gestionnaire de pilotes interroge ces informations, quelle que soit la version du pilote.

Exemple de code

Dans l’exemple suivant, une application alloue des handles d’environnement et de connexion. Il se connecte ensuite à la source de données SalesOrders avec l’ID utilisateur JohnS et le mot de passe Sesame et traite les données. Une fois le traitement des données terminé, il se déconnecte de la source de données et libère les 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);  
   }  
}  

Fonctions connexes

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC