Exemple de navigation SQL Server

L’exemple suivant montre comment SQLBrowse Connecter 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 SQLBrowse Connecter 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 à SQLBrowse Connecter, le Gestionnaire de pilotes charge le pilote SQL Server et appelle la fonction SQLBrowse Connecter du pilote avec les mêmes arguments qu’il a reçus de l’application.

Le pilote détermine qu’il s’agit du premier appel à SQLBrowse Connecter 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 SQLBrowse Connecter 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é dans la chaîne de résultats de navigation est suivie 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 mot clé APP et WSID sont précédés d’un astérisque, ce qui signifie qu’ils sont facultatifs. Les mot clé SERVER, UID et PWD ne sont pas précédées d’un astérisque ; les valeurs doivent être fournies pour elles dans la chaîne de requête de navigation suivante. La valeur de l’mot clé SERVER peut être l’un des serveurs retournés par SQLBrowse Connecter ou un nom fourni par l’utilisateur.

L’application appelle à nouveau SQLBrowse Connecter en spécifiant le serveur vert et en omettant les mot clé 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, SQLBrowse Connecter 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 SQLBrowse Connecter. 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 SQLBrowse Connecter une dernière fois, omettant le mot clé LANGUAGE et l’astérisque avant la base de données mot clé :

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 SQLBrowse Connecter retourne SQL_SUCCESS. SQLBrowse Connecter retourne également la chaîne de connexion complète en tant que chaîne de résultat de navigation :

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

La dernière chaîne de connexion retournée par le pilote ne contient pas les noms conviviaux après chaque mot clé, ni ne contient-elle des mot clé facultatives non spécifiées par l’application. L’application peut utiliser cette chaîne avec SQLDriver Connecter pour vous reconnecter à la source de données sur le handle de connexion actuel (après la déconnexion) ou pour vous 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);