Fonction SQLBrowseConnect

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

Résumé
SQLBrowseConnect prend en charge une méthode itérative de découverte et d’énumération des attributs et des valeurs d’attribut nécessaires pour se connecter à une source de données. Chaque appel à SQLBrowseConnect retourne des niveaux successifs d’attributs et de valeurs d’attribut. Lorsque tous les niveaux ont été énumérés, une connexion à la source de données est terminée et un chaîne de connexion complet est retourné par SQLBrowseConnect. Un code de retour de SQL_SUCCESS ou de SQL_SUCCESS_WITH_INFO indique que toutes les informations de connexion ont été spécifiées et que l’application est maintenant connectée à la source de données.

Syntaxe

  
SQLRETURN SQLBrowseConnect(  
     SQLHDBC         ConnectionHandle,  
     SQLCHAR *       InConnectionString,  
     SQLSMALLINT     StringLength1,  
     SQLCHAR *       OutConnectionString,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLength2Ptr);  

Arguments

ConnectionHandle
[Entrée] Handle de connexion.

InConnectionString
[Entrée] Parcourir les chaîne de connexion de requête (voir « Argument InConnectionString » dans « Commentaires »).

StringLength1
[Entrée] Longueur de *InConnectionString en caractères.

OutConnectionString
[Sortie] Pointeur vers une mémoire tampon de caractères dans laquelle retourner le résultat de navigation chaîne de connexion (voir « OutConnectionString Argument » dans « Comments »).

Si OutConnectionString a la valeur NULL, StringLength2Ptr retourne toujours le nombre total de caractères (à l’exclusion du caractère de terminaison Null pour les données de caractères) disponibles pour retourner dans la mémoire tampon indiquée par OutConnectionString.

BufferLength
[Entrée] Longueur, en caractères, de la mémoire tampon *OutConnectionString .

StringLength2Ptr
[Sortie] Nombre total de caractères (à l’exception de l’arrêt Null) disponibles pour retourner dans *OutConnectionString. Si le nombre de caractères disponibles pour retourner est supérieur ou égal à BufferLength, le chaîne de connexion dans *OutConnectionString est tronqué à BufferLength moins la longueur d’un caractère d’arrêt Null.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_STILL_EXECUTING.

Diagnostics

Lorsque SQLBrowseConnect retourne SQL_ERROR, SQL_SUCCESS_WITH_INFO ou SQL_NEED_DATA, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec un HandleType de SQL_HANDLE_STMT et un handle de ConnectionHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLBrowseConnect 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.

InConnectionString, argument

Une requête de navigation chaîne de connexion a la syntaxe suivante :

connection-string ::= attribute[;] | chaîne de connexion d’attribut ;;
attribute ::= attribute-keyword=attribute-valueDRIVER= | [{]attribute-value[}]
attribute-keyword ::= DSNPWD | UID | | driver-defined-attribute-keyword
attribute-value ::= character-string
driver-defined-attribute-keyword ::= identifier

où la chaîne de caractères a zéro ou plusieurs caractères ; l’identificateur comporte un ou plusieurs caractères ; attribute-keyword n’est pas sensible à la casse ; l’attribut-value peut être sensible à la casse ; et la valeur du mot clé DSN ne se compose pas uniquement de vides. En raison de chaîne de connexion et de la grammaire du fichier d’initialisation, de mots clés et de valeurs d’attribut qui contiennent les caractères []{}() ;? *= !@ doit être évité. En raison de la grammaire dans les informations système, les mots clés et les noms de source de données ne peuvent pas contenir la barre oblique inverse (\). Pour un ODBC 2.x driver, accolades sont requises autour de la valeur d’attribut pour le mot clé DRIVER.

Si des mots clés sont répétés dans la requête de navigation chaîne de connexion, le pilote utilise la valeur associée à la première occurrence du mot clé. Si les mots clés DSN et DRIVER sont inclus dans la même requête de navigation chaîne de connexion, le Gestionnaire de pilotes et le pilote utilisent le mot clé qui apparaît en premier.

Pour plus d’informations sur la façon dont une application choisit une source de données ou un pilote, consultez Choisir une source de données ou un pilote.

OutConnectionString, argument

