Connexion à une source de données (ODBC)
Après avoir alloué des handles d'environnement et de connexion et avoir défini tous les attributs de connexion, l'application se connecte à la source de données ou au pilote. Trois fonctions vous permettent de vous connecter :
SQLConnect
SQLDriverConnect
SQLBrowseConnect
Pour plus d’informations sur l’établissement de connexions à une source de données, y compris les différentes options de chaîne de connexion disponibles, consultez Utilisation de mots clés de chaîne de connexion avec SQL Server Native Client.
SQLConnect
SQLConnect est la fonction de connexion la plus simple. Elle accepte trois paramètres : un nom de source de données, un ID d'utilisateur et un mot de passe. Utilisez SQLConnect lorsque ces trois paramètres contiennent toutes les informations nécessaires pour se connecter à la base de données. Pour ce faire, créez une liste de sources de données à l’aide de SQLDataSources ; demander à l’utilisateur de fournir une source de données, un ID utilisateur et un mot de passe ; puis appelez SQLConnect.
SQLConnect suppose qu’un nom de source de données, un ID d’utilisateur et un mot de passe sont suffisants pour se connecter à une source de données et que la source de données ODBC contient toutes les autres informations dont le pilote ODBC a besoin pour établir la connexion. Contrairement à SQLDriverConnect et SQLBrowseConnect, SQLConnect n’utilise pas de chaîne de connexion.
SQLDriverConnect
SQLDriverConnect est utilisé lorsque davantage d’informations que le nom de la source de données, l’ID d’utilisateur et le mot de passe sont nécessaires. L’un des paramètres de SQLDriverConnect est une chaîne de connexion contenant des informations spécifiques au pilote. Vous pouvez utiliser SQLDriverConnect au lieu de SQLConnect pour les raisons suivantes :
Pour fournir des informations spécifiques au pilote lors de la connexion.
Pour demander que le pilote invite l'utilisateur à fournir des informations sur la connexion.
Pour se connecter sans le recours à une source de données ODBC.
La chaîne de connexion SQLDriverConnect contient une série de paires mot clé-valeur qui spécifient toutes les informations de connexion prises en charge par un pilote ODBC. Chaque pilote prend en charge les mots clés ODBC standard (DSN, FILEDSN, DRIVER, UID, PWD et SAVEFILE) en plus des mots clés spécifiques au pilote pour toutes les informations de connexion prises en charge par le pilote. SQLDriverConnect peut être utilisé pour se connecter sans source de données. Par exemple, une application conçue pour établir une connexion « sans DSN » à un instance de SQL Server peut appeler SQLDriverConnect avec une chaîne de connexion qui définit l’ID de connexion, le mot de passe, la bibliothèque réseau, le nom du serveur auquel se connecter et la base de données par défaut à utiliser.
Lors de l’utilisation de SQLDriverConnect, deux options permettent d’inviter l’utilisateur à fournir toutes les informations de connexion nécessaires :
Boîte de dialogue d'application
Vous pouvez créer une boîte de dialogue d’application qui demande des informations de connexion, puis appelle SQLDriverConnect avec un handle de fenêtre NULL et DriverCompletion défini sur SQL_DRIVER_NOPROMPT. Ces paramètres empêchent le pilote ODBC d'ouvrir sa propre boîte de dialogue. Cette méthode est employée lorsqu'il est vital de contrôler l'interface utilisateur de l'application.
Boîte de dialogue du pilote
Vous pouvez coder l’application pour passer un handle de fenêtre valide à SQLDriverConnect et définir le paramètre DriverCompletion sur SQL_DRIVER_COMPLETE, SQL_DRIVER_PROMPT ou SQL_DRIVER_COMPLETE_REQUIRED. Le pilote génère ensuite une boîte de dialogue pour inviter l'utilisateur à fournir les informations de connexion. Cette méthode simplifie le code de l'application.
SQLBrowseConnect
SQLBrowseConnect, comme SQLDriverConnect, utilise une chaîne de connexion. Toutefois, à l’aide de SQLBrowseConnect, une application peut construire une chaîne de connexion complète de façon itérative avec la source de données au moment de l’exécution. L'application peut alors réaliser deux tâches :
Créer ses propres boîtes de dialogue pour demander ces informations et conserver ainsi le contrôle de son interface utilisateur.
Parcourir le système à la recherche de sources de données qu'un pilote en particulier peut exploiter, et ce éventuellement en plusieurs étapes.
Par exemple, l'utilisateur peut d'abord rechercher des serveurs sur le réseau, puis après avoir choisi un serveur, recherchez sur ce dernier des bases de données auxquelles le pilote peut accéder.
Lorsque SQLBrowseConnect termine une connexion réussie, il retourne une chaîne de connexion qui peut être utilisée lors des appels suivants à SQLDriverConnect.
Le pilote ODBC SQL Server Native Client retourne toujours SQL_SUCCESS_WITH_INFO sur une connexion SQLConnect, SQLDriverConnect ou SQLBrowseConnect réussie. Lorsqu’une application ODBC appelle SQLGetDiagRec après avoir obtenu SQL_SUCCESS_WITH_INFO, elle peut recevoir les messages suivants :
5701
Indique que SQL Server placer le contexte de l’utilisateur dans la base de données par défaut définie dans la source de données, ou dans la base de données par défaut définie pour l’ID de connexion utilisé dans la connexion si la source de données n’avait pas de base de données par défaut.
5703
Indique la langue utilisée sur le serveur.
L'exemple ci-dessous affiche le message retourné par l'administrateur système lorsqu'une connexion est réussie :
szSqlState = "01000", *pfNativeError = 5701,
szErrorMsg="[Microsoft][SQL Server Native Client][SQL Server]
Changed database context to 'pubs'."
szSqlState = "01000", *pfNativeError = 5703,
szErrorMsg="[Microsoft][SQL Server Native Client][SQL Server]
Changed language setting to 'us_english'."
Vous pouvez ignorer les messages 5701 et 5703 ; ils sont fournis uniquement à titre d'information. En revanche, n'ignorez pas le code de retour SQL_SUCCESS_WITH_INFO car des messages autres que 5701 ou 5703 peuvent être retournés. Par exemple, si un pilote se connecte à un serveur exécutant une instance de SQL Server avec des procédures stockées de catalogue obsolètes, l’une des erreurs retournées via SQLGetDiagRec après une SQL_SUCCESS_WITH_INFO est :
SqlState: 01000
pfNative: 0
szErrorMsg: "[Microsoft][SQL Server Native Client]The ODBC
catalog stored procedures installed on server
my65server are version 06.50.0193; version 07.00.0205
or later is required to ensure proper operation.
Please contact your system administrator."
La fonction de gestion des erreurs d’une application pour SQL Server connexions doit appeler SQLGetDiagRec jusqu’à ce qu’elle retourne SQL_NO_DATA. Il doit ensuite agir sur tous les messages autres que ceux dont le code pfNative est 5701 ou 5703.