Connexion à une source de données (ODBC)

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 cela, générez une liste de sources de données à l'aide de la fonction SQLDataSources, demandez à l'utilisateur de préciser une source de données, un ID d'utilisateur et un mot de passe, puis appelez la fonction SQLConnect.

SQLConnect part du principe 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. À l'inverse des fonctions SQLDriverConnect et SQLBrowseConnect, SQLConnect n'utilise pas de chaîne de connexion.

SQLDriverConnect

La fonction SQLDriverConnect est utilisée lorsque d'autres informations que le nom de source de données, l'ID d'utilisateur et le mot de passe sont requises. L'un des paramètres de SQLDriverConnect est une chaîne de connexion qui contient des informations spécifiques au pilote. Vous pouvez utiliser SQLDriverConnect au lieu de la fonction 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 de valeurs de mots clés 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. La fonction SQLDriverConnect peut être utilisée pour se connecter sans une source de données. Par exemple, une application conçue pour établir une connexion sans DSN à une 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.

Lorsque vous utilisez la fonction SQLDriverConnect, deux options permettent de demander les informations de connexion nécessaires à l'utilisateur :

• 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 la fonction SQLDriverConnect avec un handle de fenêtre NULL et la valeur DriverCompletion définie 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 afin de passer un handle de fenêtre valide à la fonction 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

Tout comme la fonction SQLDriverConnect, SQLBrowseConnect utilise une chaîne de connexion. Cependant, avec SQLBrowseConnect, une application peut concevoir de manière itérative une chaîne de connexion complète 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 établit avec succès une connexion, il retourne une chaîne de connexion qui peut être utilisée lors des appels suivants à la fonction SQLDriverConnect.

Le pilote ODBC SQL Server Native Client retourne toujours SQL_SUCCESS_WITH_INFO sur une fonction SQLConnect, SQLDriverConnectou SQLBrowseConnect réussie. Lorsqu'une application ODBC appelle SQLGetDiagRec après avoir obtenu SQL_SUCCESS_WITH_INFO, il peut recevoir les messages suivants :

• 5701
  Indique que SQL Server a placé 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 employé dans la connexion si la source de données ne disposait pas d'une 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 qui exécute 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 un SQL_SUCCESS_WITH_INFO est la suivante :

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 les connexions SQL Server doit appeler SQLGetDiagRec jusqu'à ce que la valeur SQL_NO_DATA soit retournée. Elle doit ensuite intervenir sur tous les messages autres que ceux dotés d'un code pfNative 5701 ou 5703.

Vérification de l'état de connexion

Le comportement de SQL_ATTR_CONNECTION_DEAD et SQL_COPT_SS_CONNECTION_DEAD dans SQL Server 2000 (et versions ultérieures) diffère du comportement observé dans les versions antérieures. Dans SQL Server 2000 et versions ultérieures, SQL_ATTR_CONNECTION_DEAD retourne l'état le plus récent de la connexion qui peut ne pas correspondre à l'état actuel de la connexion. Toutefois, SQL_COPT_SS_CONNECTION_DEAD interroge toujours la Net-Library sur l'état actuel de la connexion.

Pour différencier ces comportements, SQL_COPT_SS_CONNECTION_DEAD se voit attribuer une nouvelle valeur dans les fichiers Include de SQL Server 2000 et versions ultérieures. Les applications qui utilisent cet attribut et sont conçues au moyen d'en-têtes SQL Server 2000 (et versions ultérieures) retourneront une erreur (erreur HY092, Identificateur d'option/attribut non valide) si les applications sont exécutées à l'aide d'un pilote SQL Server 7.0. Il est recommandé que l'application vérifie la version du pilote utilisé avant d'appeler SQLGetConnectAttr, puis utilise SQL_ATTR_CONNECTION_DEAD au lieu de SQL_COPT_SS_CONNECTION_DEAD si l'application s'exécute sur un pilote SQL Server 7.0.

Voir aussi

Concepts