Le résultat de navigation chaîne de connexion est une liste d’attributs de connexion. Un attribut de connexion se compose d’un mot clé d’attribut et d’une valeur d’attribut correspondante. Le résultat de navigation chaîne de connexion a la syntaxe suivante :

connection-string ::= attribute[;] | chaîne de connexion d’attribut ;
attribute ::= [*]attribute-keyword=attribute-value
attribute-keyword ::= ODBC-attribute-keyword | driver-defined-attribute-keyword
ODBC-attribute-keyword = {UID | PWD}[:localized-identifier] driver-defined-attribute-keyword ::= identifier[:localized-identifier] attribute-value  ::= { attribute-value-list } | ? (les accolades sont littérales ; elles sont retournées par le pilote.)
attribute-value-list ::= character-string [:chaîne de caractères localisé] | character-string [:chaîne de caractères localisée] , attribute-value-list

où la chaîne de caractères et la chaîne de caractères localisées ont zéro ou plusieurs caractères ; l’identificateur et l’identificateur localisé ont un ou plusieurs caractères ; attribute-keyword n’est pas sensible à la casse ; et attribute-value peut être sensible à la casse. En raison de chaîne de connexion et de la grammaire du fichier d’initialisation, de mots clés, d’identificateurs localisés et de valeurs d’attribut qui contiennent les caractères []{}() ;? *= !@ doit être évité. En raison de la grammaire dans les informations système, les mots clés et les noms de source de données ne peuvent pas contenir la barre oblique inverse (\).

Le résultat de navigation chaîne de connexion syntaxe est utilisé en fonction des règles sémantiques suivantes :

• Si un astérisque (*) précède un attribut-mot clé, l’attribut est facultatif et peut être omis dans l’appel suivant à SQLBrowseConnect.

• Les mots clés d’attribut UID et PWD ont la même signification que ceux définis dans SQLDriverConnect.

• Un mot clé-attribute-defined-driver nomme le type d’attribut pour lequel une valeur d’attribut peut être fournie. Par exemple, il peut s’agir de SERVER, DATABASE, HOST ou SGBD.

• Les mots clés ODBC-attribute-keywords et driver-defined-attribute-keywords incluent une version localisée ou conviviale du mot clé. Cela peut être utilisé par les applications comme étiquette dans une boîte de dialogue. Toutefois, UID, PWD ou l’identificateur seul doit être utilisé lors de la transmission d’une chaîne de demande de navigation au pilote.

• {attribute-value-list} est une énumération des valeurs réelles valides pour le mot clé-attribut correspondant. Notez que les accolades ({}) n’indiquent pas de liste de choix ; elles sont retournées par le pilote. Par exemple, il peut s’agir d’une liste de noms de serveurs ou d’une liste de noms de base de données.

• Si la valeur de l’attribut est un point d’interrogation unique ( ?), une seule valeur correspond au mot clé d’attribut. Par exemple, UID=JohnS ; PWD=Sésame.

• Chaque appel à SQLBrowseConnect retourne uniquement les informations requises pour satisfaire le niveau suivant du processus de connexion. Le pilote associe les informations d’état au handle de connexion afin que le contexte puisse toujours être déterminé sur chaque appel.

Utilisation de SQLBrowseConnect

SQLBrowseConnect nécessite une connexion allouée. Le Gestionnaire de pilotes charge le pilote qui a été spécifié ou qui correspond au nom de la source de données spécifié dans la requête de navigation initiale chaîne de connexion ; pour plus d’informations sur le moment où cela se produit, consultez la section « Commentaires » dans la fonction SQLConnect. Le pilote peut établir une connexion avec la source de données pendant le processus de navigation. Si SQLBrowseConnect retourne SQL_ERROR, les connexions en attente sont arrêtées et la connexion est retournée à un état non connecté.

Lorsque SQLBrowseConnect est appelé pour la première fois sur une connexion, la requête de navigation chaîne de connexion doit contenir le mot clé DSN ou le mot clé DRIVER. Si la requête de navigation chaîne de connexion contient le mot clé DSN, le Gestionnaire de pilotes localise une spécification de source de données correspondante dans les informations système :

• Si le Gestionnaire de pilotes trouve la spécification de source de données correspondante, il charge la DLL de pilote associée ; le pilote peut récupérer des informations sur la source de données à partir des informations système.

