Exemple de navigation SQL Server

L’exemple suivant montre comment SQLBrowseConnect peut être utilisé pour parcourir les connexions disponibles avec un pilote pour SQL Server. Tout d’abord, l’application demande un handle de connexion :

SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  

Ensuite, l’application appelle SQLBrowseConnect et spécifie le pilote SQL Server, à l’aide de la description du pilote retournée par SQLDrivers :

SQLBrowseConnect(hdbc, "DRIVER={SQL Server};", SQL_NTS, BrowseResult,  
                  sizeof(BrowseResult), &BrowseResultLen);  

Étant donné qu’il s’agit du premier appel à SQLBrowseConnect, le Gestionnaire de pilotes charge le pilote SQL Server et appelle la fonction SQLBrowseConnect du pilote avec les mêmes arguments qu’il a reçus de l’application.

Note

Si vous vous connectez à un fournisseur de source de données qui prend en charge l’authentification Windows, vous devez spécifier Trusted_Connection=yes au lieu des informations d’ID d’utilisateur et de mot de passe dans la chaîne de connexion.

Le pilote détermine qu’il s’agit du premier appel à SQLBrowseConnect et retourne le deuxième niveau d’attributs de connexion : serveur, nom d’utilisateur, mot de passe, nom d’application et ID de station de travail. Pour l’attribut de serveur, il retourne une liste de noms de serveur valides. Le code de retour de SQLBrowseConnect est SQL_NEED_DATA. Voici la chaîne de résultat de navigation :

"SERVER:Server={red,blue,green,yellow};UID:Login ID=?;PWD:Password=?;  
   *APP:AppName=?;*WSID:WorkStation ID=?;"  

Chaque mot clé de la chaîne de résultat de navigation est suivi d’un signe deux-points et d’un ou plusieurs mots avant le signe égal. Ces mots sont le nom convivial qu’une application peut utiliser pour générer une boîte de dialogue. Les mots clés APP et WSID sont précédés d’un astérisque, ce qui signifie qu’ils sont facultatifs. Les mots clés SERVER, UID et PWD ne sont pas précédés d’un astérisque ; les valeurs doivent être fournies pour elles dans la chaîne de requête de navigation suivante. La valeur du mot clé SERVER peut être l’un des serveurs retournés par SQLBrowseConnect ou un nom fourni par l’utilisateur.

L’application appelle à nouveau SQLBrowseConnect , en spécifiant le serveur vert et en omettant les mots clés APP et WSID et les noms conviviaux après chaque mot clé :

SQLBrowseConnect(hdbc, "SERVER=green;UID=Smith;PWD=Sesame;", SQL_NTS,  
                  BrowseResult, sizeof(BrowseResult), &BrowseResultLen);  

Le pilote tente de se connecter au serveur vert. S’il existe des erreurs non irrécupérables, telles qu’une paire mot clé-valeur manquante, SQLBrowseConnect retourne SQL_NEED_DATA et reste dans le même état qu’avant l’erreur. L’application peut appeler SQLGetDiagField ou SQLGetDiagRec pour déterminer l’erreur. Si la connexion réussit, le pilote retourne SQL_NEED_DATA et retourne la chaîne de résultat de navigation :

"*DATABASE:Database={master,model,pubs,tempdb};  
   *LANGUAGE:Language={us_english,Franais};"  

Étant donné que les attributs de cette chaîne sont facultatifs, l’application peut les omettre. Toutefois, l’application doit appeler à nouveau SQLBrowseConnect . Si l’application choisit d’omettre le nom et la langue de la base de données, elle spécifie une chaîne de demande de navigation vide. Dans cet exemple, l’application choisit la base de données pubs et appelle SQLBrowseConnect une dernière fois, omettant le mot clé LANGUAGE et l’astérisque avant le mot clé DATABASE :

SQLBrowseConnect(hdbc, "DATABASE=pubs;", SQL_NTS, BrowseResult,  
                  sizeof(BrowseResult), &BrowseResultLen);  

Étant donné que l’attribut DATABASE est l’attribut de connexion final requis par le pilote, le processus de navigation est terminé, l’application est connectée à la source de données et SQLBrowseConnect retourne SQL_SUCCESS. SQLBrowseConnect retourne également la chaîne de connexion complète comme chaîne de résultat de navigation :

"DSN=MySQLServer;SERVER=green;UID=Smith;PWD=Sesame;DATABASE=pubs;"  

La chaîne de connexion finale renvoyée par le pilote ne contient pas les noms conviviaux après chaque mot-clé, ni les mots-clés facultatifs non spécifiés par l'application. L’application peut utiliser cette chaîne avec SQLDriverConnect pour se reconnecter à la source de données sur le handle de connexion actuel (après déconnexion) ou pour se connecter à la source de données sur un autre handle de connexion. Par exemple:

SQLDriverConnect(hdbc, hwnd, BrowseResult, SQL_NTS, ConnStrOut,  
                  sizeof(ConnStrOut), &ConnStrOutLen, SQL_DRIVER_NOPROMPT);