ConfigDSN, fonction

Conformité
Version introduite : ODBC 1.0

Résumé
ConfigDSN ajoute, modifie ou supprime des sources de données des informations système. Il peut inviter l’utilisateur à fournir des informations de connexion. Il peut se trouver dans la DLL de pilote ou dans une DLL d’installation distincte.

Syntaxe

  
BOOL ConfigDSN(  
     HWND     hwndParent,  
     WORD     fRequest,  
     LPCSTR   lpszDriver,  
     LPCSTR   lpszAttributes);  

Arguments

hwndParent
[Entrée] Poignée de fenêtre parente. La fonction n’affiche aucune boîte de dialogue si le handle est null.

fRequest
[Entrée] Type de demande. L’argument fRequest doit contenir l’une des valeurs suivantes :

ODBC_ADD_DSN : ajoutez une nouvelle source de données.

ODBC_CONFIG_DSN : configurer (modifier) une source de données existante.

ODBC_REMOVE_DSN : supprimez une source de données existante.

lpszDriver
[Entrée] Description du pilote (généralement le nom du SGBD associé) présentée aux utilisateurs au lieu du nom du pilote physique.

lpszAttributes
[Entrée] Liste d’attributs à double terminaison null sous la forme de paires mot clé-valeur. Pour plus d’informations, consultez « Commentaires ».

Retours

La fonction retourne TRUE si elle réussit, FALSE en cas d’échec.

Diagnostics

Lorsque ConfigDSN retourne FALSE, une valeur *pfErrorCode associée est publiée dans la mémoire tampon d’erreur du programme d’installation par un appel à SQLPostInstallerError et peut être obtenue en appelant SQLInstallerError. Le tableau suivant répertorie les valeurs *pfErrorCode qui peuvent être retournées par SQLInstallerError et explique chacune d’elles dans le contexte de cette fonction.

Commentaires

ConfigDSN reçoit les informations de connexion de la DLL du programme d’installation sous la forme d’une liste d’attributs sous la forme de paires mot clé-valeur. Chaque paire se termine par un octet null, et la liste entière se termine par un octet null. (Autrement dit, deux octets null marquent la fin de la liste.) Les espaces ne sont pas autorisés autour du signe égal dans la paire mot clé-valeur. ConfigDSN peut accepter des mots clés qui ne sont pas des mots clés valides pour SQLBrowseConnect et SQLDriverConnect. ConfigDSN ne prend pas nécessairement en charge tous les mots clés qui sont des mots clés valides pour SQLBrowseConnect et SQLDriverConnect. (ConfigDSN n’accepte pas le mot clé DRIVER .) Les mots clés utilisés par la fonction ConfigDSN doivent prendre en charge toutes les options requises pour recréer la source de données à l’aide de la fonctionnalité d’installation AUTOMATIQUE du programme d’installation. Lorsque les utilisations des valeurs ConfigDSN et des valeurs de chaîne de connexion sont identiques, les mêmes mots clés doivent être utilisés.

Comme dans SQLBrowseConnect et SQLDriverConnect, les mots clés et leurs valeurs ne doivent pas contenir []{}();? *=!@ caractères et la valeur du mot clé DSN ne peuvent pas se composer uniquement de vides. En raison de la grammaire du Registre, les mots clés et les noms de source de données ne peuvent pas contenir la barre oblique inverse (\).

ConfigDSN doit appeler SQLValidDSN pour vérifier la longueur du nom de la source de données et pour vérifier qu’aucun caractère non valide n’est inclus dans le nom. Si le nom de la source de données est plus long que SQL_MAX_DSN_LENGTH ou contient des caractères non valides, SQLValidDSN renvoie une erreur et ConfigDSN renvoie une erreur. La longueur du nom de la source de données est également vérifiée par SQLWriteDSNToIni.

Par exemple, pour configurer une source de données qui nécessite un ID utilisateur, un mot de passe et un nom de base de données, une application d’installation peut passer les paires mot clé-valeur suivantes :

DSN=Personnel Data\0UID=Smith\0PWD=Sesame\0DATABASE=Personnel\0\0  

Pour plus d’informations sur ces mots clés, consultez SQLDriverConnect et la documentation de chaque pilote.

Pour afficher une boîte de dialogue, hwndParent ne doit pas avoir la valeur Null.

Ajout d'une source de données

Si un nom de source de données est passé à ConfigDSN dans lpszAttributes, ConfigDSN vérifie que le nom est valide. Si le nom de la source de données correspond à un nom de source de données existant et que hwndParent a la valeur Null, ConfigDSN remplace le nom existant. S’il correspond à un nom existant et que hwndParent n’est pas null, ConfigDSN invite l’utilisateur à remplacer le nom existant.

Si lpszAttributes contient suffisamment d’informations pour se connecter à une source de données, ConfigDSN peut ajouter la source de données ou afficher une boîte de dialogue avec laquelle l’utilisateur peut modifier les informations de connexion. Si lpszAttributes ne contient pas suffisamment d’informations pour se connecter à une source de données, ConfigDSN doit déterminer les informations nécessaires ; si hwndParent n’a pas la valeur Null, il affiche une boîte de dialogue pour récupérer les informations de l’utilisateur.

Si ConfigDSN affiche une boîte de dialogue, il doit afficher toutes les informations de connexion qui lui sont transmises dans lpszAttributes. En particulier, si un nom de source de données lui a été transmis, ConfigDSN affiche ce nom, mais ne permet pas à l’utilisateur de le modifier. ConfigDSN peut fournir des valeurs par défaut pour les informations de connexion qui ne lui sont pas transmises dans lpszAttributes.

Si ConfigDSN ne peut pas obtenir des informations de connexion complètes pour une source de données, il retourne FALSE.

Si ConfigDSN peut obtenir des informations de connexion complètes pour une source de données, il appelle SQLWriteDSNToIni dans la DLL du programme d’installation pour ajouter la nouvelle spécification de source de données au fichier de Odbc.ini (ou registre). SQLWriteDSNToIni ajoute le nom de la source de données à la section [Sources de données ODBC], crée la section spécification de source de données et ajoute le mot clé DRIVER avec la description du pilote comme valeur. ConfigDSN appelle SQLWritePrivateProfileString dans la DLL du programme d’installation pour ajouter des mots clés et des valeurs supplémentaires utilisés par le pilote.

Modification d’une source de données

Pour modifier une source de données, un nom de source de données doit être passé à ConfigDSN dans lpszAttributes. ConfigDSN vérifie que le nom de la source de données se trouve dans le fichier Odbc.ini (ou registre).

Si hwndParent a la valeur Null, ConfigDSN utilise les informations de lpszAttributes pour modifier les informations du fichier Odbc.ini (ou du registre). Si hwndParent n’a pas la valeur Null, ConfigDSN affiche une boîte de dialogue utilisant les informations de lpszAttributes ; Pour les informations qui ne se trouve pas dans lpszAttributes, il utilise les informations provenant des informations système. L’utilisateur peut modifier les informations avant que ConfigDSN les stocke dans les informations système.

Si le nom de la source de données a été modifié, ConfigDSN appelle d’abord SQLRemoveDSNFromIni dans la DLL du programme d’installation pour supprimer la spécification de source de données existante du fichier Odbc.ini (ou du registre). Il suit ensuite les étapes de la section précédente pour ajouter la nouvelle spécification de source de données. Si le nom de la source de données n’a pas été modifié, ConfigDSN appelle SQLWritePrivateProfileString dans la DLL du programme d’installation pour apporter d’autres modifications. ConfigDSN ne peut pas supprimer ou modifier la valeur du mot clé Driver .

Suppression d’une source de données

Pour supprimer une source de données, un nom de source de données doit être passé à ConfigDSN dans lpszAttributes. ConfigDSN vérifie que le nom de la source de données se trouve dans le fichier Odbc.ini (ou registre). Il appelle ensuite SQLRemoveDSNFromIni dans la DLL du programme d’installation pour supprimer la source de données.

Notes

Si vous écrivez une version Unicode de cette routine, elle doit être appelée ConfigDSNW, avec des arguments LPCWSTR au lieu de LPCSTR.

Fonctions connexes