• Si le Gestionnaire de pilotes ne trouve pas la spécification de source de données correspondante, il localise la spécification de la source de données par défaut et charge la DLL de pilote associée ; le pilote peut récupérer des informations sur la source de données par défaut à partir des informations système. « DEFAULT » est transmis au pilote pour le DSN.

• Si le Gestionnaire de pilotes ne trouve pas la spécification de source de données correspondante et qu’il n’existe aucune spécification de source de données par défaut, elle retourne SQL_ERROR avec SQLSTATE IM002 (source de données introuvable et aucun pilote par défaut spécifié).

Si la requête de navigation chaîne de connexion contient le mot clé DRIVER, le Gestionnaire de pilotes charge le pilote spécifié ; il ne tente pas de localiser une source de données dans les informations système. Étant donné que le mot clé DRIVER n’utilise pas d’informations à partir des informations système, le pilote doit définir suffisamment de mots clés afin qu’un pilote puisse se connecter à une source de données à l’aide uniquement des informations contenues dans la requête de navigation chaîne de connexion s.

Sur chaque appel à SQLBrowseConnect, l’application spécifie les valeurs d’attribut de connexion dans la requête de navigation chaîne de connexion. Le pilote retourne des niveaux successifs d’attributs et de valeurs d’attribut dans le résultat de navigation chaîne de connexion ; il retourne SQL_NEED_DATA tant qu’il existe des attributs de connexion qui n’ont pas encore été énumérés dans la requête de navigation chaîne de connexion. L’application utilise le contenu du résultat de navigation chaîne de connexion pour générer la requête de navigation chaîne de connexion pour l’appel suivant à SQLBrowseConnect. Tous les attributs obligatoires (ceux qui ne sont pas précédés d’un astérisque dans l’argument OutConnectionString ) doivent être inclus dans l’appel suivant à SQLBrowseConnect. Notez que l’application ne peut pas utiliser le contenu du résultat de navigation précédent chaîne de connexion s lors de la génération de la requête de navigation actuelle chaîne de connexion ; autrement dit, elle ne peut pas spécifier différentes valeurs pour les attributs définis dans les niveaux précédents.

Lorsque tous les niveaux de connexion et leurs attributs associés ont été énumérés, le pilote retourne SQL_SUCCESS, la connexion à la source de données est terminée et une chaîne de connexion complète est retournée à l’application. Le chaîne de connexion convient à utiliser, conjointement avec SQLDriverConnect, avec l’option SQL_DRIVER_NOPROMPT pour établir une autre connexion. La chaîne de connexion complète ne peut pas être utilisée dans un autre appel à SQLBrowseConnect. Toutefois, si SQLBrowseConnect a été appelé à nouveau, la séquence entière d’appels doit être répétée.

SQLBrowseConnect retourne également SQL_NEED_DATA s’il existe des erreurs récupérables et non irrécupérables pendant le processus de navigation ; par exemple, un mot clé de mot de passe ou d’attribut non valide fourni par l’application. Lorsque SQL_NEED_DATA est retourné et que le résultat de navigation chaîne de connexion n’est pas modifié, une erreur s’est produite et l’application peut appeler SQLGetDiagRec pour retourner SQLSTATE pour les erreurs de navigation. Cela permet à l’application de corriger l’attribut et de poursuivre la navigation.

Une application peut arrêter le processus de navigation à tout moment en appelant SQLDisconnect. Le pilote termine toutes les connexions en attente et retourne la connexion à un état non connecté.

Si des opérations asynchrones sont activées sur le handle de connexion, SQLBrowseConnect peut également retourner SQL_STILL_EXECUTING. Lorsqu’elle retourne SQL_NEED_DATA, une application doit utiliser SQLDisconnect pour annuler le processus de navigation. Si SQLBrowseConnect retourne SQL_STILL_EXECUTING, une application doit utiliser SQLCancelHandle pour annuler l’opération en cours. Appeler SQLCancelHandle après que la fonction retourne SQL_NEED_DATA n’a aucun effet.

Pour plus d’informations, consultez Connexion avec SQLBrowseConnect.

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

Exemple de code

