Fonction SQLDriverConnect
Conformité
Version introduite : Conformité aux normes ODBC 1.0 : ODBC
Résumé
SQLDriverConnect est une alternative à SQLConnect. Il prend en charge les sources de données qui nécessitent plus d’informations de connexion que les trois arguments dans SQLConnect, les boîtes de dialogue pour inviter l’utilisateur à entrer toutes les informations de connexion et les sources de données qui ne sont pas définies dans les informations système. Pour plus d’informations, consultez Connexion avec SQLDriverConnect.
Syntaxe
SQLRETURN SQLDriverConnect(
SQLHDBC ConnectionHandle,
SQLHWND WindowHandle,
SQLCHAR * InConnectionString,
SQLSMALLINT StringLength1,
SQLCHAR * OutConnectionString,
SQLSMALLINT BufferLength,
SQLSMALLINT * StringLength2Ptr,
SQLUSMALLINT DriverCompletion);
Arguments
ConnectionHandle
[Entrée] Handle de connexion.
WindowHandle
[Entrée] Poignée de fenêtre. L’application peut passer le handle de la fenêtre parente, le cas échéant, ou un pointeur Null si le handle de fenêtre n’est pas applicable ou SI SQLDriverConnect ne présente aucune boîte de dialogue.
InConnectionString
[Entrée] Une chaîne de connexion complète (voir la syntaxe dans « Commentaires »), une chaîne de connexion partielle ou une chaîne vide.
StringLength1
[Entrée] Longueur de *InConnectionString, en caractères si la chaîne est Unicode, ou octets si la chaîne est ANSI ou DBCS.
OutConnectionString
[Sortie] Pointeur vers une mémoire tampon pour la chaîne de connexion terminée. En cas de connexion réussie à la source de données cible, cette mémoire tampon contient la chaîne de connexion terminée. Les applications doivent allouer au moins 1 024 caractères pour cette mémoire tampon.
Si OutConnectionString a la valeur NULL, StringLength2Ptr retourne toujours le nombre total de caractères (à l’exception du caractère d’arrêt Null pour les données de caractères) pouvant être retournés dans la mémoire tampon pointée par OutConnectionString.
BufferLength
[Entrée] Longueur de la mémoire tampon *OutConnectionString , en caractères.
StringLength2Ptr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le nombre total de caractères (à l’exclusion du caractère d’arrêt Null) disponibles à retourner dans *OutConnectionString. Si le nombre de caractères disponibles à retourner est supérieur ou égal à BufferLength, la chaîne de connexion terminée dans *OutConnectionString est tronquée en BufferLength moins la longueur d’un caractère d’arrêt Null.
DriverCompletion
[Entrée] Indicateur qui indique si le gestionnaire de pilotes ou le pilote doit demander plus d’informations de connexion :
SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED ou SQL_DRIVER_NOPROMPT.
(Pour plus d’informations, consultez « Commentaires ».
Retours
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_STILL_EXECUTING.
Diagnostics
Lorsque SQLDriverConnect retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec un fHandleType de SQL_HANDLE_DBC et un hHandle de ConnectionHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLDriverConnect 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.
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | Avertissement général | Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 01004 | Données de chaîne, tronquées à droite | La mémoire tampon *OutConnectionString n’étant pas assez grande pour renvoyer la chaîne de connexion entière, la chaîne de connexion a été tronquée. La longueur de la chaîne de connexion non structurée est retournée dans *StringLength2Ptr. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 01S00 | Attribut de chaîne de connexion non valide | Un mot clé d’attribut non valide a été spécifié dans la chaîne de connexion (InConnectionString), mais le pilote a quand même pu se connecter à la source de données. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Valeur de l’option modifiée | Le pilote n’a pas pris en charge la valeur spécifiée pointée vers l’argument ValuePtr dans SQLSetConnectAttr et a remplacé une valeur similaire. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 01S08 | Erreur lors de l’enregistrement du DSN du fichier | La chaîne dans *InConnectionString contenait un mot clé FILEDSN , mais le fichier .dsn n’a pas été enregistré. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 01S09 | Mot clé non valide | (DM) La chaîne dans *InConnectionString contenait un mot clé SAVEFILE , mais pas un mot clé DRIVER ou FILEDSN . (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 08001 | Le client ne peut pas établir la connexion | Le pilote n’a pas pu établir de connexion avec la source de données. |
| 08002 | Nom de la connexion en cours d’utilisation | (DM) Le ConnectionHandle spécifié avait déjà été utilisé pour établir une connexion avec une source de données, et la connexion était toujours ouverte. |
| 08004 | Le serveur a rejeté la connexion | La source de données a rejeté l’établissement de la connexion pour des raisons définies par l’implémentation. |
| 08S01 | Échec de la liaison de communication | Le lien de communication entre le pilote et la source de données à laquelle le pilote tentait de se connecter a échoué avant la fin du traitement de la fonction SQLDriverConnect . |
| 28000 | Spécification d’autorisation non valide | L’identificateur utilisateur ou la chaîne d’autorisation, ou les deux, comme spécifié dans la chaîne de connexion (InConnectionString), a violé les restrictions définies par la source de données. |
| HY000 | Erreur générale | Une erreur s’est produite pour laquelle il n’y avait pas de SQLSTATE spécifique et pour laquelle aucun SQLSTATE spécifique à l’implémentation n’a été défini. Le message d’erreur retourné par SQLGetDiagRec dans la mémoire tampon *szMessageText décrit l’erreur et sa cause. |
| HY000 | Erreur générale : fichier dsn non valide | (DM) La chaîne dans *InConnectionString contenait un mot clé FILEDSN, mais le nom du fichier .dsn est introuvable. |
| HY000 | Erreur générale : Impossible de créer une mémoire tampon de fichier | (DM) La chaîne dans *InConnectionString contenait un mot clé FILEDSN, mais le fichier .dsn était illisible. |
| HY001 | Erreur d’allocation de mémoire | Le Gestionnaire de pilotes n’a pas pu allouer la mémoire nécessaire pour prendre en charge l’exécution ou l’achèvement de la fonction SQLDriverConnect . Le pilote n’a pas pu allouer la mémoire nécessaire pour prendre en charge l’exécution ou l’achèvement de la fonction. |
| HY008 | Opération annulée | Le traitement asynchrone a été activé pour connectionHandle. La fonction a été appelée et, avant la fin de son exécution, la fonction SQLCancelHandle a été appelée sur connectionHandle, puis la fonction SQLDriverConnect a été appelée à nouveau sur le ConnectionHandle. Ou bien, la fonction SQLDriverConnect a été appelée et, avant la fin de son exécution, SQLCancelHandle a été appelé sur connectionHandle à partir d’un thread différent dans une application multithread. |
| HY010 | Erreur de séquence de fonction | (DM) Une autre fonction en cours d’exécution asynchrone (et non SQLDriverConnect) a été appelée pour connectionHandle et s’exécutait toujours lorsque la fonction SQLDriverConnect a été appelée. |
| HY013 | Erreur de gestion de la mémoire | L’appel de fonction SQLDriverConnect n’a pas pu être traité, car les objets mémoire sous-jacents n’ont pas pu être accessibles, peut-être en raison de conditions de mémoire insuffisantes. |
| HY090 | Chaîne ou longueur de mémoire tampon non valide | (DM) La valeur spécifiée pour l’argument StringLength1 était inférieure à 0 et n’était pas égale à SQL_NTS. (DM) La valeur spécifiée pour l’argument BufferLength était inférieure à 0. |
| HY092 | Identificateur d’attribut/d’option non valide | (DM) L’argument DriverCompletion était SQL_DRIVER_PROMPT, et l’argument WindowHandle était un pointeur null. |
| HY110 | Complétion du pilote non valide | (DM) La valeur spécifiée pour l’argument DriverCompletion n’était pas égale à SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED ou SQL_DRIVER_NOPROMPT. (DM) Le regroupement de connexions a été activé et la valeur spécifiée pour l’argument DriverCompletion n’était pas égale à SQL_DRIVER_NOPROMPT. |
| HYC00 | Fonctionnalité facultative non implémentée | Le pilote ne prend pas en charge la version du comportement ODBC demandée par l’application. |
| HYT00 | Délai expiré | Le délai d’expiration de la connexion a expiré avant la fin de la connexion à la source de données. Le délai d’expiration est défini via SQLSetConnectAttr, SQL_ATTR_LOGIN_TIMEOUT. |
| HYT01 | Délai d’attente de la connexion expiré | Le délai d’expiration de la connexion a expiré avant que la source de données ne réponde à la demande. Le délai d’expiration de connexion est défini via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Le pilote ne prend pas en charge cette fonction | (DM) Le pilote correspondant au nom de source de données spécifié ne prend pas en charge la fonction. |
| IM002 | Source de données introuvable et aucun pilote par défaut spécifié | (DM) Le nom de la source de données spécifié dans la chaîne de connexion (InConnectionString) n’a pas été trouvé dans les informations système et il n’y avait aucune spécification de pilote par défaut. (DM) La source de données ODBC et les informations de pilote par défaut sont introuvables dans les informations système. |
| IM003 | Impossible de charger le pilote spécifié | (DM) Le pilote répertorié dans la spécification de la source de données dans les informations système ou spécifié par le mot clé DRIVER est introuvable ou n’a pas pu être chargé pour une autre raison. |
| IM004 | Échec du SQLAllocHandle du pilote sur SQL_HANDLE_ENV | (DM) Pendant SQLDriverConnect, le Gestionnaire de pilotes a appelé la fonction SQLAllocHandle du pilote avec un fHandleType de SQL_HANDLE_ENV et le pilote a renvoyé une erreur. |
| IM005 | Échec du SQLAllocHandle du pilote sur SQL_HANDLE_DBC. | (DM) Pendant SQLDriverConnect, le Gestionnaire de pilotes a appelé la fonction SQLAllocHandle du pilote avec un fHandleType de SQL_HANDLE_DBC et le pilote a renvoyé une erreur. |
| IM006 | Échec de SQLSetConnectAttr du pilote | (DM) Pendant SQLDriverConnect, le Gestionnaire de pilotes a appelé la fonction SQLSetConnectAttr du pilote et le pilote a retourné une erreur. |
| IM007 | Aucune source de données ou pilote spécifié ; boîte de dialogue interdite | Aucun nom ou pilote de source de données n’a été spécifié dans la chaîne de connexion, et DriverCompletion a été SQL_DRIVER_NOPROMPT. |
| IM008 | Échec de la boîte de dialogue | Le pilote a tenté d’afficher sa boîte de dialogue de connexion et a échoué. WindowHandle était un pointeur null et DriverCompletion n’était pas SQL_DRIVER_NO_PROMPT. |
| IM009 | Impossible de charger la DLL de traduction | Le pilote n’a pas pu charger la DLL de traduction spécifiée pour la source de données ou pour la connexion. |
| IM010 | Nom de la source de données trop long | (DM) La valeur d’attribut du mot clé DSN était plus longue que SQL_MAX_DSN_LENGTH caractères. |
| IM011 | Nom du pilote trop long | (DM) La valeur d’attribut du mot clé DRIVER était supérieure à 255 caractères. |
| IM012 | Erreur de syntaxe de mot clé DRIVER | (DM) La paire mot clé-valeur pour le mot clé DRIVER contenait une erreur de syntaxe. (DM) La chaîne dans *InConnectionString contenait un mot clé FILEDSN , mais le fichier .dsn ne contenait pas de mot clé DRIVER ou de mot clé DSN . |
| IM014 | Le DSN spécifié contient une incompatibilité d’architecture entre le pilote et l’application | (DM) l’application 32 bits utilise un DSN qui se connecte à un pilote 64 bits ; ou vice versa. |
| IM015 | Échec de SQLDriverConnect du pilote sur SQL_HANDLE_DBC_INFO_HANDLE | Si un pilote retourne SQL_ERROR, le Gestionnaire de pilotes retourne SQL_ERROR à l’application et la connexion échoue. Pour plus d’informations sur SQL_HANDLE_DBC_INFO_TOKEN, consultez Développement de la sensibilisation Connection-Pool dans un pilote ODBC. |
| IM017 | L’interrogation est désactivée en mode de notification asynchrone | Chaque fois que le modèle de notification est utilisé, l’interrogation est désactivée. |
| IM018 | SQLCompleteAsync n’a pas été appelé pour effectuer l’opération asynchrone précédente sur ce handle. | Si l’appel de fonction précédent sur le handle retourne SQL_STILL_EXECUTING et si le mode de notification est activé, SQLCompleteAsync doit être appelé sur le handle pour effectuer le post-traitement et terminer l’opération. |
| S1118 | Le pilote ne prend pas en charge la notification asynchrone | Lorsque le pilote ne prend pas en charge la notification asynchrone, vous ne pouvez pas définir SQL_ATTR_ASYNC_DBC_EVENT ou SQL_ATTR_ASYNC_DBC_RETCODE_PTR. |
Commentaires
Une chaîne de connexion a la syntaxe suivante :
connection-string ::= empty-string[;] | attribute[;] | attribut ; chaîne de connexion
empty-string ::=attribute ::= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}]
attribute-keyword ::= DSN | UID | PWD | driver-defined-attribute-keyword
attribute-value ::= character-string
driver-defined-attribute-keyword ::= identifier
où la chaîne de caractères comporte zéro ou plusieurs caractères ; l’identificateur comporte un ou plusieurs caractères ; attribute-keyword ne respecte pas la casse ; attribute-value peut respecter la casse ; et la valeur du mot clé DSN ne se compose pas uniquement de vides.
En raison de la grammaire de la chaîne de connexion et du fichier d’initialisation, des mots clés et des valeurs d’attribut qui contiennent les caractères []{}(),;? *=!@ non entouré d’accolades doit être évité. La valeur du mot clé DSN ne peut pas se composer uniquement de vides et ne doit pas contenir de blancs de début. En raison de la grammaire des informations système, les mots clés et les noms de sources de données ne peuvent pas contenir la barre oblique inverse (\).
Les applications n’ont pas besoin d’ajouter des accolades autour de la valeur d’attribut après le mot clé DRIVER , sauf si l’attribut contient un point-virgule (;), auquel cas les accolades sont requises. Si la valeur d’attribut que le pilote reçoit inclut des accolades, le pilote ne doit pas les supprimer, mais elles doivent faire partie de la chaîne de connexion retournée.
Valeur DSN ou chaîne de connexion entourée d’accolades ({}) contenant l’un des caractères []{}(),;? *=!@ est transmis intact au pilote. Toutefois, lors de l’utilisation de ces caractères dans un mot clé, le Gestionnaire de pilotes renvoie une erreur lors de l’utilisation des noms de source de données de fichier, mais transmet la chaîne de connexion au pilote pour les chaînes de connexion normales. Évitez d’utiliser des accolades incorporées dans une valeur de mot clé.
La chaîne de connexion peut inclure n’importe quel nombre de mots clés définis par le pilote. Étant donné que le mot clé DRIVER n’utilise pas d’informations provenant des informations système, le pilote doit définir suffisamment de mots clés pour qu’un pilote puisse se connecter à une source de données en utilisant uniquement les informations de la chaîne de connexion. (Pour plus d’informations, consultez « Instructions relatives aux pilotes », plus loin dans cette section.) Le pilote définit les mots clés requis pour se connecter à la source de données.
Le tableau suivant décrit les valeurs d’attribut des mots clés DSN, FILEDSN, DRIVER, UID, PWD et SAVEFILE .
| Mot clé | Description de la valeur d’attribut |
|---|---|
| DSN | Nom d’une source de données tel que retourné par SQLDataSources ou la boîte de dialogue sources de données de SQLDriverConnect. |
| FILEDSN | Nom d’un fichier .dsn à partir duquel une chaîne de connexion sera générée pour la source de données. Ces sources de données sont appelées sources de données de fichier. |
| PILOTE | Description du pilote tel que retourné par la fonction SQLDrivers . Par exemple, Rdb ou SQL Server. |
| UID | ID utilisateur. |
| PWD | Mot de passe correspondant à l’ID utilisateur, ou une chaîne vide s’il n’existe aucun mot de passe pour l’ID utilisateur (PWD=;). |
| SAVEFILE | Nom de fichier d’un fichier .dsn dans lequel les valeurs d’attribut des mots clés utilisés pour établir la connexion actuelle et réussie doivent être enregistrées. |
Pour plus d’informations sur la façon dont une application choisit une source de données ou un pilote, consultez Choix d’une source de données ou d’un pilote.
Si des mots clés sont répétés dans la 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 chaîne de connexion, le Gestionnaire de pilotes et le pilote utilisent le mot clé qui apparaît en premier.
Les mots clés FILEDSN et DSN s’excluent mutuellement : le mot clé qui apparaît en premier est utilisé et celui qui apparaît en deuxième est ignoré. En revanche, les mots clés FILEDSN et DRIVER ne s’excluent pas mutuellement. Si un mot clé apparaît dans une chaîne de connexion avec FILEDSN, la valeur d’attribut du mot clé dans la chaîne de connexion est utilisée plutôt que la valeur d’attribut du même mot clé dans le fichier .dsn.
Si le mot clé FILEDSN est utilisé, les mots clés spécifiés dans un fichier .dsn sont utilisés pour créer une chaîne de connexion. (Pour plus d’informations, consultez « Sources de données de fichier », plus loin dans cette section.) Le mot clé UID est facultatif ; un fichier .dsn peut être créé avec uniquement le mot clé DRIVER . Le mot clé PWD n’est pas stocké dans un fichier .dsn. Le répertoire par défaut pour l’enregistrement et le chargement d’un fichier .dsn est une combinaison du chemin spécifié par CommonFileDir dans HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ Windows\CurrentVersion et « ODBC\DataSources ». (Si CommonFileDir était « C:\Program Files\Common Files », le répertoire par défaut serait « C:\Program Files\Common Files\ODBC\Data Sources ».)
Notes
Un fichier .dsn peut être manipulé directement en appelant les fonctions SQLReadFileDSN et SQLWriteFileDSN dans la DLL du programme d’installation.
Si le mot clé SAVEFILE est utilisé, les valeurs d’attribut des mots clés utilisés pour établir la connexion actuelle et réussie sont enregistrées en tant que fichier .dsn avec le nom de la valeur d’attribut du mot clé SAVEFILE . Le mot clé SAVEFILE doit être utilisé conjointement avec le mot clé DRIVER , le mot clé FILEDSN ou les deux, ou la fonction retourne SQL_SUCCESS_WITH_INFO avec SQLSTATE 01S09 (mot clé non valide). Le mot clé SAVEFILE doit apparaître avant le mot clé DRIVER dans la chaîne de connexion, sinon les résultats ne sont pas définis.
Instructions du gestionnaire de pilotes
Le Gestionnaire de pilotes construit une chaîne de connexion à passer au pilote dans l’argument InConnectionString de la fonction SQLDriverConnect du pilote. Le Gestionnaire de pilotes ne modifie pas l’argument InConnectionString qui lui est transmis par l’application.
L’action du Gestionnaire de pilotes est basée sur la valeur de l’argument DriverCompletion :
SQL_DRIVER_PROMPT : si la chaîne de connexion ne contient pas le mot clé DRIVER, DSN ou FILEDSN , le Gestionnaire de pilotes affiche la boîte de dialogue Sources de données. Il construit une chaîne de connexion à partir du nom de la source de données retourné par la boîte de dialogue et de tous les autres mots clés qui lui sont transmis par l’application. Si le nom de la source de données retourné par la boîte de dialogue est vide, le Gestionnaire de pilotes spécifie la paire mot clé-valeur DSN=Default. (Cette boîte de dialogue n’affiche pas de source de données avec le nom « Default ».)
SQL_DRIVER_COMPLETE ou SQL_DRIVER_COMPLETE_REQUIRED : si la chaîne de connexion spécifiée par l’application inclut le mot clé DSN , le Gestionnaire de pilotes copie la chaîne de connexion spécifiée par l’application. Sinon, il effectue les mêmes actions que lorsque DriverCompletion est SQL_DRIVER_PROMPT.
SQL_DRIVER_NOPROMPT : le Gestionnaire de pilotes copie la chaîne de connexion spécifiée par l’application.
Si la chaîne de connexion spécifiée par l’application contient le mot clé DRIVER , le Gestionnaire de pilotes copie la chaîne de connexion spécifiée par l’application.
À l’aide de la chaîne de connexion qu’il a construite, le Gestionnaire de pilotes détermine le pilote à utiliser, se connecte à ce pilote et transmet la chaîne de connexion qu’il a construite au pilote ; Pour plus d’informations sur l’interaction entre le Gestionnaire de pilotes et le pilote, consultez la section « Commentaires » dans la fonction SQLConnect. Si la chaîne de connexion ne contient pas le mot clé DRIVER , le Gestionnaire de pilotes détermine le pilote à utiliser comme suit :
Si la chaîne de connexion contient le mot clé DSN , le Gestionnaire de pilotes récupère le pilote associé à la source de données à partir des informations système.
Si la chaîne de connexion ne contient pas le mot clé DSN ou si la source de données est introuvable, le Gestionnaire de pilotes récupère le pilote associé à la source de données par défaut à partir des informations système. (Pour plus d’informations, consultez Sous-clé par défaut.) Le Gestionnaire de pilotes remplace la valeur du mot clé DSN dans la chaîne de connexion par « DEFAULT ».
Si le mot clé DSN dans la chaîne de connexion est défini sur « DEFAULT », le Gestionnaire de pilotes récupère le pilote associé à la source de données Par défaut à partir des informations système.
Si la source de données est introuvable et que la source de données par défaut est introuvable, le Gestionnaire de pilotes retourne SQL_ERROR avec SQLSTATE IM002 (source de données introuvable et aucun pilote par défaut spécifié).
Sources de données de fichier
Si la chaîne de connexion spécifiée par l’application dans l’appel à SQLDriverConnect contient le mot clé FILEDSN et que ce mot clé n’est pas remplacé par le mot clé DSN ou DRIVER , le Gestionnaire de pilotes crée une chaîne de connexion à l’aide des informations contenues dans le fichier .dsn et l’argument InConnectionString . Le gestionnaire de pilotes se déroule comme suit :
Vérifie si le nom du fichier .dsn est valide. Si ce n’est pas le cas, elle retourne SQL_ERROR avec SQLSTATE IM014 (nom non valide du nom de source de données du fichier). Si le nom de fichier est une chaîne vide (« ») et que SQL_DRIVER_NOPROMPT n’est pas spécifié, la boîte de dialogue Ouvrir le fichier s’affiche. Si le nom de fichier contient un chemin d’accès valide, mais aucun nom de fichier ou un nom de fichier non valide, et que SQL_DRIVER_NOPROMPT n’est pas spécifié, la boîte de dialogue Ouvrir le fichier s’affiche avec le répertoire actif défini sur celui spécifié dans le nom de fichier. Si le nom de fichier est une chaîne vide (« ») ou si le nom de fichier contient un chemin d’accès valide, mais aucun nom de fichier ou un nom de fichier non valide, et SQL_DRIVER_NOPROMPT est spécifié, SQL_ERROR est retourné avec SQLSTATE IM014 (Nom non valide du nom de source de données du fichier).
Lit tous les mots clés de la section [ODBC] du fichier .dsn. Si le mot clé DRIVER n’est pas présent, il retourne SQL_ERROR avec SQLSTATE IM012 (erreur de syntaxe de mot clé driver), sauf si le fichier .dsn n’est pas partageable et contient donc uniquement le mot clé DSN .
Si la source de données du fichier n’est pas partageable, le Gestionnaire de pilotes lit la valeur du mot clé DSN et se connecte si nécessaire à la source de données utilisateur ou système pointée par la source de données de fichier non partageable. Les étapes 3 à 5 ne sont pas effectuées.
Construit une chaîne de connexion pour le pilote. La chaîne de connexion du pilote est l’union des mots clés spécifiés dans le fichier .dsn et de ceux spécifiés dans la chaîne de connexion d’application d’origine. Les règles de construction de la chaîne de connexion du pilote où les mots clés se chevauchent sont les suivantes :
Si le mot clé DRIVER existe dans la chaîne de connexion de l’application et que les pilotes spécifiés par les mots clés DRIVER ne sont pas les mêmes dans le fichier .dsn et la chaîne de connexion de l’application, les informations de pilote dans le fichier .dsn sont ignorées et les informations de pilote dans la chaîne de connexion de l’application sont utilisées. Si les pilotes spécifiés par le mot clé DRIVER sont les mêmes dans le fichier .dsn et la chaîne de connexion de l’application, là où tous les mots clés se chevauchent, ceux spécifiés dans la chaîne de connexion de l’application ont la priorité sur ceux spécifiés dans le fichier .dsn.
Dans la nouvelle chaîne de connexion, le mot clé FILEDSN est éliminé.
Charge le pilote en recherchant dans l’entrée de Registre HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\<Nom> du pilote\Pilote où <le nom du> pilote est spécifié par le mot clé DRIVER .
Transmet au pilote la nouvelle chaîne de connexions.
Pour obtenir des exemples de fichiers .dsn, consultez Connexion à l’aide de sources de données de fichier.
SAVEFILE, mot clé
Si la chaîne de connexion spécifiée par l’application contient le mot clé SAVEFILE , le Gestionnaire de pilotes enregistre la chaîne de connexion dans un fichier .dsn. Le gestionnaire de pilotes se déroule comme suit :
Vérifie si le nom de fichier du fichier .dsn inclus comme valeur d’attribut du mot clé SAVEFILE est valide. Si ce n’est pas le cas, elle retourne SQL_ERROR avec SQLSTATE IM014 (nom non valide du nom de source de données du fichier). La validité du nom de fichier est déterminée par les règles de nommage système standard. Si le nom de fichier est une chaîne vide (« ») et que l’argument DriverCompletion n’est pas SQL_DRIVER_NOPROMPT, le nom de fichier est valide. Si le nom de fichier existe déjà, si DriverCompletion est SQL_DRIVER_NOPROMPT, le fichier est remplacé. Si DriverCompletion est SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE ou SQL_DRIVER_COMPLETE_REQUIRED, une boîte de dialogue invite l’utilisateur à spécifier si le fichier doit être remplacé. Si non est entré, la boîte de dialogue Fichier-Enregistrer s’affiche.
Si le pilote retourne SQL_SUCCESS et que le nom de fichier n’était pas une chaîne vide, le Gestionnaire de pilotes écrit les informations de connexion retournées dans l’argument OutConnectionString dans le fichier spécifié avec le format spécifié dans la section « Chaînes de connexion » plus haut dans cette section.
Si le pilote retourne SQL_SUCCESS et que le nom de fichier était une chaîne vide (« »), le Gestionnaire de pilotes appelle la boîte de dialogue Fichier-Enregistrer commun avec le hwnd spécifié et écrit les informations de connexion retournées dans OutConnectionString dans le fichier spécifié dans la boîte de dialogue File-Save commune avec le format spécifié dans la section « Chaînes de connexion » plus haut dans cette section.
Si le pilote retourne SQL_SUCCESS, il retourne l’argument OutConnectionString contenant la chaîne de connexion à l’application.
Si le pilote retourne SQL_SUCCESS_WITH_INFO ou SQL_ERROR, le Gestionnaire de pilotes renvoie l’instruction SQLSTATE à l’application.
Instructions relatives aux pilotes
Le pilote vérifie si la chaîne de connexion qui lui est transmise par le Gestionnaire de pilotes contient le nom de source de données ou le mot clé DRIVER . Si la chaîne de connexion contient le mot clé DRIVER , le pilote ne peut pas récupérer d’informations sur la source de données à partir des informations système. Si la chaîne de connexion contient le mot clé DSN ou ne contient pas le nom de source de données ou le mot clé DRIVER , le pilote peut récupérer des informations sur la source de données à partir des informations système comme suit :
Si la chaîne de connexion contient le mot clé DSN , le pilote récupère les informations de la source de données spécifiée.
Si la chaîne de connexion ne contient pas le mot clé DSN , que la source de données spécifiée est introuvable ou que le mot clé DSN est défini sur « DEFAULT », le pilote récupère les informations de la source de données Par défaut.
Le pilote utilise toutes les informations qu’il récupère à partir des informations système pour augmenter les informations qui lui sont transmises dans la chaîne de connexion. Si les informations contenues dans les informations système dupliquent des informations dans la chaîne de connexion, le pilote utilise les informations de la chaîne de connexion.
En fonction de la valeur de DriverCompletion, le pilote invite l’utilisateur à entrer des informations de connexion, telles que l’ID utilisateur et le mot de passe, et se connecte à la source de données :
SQL_DRIVER_PROMPT : le pilote affiche une boîte de dialogue, en utilisant les valeurs de la chaîne de connexion et les informations système (le cas échéant) comme valeurs initiales. Lorsque l’utilisateur quitte la boîte de dialogue, le pilote se connecte à la source de données. Il construit également une chaîne de connexion à partir de la valeur du mot clé DSN ou DRIVER dans *InConnectionString et des informations retournées par la boîte de dialogue. Il place cette chaîne de connexion dans la mémoire tampon *OutConnectionString .
SQL_DRIVER_COMPLETE ou SQL_DRIVER_COMPLETE_REQUIRED : si la chaîne de connexion contient suffisamment d’informations et que ces informations sont correctes, le pilote se connecte à la source de données et copie *InConnectionString dans *OutConnectionString. Si des informations sont manquantes ou incorrectes, le pilote effectue les mêmes actions que lorsque DriverCompletion est SQL_DRIVER_PROMPT, sauf que si DriverCompletion est SQL_DRIVER_COMPLETE_REQUIRED, le pilote désactive les contrôles pour toutes les informations qui ne sont pas nécessaires pour se connecter à la source de données.
SQL_DRIVER_NOPROMPT : si la chaîne de connexion contient suffisamment d’informations, le pilote se connecte à la source de données et copie *InConnectionString dans *OutConnectionString. Sinon, le pilote retourne SQL_ERROR pour SQLDriverConnect.
En cas de connexion réussie à la source de données, le pilote définit également *StringLength2Ptr sur la longueur de la chaîne de connexion de sortie qui est disponible pour retourner dans *OutConnectionString.
Si l’utilisateur annule une boîte de dialogue présentée par le Gestionnaire de pilotes ou le pilote, SQLDriverConnect retourne SQL_NO_DATA.
Pour plus d’informations sur la façon dont le Gestionnaire de pilotes et le pilote interagissent pendant le processus de connexion, consultez FONCTION SQLConnect.
Si un pilote prend en charge SQLDriverConnect, la section mot clé du pilote des informations système pour le pilote doit contenir le mot clé ConnectFunctions avec le deuxième caractère défini sur « Y ».
Connexion lorsque le regroupement de connexions est activé
Le regroupement de connexions permet à une application de réutiliser une connexion qui a déjà été créée. Lorsque SQLDriverConnect est appelé, le Gestionnaire de pilotes tente d’établir la connexion à l’aide d’une connexion qui fait partie d’un pool de connexions dans un environnement qui a été désigné pour le regroupement de connexions. Pour plus d’informations sur le regroupement de connexions, consultez FONCTION SQLConnect.
Une application peut définir SQL_ATTR_RESET_CONNECTION avant d’appeler SQLDisconnect sur une connexion où le regroupement est activé. Pour plus d’informations, consultez FONCTION SQLSetConnectAttr.
Les restrictions suivantes s’appliquent lorsqu’une application appelle SQLDriverConnect pour se connecter à une connexion mise en pool :
Aucun traitement de regroupement de connexions n’est effectué lorsque le mot clé SAVEFILE est spécifié dans la chaîne de connexion.
Si le regroupement de connexions est activé, SQLDriverConnect peut être appelé uniquement avec un argument DriverCompletion de SQL_DRIVER_NOPROMPT ; si SQLDriverConnect est appelé avec un autre DriverCompletion, SQLSTATE HY110 (Achèvement du pilote non valide) est retourné.
Attributs de connexion
L’attribut de connexion SQL_ATTR_LOGIN_TIMEOUT, défini à l’aide de SQLSetConnectAttr, définit le nombre de secondes à attendre qu’une demande de connexion se termine avec une connexion réussie par le pilote avant de revenir à l’application. Si l’utilisateur est invité à terminer la chaîne de connexion, une période d’attente pour chaque demande de connexion commence lorsque le pilote démarre le processus de connexion.
Le pilote ouvre la connexion en mode d’accès SQL_MODE_READ_WRITE par défaut. Pour définir le mode d’accès sur SQL_MODE_READ_ONLY, l’application doit appeler SQLSetConnectAttr avec l’attribut SQL_ATTR_ACCESS_MODE avant d’appeler SQLDriverConnect.
Si une bibliothèque de traduction par défaut est spécifiée dans les informations système de la source de données, le pilote la charge. Une autre bibliothèque de traduction peut être chargée en appelant SQLSetConnectAttr avec l’attribut SQL_ATTR_TRANSLATE_LIB. Vous pouvez spécifier une option de traduction en appelant SQLSetConnectAttr avec l’option SQL_ATTR_TRANSLATE_OPTION.
Pour plus d’informations, consultez Connexion avec SQLDriverConnect.
// SQLDriverConnect_ref.cpp
// compile with: odbc32.lib user32.lib
#include <windows.h>
#include <sqlext.h>
int main() {
SQLHENV henv;
SQLHDBC hdbc;
SQLHSTMT hstmt;
SQLRETURN retcode;
SQLCHAR OutConnStr[255];
SQLSMALLINT OutConnStrLen;
HWND desktopHandle = GetDesktopWindow(); // desktop's window handle
// Allocate environment handle
retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
// Set the ODBC version environment attribute
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);
// Allocate connection handle
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
// Set login timeout to 5 seconds
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);
retcode = SQLDriverConnect( // SQL_NULL_HDBC
hdbc,
desktopHandle,
(SQLCHAR*)"driver=SQL Server",
_countof("driver=SQL Server"),
OutConnStr,
255,
&OutConnStrLen,
SQL_DRIVER_PROMPT );
// Allocate statement handle
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
// Process data
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
}
SQLDisconnect(hdbc);
}
SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
}
}
SQLFreeHandle(SQL_HANDLE_ENV, henv);
}
}
Consultez également Exemple de programme ODBC.
Fonctions connexes
| Pour obtenir des informations sur | Consultez |
|---|---|
| Allocation d’un handle | SQLAllocHandle, fonction |
| Découverte et énumération des valeurs requises pour se connecter à une source de données | Fonction SQLBrowseConnect |
| Connexion à une source de données | SQLConnect, fonction |
| Déconnexion d’une source de données | SQLDisconnect, fonction |
| Retour des descriptions et des attributs des pilotes | SQLDrivers, fonction |
| Libération d’un handle | Fonction SQLFreeHandle |
| Définition d’un attribut de connexion | Fonction SQLSetConnectAttr |
Voir aussi
Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour