SQLCreateDataSource, fonction

Conformité
Version introduite : ODBC 2.0

Résumé
SQLCreateDataSource affiche une boîte de dialogue avec laquelle l’utilisateur peut ajouter une source de données.

Syntaxe

  
BOOL SQLCreateDataSource(  
     HWND    hwnd,  
     LPSTR   lpszDS);  

Arguments

Hwnd
[Entrée] Poignée de fenêtre parente.

lpszDS
[Entrée] Nom de la source de données. lpszDS peut être un pointeur null ou une chaîne vide.

Retours

SQLCreateDataSource retourne TRUE si la source de données est créée. Sinon, elle retourne FALSE.

Diagnostics

Lorsque SQLCreateDataSource retourne FALSE, une valeur *pfErrorCode associée 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.

*pfErrorCode	Error	Description
ODBC_ERROR_GENERAL_ERR	Erreur générale du programme d’installation	Une erreur s’est produite pour laquelle il n’y avait pas d’erreur de programme d’installation spécifique.
ODBC_ERROR_INVALID_HWND	Handle de fenêtre non valide	L’argument hwnd n’était pas valide ou null.
ODBC_ERROR_INVALID_DSN	DSN non valide	L’argument lpszDS contenait une chaîne non valide pour un DSN.
ODBC_ERROR_REQUEST_FAILED	Échec de la demande	L’appel à ConfigDSN avec l’option ODBC_ADD_DSN a échoué.
ODBC_ERROR_LOAD_LIBRARY_FAILED	Impossible de charger le pilote ou la bibliothèque de configuration du traducteur	Impossible de charger la bibliothèque d’installation du pilote.
ODBC_ERROR_USER_CANCELED	Opération annulée par l’utilisateur	L’utilisateur a annulé la création d’une source de données.
ODBC_ERROR_CREATE_DSN_FAILED	Impossible de créer le DSN demandé	Impossible de se connecter à la base de données ; l’appel à SQLDriverConnect pour un DSN de fichier n’a pas retourné une connexion réussie. Impossible d’écrire dans le fichier.
ODBC_ERROR_OUT_OF_MEM	Mémoire insuffisante	Le programme d’installation n’a pas pu effectuer la fonction en raison d’un manque de mémoire.

Commentaires

Si hwnd a la valeur Null, SQLCreateDataSource retourne FALSE. Sinon, il affiche la boîte de dialogue Créer une source de données avec une page d’Assistant pour choisir le type de source de données à configurer, comme illustré dans l’illustration suivante.

L’option par défaut est File Data Source. Lorsqu’une source de données a été choisie et que vous avez cliqué sur Suivant , la page de l’Assistant suivante qui contient la liste des pilotes installés s’affiche.

Si vous cliquez sur Annuler , la boîte de dialogue disparaît et SQLCreateDataSource retourne FALSE avec le code d’erreur ODBC_ERROR_USER_CANCELED. Si l’option Source de données utilisateur ou Source de données système a été sélectionnée, le bouton Avancé n’est pas disponible.

Lorsque vous cliquez sur le bouton Suivant , l’un des éléments suivants se produit, selon le type de source de données sélectionné :

• Si Source de données de fichier a été sélectionnée, une page d’Assistant s’affiche pour permettre à l’utilisateur d’entrer un nom de fichier.

• Si source de données utilisateur ou source de données système a été sélectionnée, une page d’Assistant affichant le type de source de données et de pilote s’affiche pour révision, et lorsque vous cliquez sur Terminer , la source de données est configurée.

Si vous cliquez sur Avancé à partir de la page de l’Assistant Création d’une nouvelle source de données, une page d’Assistant s’affiche pour permettre à l’utilisateur d’entrer des informations spécifiques au pilote. Dans la zone de texte de cette boîte de dialogue, tapez le pilote et les mots clés séparés par des retours, comme illustré dans l’illustration suivante.

Vous trouverez d’autres mots clés spécifiques au pilote sous la description de SQLDriverConnect. Tous les DSN à l’exception de DSN sont autorisés.

La valeur par défaut de l’option Vérifier cette connexion est TRUE. Cette valeur par défaut s’applique, que cette page de l’Assistant soit activée ou non. Si vous cliquez sur OK , la chaîne spécifiée dans la zone de texte et la valeur de l’option Vérifier cette connexion sont mises en cache. (Si vous cliquez sur le bouton Fermer ou Annuler , les informations spécifiques au pilote qui viennent d’être entrées sont perdues, car la chaîne spécifiée dans la zone de texte et la valeur de l’option Vérifier cette connexion ne sont pas mises en cache.)

Si la source de données fichier a été sélectionnée dans la première page de l’Assistant, une fois qu’un pilote a été sélectionné et que les valeurs de mot clé ont été entrées dans la page de l’Assistant Avancé, l’utilisateur est invité à entrer un nom de fichier. Cliquez sur Parcourir pour rechercher un nom de fichier, auquel cas le répertoire par défaut dans la zone Parcourir est spécifié par une combinaison du chemin spécifié par CommonFileDir dans HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion et de « 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 ».)

Quand un nom de fichier a été entré et que l’utilisateur clique sur Suivant , la validité du nom de fichier entré est vérifiée par rapport aux règles de nommage de fichier standard du système d’exploitation. Si le nom de fichier n’est pas valide, une boîte de message d’erreur informe l’utilisateur qu’un nom de fichier non valide a été entré. Une fois que l’utilisateur a accusé réception de la boîte de message, le focus est retourné à la page de l’Assistant dans laquelle le nom de fichier est entré. Si le nom de fichier est valide, une page d’Assistant qui affiche les paires mot clé-valeur sélectionnées s’affiche pour révision, comme illustré dans l’illustration suivante.

Si vous cliquez sur Terminer et que source de données fichier a été sélectionné comme type de source de données, et si l’option Vérifier cette connexion a la valeur TRUE, SQLDriverConnect est appelé avec les mots clés SAVEFILE et DRIVER . L’argument DriverCompletion a la valeur SQL_DRIVER_COMPLETE. Le nom de fichier du mot clé SAVEFILE est le nom qui a été entré ou choisi, et le nom du pilote pour le mot clé DRIVER est le nom qui a été choisi. Si une chaîne de connexion spécifique au pilote a été spécifiée dans la page de l’Assistant Avancé, cette chaîne est ajoutée après le mot clé DRIVER .

Si SQLDriverConnect retourne SQL_SUCCESS, le Gestionnaire de pilotes a créé le nom de source de données de fichier. SQLCreateDataSource retourne TRUE. Si SQLDriverConnect ne retourne pas SQL_SUCCESS, un message d’avertissement indique qu’une connexion n’a pas pu être établie à la source de données. Un DSN avec des informations de connexion minimales peut toujours être créé. Cette boîte de message permet à l’utilisateur d’annuler ou de poursuivre la création de fichier DSN.

Si l’utilisateur choisit de continuer à créer le DSN, ce processus se poursuit comme si l’option Vérifier cette connexion était définie sur FALSE. Si l’utilisateur choisit d’annuler, FALSE est retourné pour SQLCreateDataSource avec un code d’erreur ODBC_ERROR_CREATE_DSN_FAILED.

Si File Data Source a été sélectionné comme type de source de données et que l’option Vérifier cette connexion a la valeur FALSE, un nom de source de données de fichier est créé avec le mot clé DRIVER et la chaîne de connexion spécifiée par l’utilisateur (le cas échéant) à partir de la page De l’Assistant Avancé. Si la création du fichier a réussi, TRUE est retourné pour SQLCreateDataSource. Si la création du fichier n’a pas réussi, une boîte de message d’erreur avertit l’utilisateur de toute erreur retournée par le système d’exploitation. FALSE est retourné pour SQLCreateDataSource avec le code d’erreur ODBC_ERROR_CREATE_DSN_FAILED. Pour plus d’informations sur les sources de données de fichier, consultez Connexion à l’aide de sources de données de fichier ou SQLDriverConnect.

Si lasource de données utilisateur ou système a été sélectionnée comme type de source de données, ConfigDSN dans la bibliothèque de configuration du pilote est appelé avec la ODBC_ADD_DSN fRequest. Pour plus d’informations, consultez ConfigDSN.

Fonctions connexes

Pour obtenir des informations sur	Consultez
Gérer les sources de données	SQLManageDataSources