Dans l’exemple suivant, une application appelle SQLBrowseConnect à plusieurs reprises. Chaque fois que SQLBrowseConnect retourne SQL_NEED_DATA, il transmet des informations sur les données dont il a besoin dans *OutConnectionString. L’application transmet OutConnectionString à sa routine GetUserInput (non affichée). GetUserInput analyse les informations, génère et affiche une boîte de dialogue, puis retourne les informations entrées par l’utilisateur dans *InConnectionString. L’application transmet les informations de l’utilisateur au pilote dans l’appel suivant à SQLBrowseConnect. Une fois que l’application a fourni toutes les informations nécessaires pour que le pilote se connecte à la source de données, SQLBrowseConnect retourne SQL_SUCCESS et l’application continue.

Pour obtenir un exemple plus détaillé de connexion à un pilote SQL Server en appelant SQLBrowseConnect, consultez l’exemple de navigation SQL Server.

Par exemple, pour vous connecter à la source de données Sales, les actions suivantes peuvent se produire. Tout d’abord, l’application transmet la chaîne suivante à SQLBrowseConnect :

"DSN=Sales"  

Le Gestionnaire de pilotes charge le pilote associé à la source de données Sales. Il appelle ensuite la fonction SQLBrowseConnect du pilote avec les mêmes arguments qu’elle a reçus de l’application. Le pilote retourne la chaîne suivante dans *OutConnectionString :

"HOST:Server={red,blue,green};UID:ID=?;PWD:Password=?"  

L’application transmet cette chaîne à sa routine GetUserInput , qui génère une boîte de dialogue qui demande à l’utilisateur de sélectionner le serveur rouge, bleu ou vert et d’entrer un ID d’utilisateur et un mot de passe. La routine transmet les informations spécifiées par l’utilisateur suivantes dans *InConnectionString, que l’application transmet à SQLBrowseConnect :

"HOST=red;UID=Smith;PWD=Sesame"  

SQLBrowseConnect utilise ces informations pour se connecter au serveur rouge en tant que Smith avec le mot de passe Sésame, puis retourne la chaîne suivante dans *OutConnectionString :

"*DATABASE:Database={SalesEmployees,SalesGoals,SalesOrders}"  

L’application transmet cette chaîne à sa routine GetUserInput , qui génère une boîte de dialogue qui demande à l’utilisateur de sélectionner une base de données. L’utilisateur sélectionne empdata et l’application appelle SQLBrowseConnect une dernière fois avec cette chaîne :

"DATABASE=SalesOrders"  

Il s’agit de la dernière information dont le pilote a besoin pour se connecter à la source de données ; SQLBrowseConnect retourne SQL_SUCCESS et *OutConnectionString contient le chaîne de connexion terminé :

// SQLBrowseConnect_Function.cpp  
// compile with: odbc32.lib  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
#define BRWS_LEN 100  
SQLHENV henv;  
SQLHDBC hdbc;  
SQLHSTMT hstmt;  
SQLRETURN retcode;  
SQLCHAR szConnStrIn[BRWS_LEN], szConnStrOut[BRWS_LEN];  
SQLSMALLINT cbConnStrOut;  
  
void GetUserInput(SQLCHAR * szConnStrOut, SQLCHAR * szConnStrIn) {}  
  
int main() {  
   // Allocate the environment handle.  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);        
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
  
      // Set the version environment attribute.  
      retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
  
         // Allocate the connection handle.  
         retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
            // Call SQLBrowseConnect until it returns a value other than SQL_NEED_DATA   
            // (pass data source name the first time).  If SQL_NEED_DATA is returned, call GetUserInput   
            // (not shown) to build a dialog from the values in szConnStrOut.  The user-supplied values   
            // are returned in szConnStrIn, which is passed in the next call to SQLBrowseConnect.  
  
            strcpy_s((char*)szConnStrIn, _countof(szConnStrIn), "DSN=Sales");  
            do {  
               retcode = SQLBrowseConnect(hdbc, szConnStrIn, SQL_NTS,  
                  szConnStrOut, BRWS_LEN, &cbConnStrOut);  
               if (retcode == SQL_NEED_DATA)  
                  GetUserInput(szConnStrOut, szConnStrIn);  
            } while (retcode == SQL_NEED_DATA);  
  
            if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){  
  
               // Allocate the statement handle.  
               retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)  
                  // Process data after successful connection  
                  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