SQLDataSources, fonction

Conformité
Version introduite : Conformité aux normes ODBC 1.0 : ISO 92

Résumé
SQLDataSources retourne des informations sur une source de données. Cette fonction est implémentée uniquement par le Gestionnaire de pilotes.

Syntaxe

  
SQLRETURN SQLDataSources(  
     SQLHENV          EnvironmentHandle,  
     SQLUSMALLINT     Direction,  
     SQLCHAR *        ServerName,  
     SQLSMALLINT      BufferLength1,  
     SQLSMALLINT *    NameLength1Ptr,  
     SQLCHAR *        Description,  
     SQLSMALLINT      BufferLength2,  
     SQLSMALLINT *    NameLength2Ptr);  

Arguments

EnvironmentHandle
[Entrée] Handle d’environnement.

Sens
[Entrée] Détermine la source de données sur laquelle le Gestionnaire de pilotes retourne des informations. Valeurs possibles :

SQL_FETCH_NEXT (pour extraire le nom de la source de données suivante dans la liste), SQL_FETCH_FIRST (pour extraire à partir du début de la liste), SQL_FETCH_FIRST_USER (pour extraire le premier nom de source de données utilisateur) ou SQL_FETCH_FIRST_SYSTEM (pour extraire le premier DSN système).

Lorsque Direction est défini sur SQL_FETCH_FIRST, les appels suivants à SQLDataSources avec Direction défini sur SQL_FETCH_NEXT retournent à la fois les DSN utilisateur et système. Lorsque Direction est défini sur SQL_FETCH_FIRST_USER, tous les appels ultérieurs à SQLDataSources avec Direction défini sur SQL_FETCH_NEXT retournent uniquement les noms DSN utilisateur. Lorsque Direction est défini sur SQL_FETCH_FIRST_SYSTEM, tous les appels ultérieurs à SQLDataSources avec Direction défini sur SQL_FETCH_NEXT retournent uniquement les DSN système.

ServerName
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le nom de la source de données.

Si ServerName a la valeur NULL, NameLength1Ptr retourne toujours le nombre total de caractères (à l’exclusion du caractère d’arrêt Null pour les données de caractères) pouvant être retournés dans la mémoire tampon vers laquelle serverName pointe.

BufferLength1
[Entrée] Longueur de la mémoire tampon *ServerName , en caractères ; cette valeur ne doit pas nécessairement être supérieure à SQL_MAX_DSN_LENGTH plus le caractère d’arrêt Null.

NameLength1Ptr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le nombre total de caractères (à l’exception du caractère d’arrêt Null) disponibles à retourner dans *ServerName. Si le nombre de caractères disponibles à retourner est supérieur ou égal à BufferLength1, le nom de la source de données dans *ServerName est tronqué en BufferLength1 moins la longueur d’un caractère de terminaison Null.

Description
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner la description du pilote associé à la source de données. Par exemple, dBASE ou SQL Server.

Si Description a la valeur NULL, NameLength2Ptr 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 vers laquelle la description est indiquée.

BufferLength2
[Entrée] Longueur en caractères de la mémoire tampon *Description .

NameLength2Ptr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le nombre total de caractères (à l’exclusion du caractère de terminaison Null) pouvant être retournés dans *Description. Si le nombre de caractères disponibles à retourner est supérieur ou égal à BufferLength2, la description du pilote dans *Description est tronquée en BufferLength2 moins la longueur d’un caractère d’arrêt Null.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLDataSources retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec un HandleType de SQL_HANDLE_ENV et un Handle de EnvironmentHandle. Le tableau suivant répertorie les valeurs SQLSTATE généralement retournées par SQLDataSources 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	(DM) Message d’information spécifique au gestionnaire de pilotes. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
01004	Données de chaîne, tronquées à droite	(DM) La mémoire tampon *ServerName n’était pas assez grande pour renvoyer le nom complet de la source de données. Par conséquent, le nom a été tronqué. La longueur du nom complet de la source de données est retournée dans *NameLength1Ptr. (La fonction retourne SQL_SUCCESS_WITH_INFO.) (DM) La mémoire tampon *Description n’était pas assez grande pour renvoyer la description complète du pilote. Par conséquent, la description a été tronquée. La longueur de la description non chiffrée de la source de données est retournée dans *NameLength2Ptr. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
HY000	Erreur générale	(DM) 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 *MessageText décrit l’erreur et sa cause.
HY001	Erreur d’allocation de mémoire	(DM) 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.
HY010	Erreur de séquence de fonction	(DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’InstructionHandle et a retourné SQL_PARAM_DATA_AVAILABLE. Cette fonction a été appelée avant la récupération des données pour tous les paramètres diffusés en continu.
HY013	Erreur de gestion de la mémoire	L’appel de fonction n’a pas pu être traité, car les objets de 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 BufferLength1 était inférieure à 0. (DM) La valeur spécifiée pour l’argument BufferLength2 était inférieure à 0.
HY103	Code de récupération non valide	(DM) La valeur spécifiée pour l’argument Direction n’est pas égale à SQL_FETCH_FIRST, SQL_FETCH_FIRST_USER, SQL_FETCH_FIRST_SYSTEM ou SQL_FETCH_NEXT.
HY117	La connexion est suspendue en raison d’un état de transaction inconnu. Seules les fonctions de déconnexion et de lecture seule sont autorisées.	(DM) Pour plus d’informations sur l’état suspendu, consultez Fonction SQLEndTran.

Commentaires

Étant donné que SQLDataSources est implémenté dans le Gestionnaire de pilotes, il est pris en charge pour tous les pilotes, quelle que soit la conformité aux normes d’un pilote particulier.

Une application peut appeler SQLDataSources plusieurs fois pour récupérer tous les noms de source de données. Le Gestionnaire de pilotes récupère ces informations à partir des informations système. Lorsqu’il n’y a plus de noms de source de données, le Gestionnaire de pilotes retourne SQL_NO_DATA. Si SQLDataSources est appelé avec SQL_FETCH_NEXT immédiatement après qu’il a retourné SQL_NO_DATA, il retourne le premier nom de la source de données. Pour plus d’informations sur la façon dont une application utilise les informations retournées par SQLDataSources, consultez Choix d’une source de données ou d’un pilote.

Si SQL_FETCH_NEXT est passé à SQLDataSources la première fois qu’il est appelé, il retourne le premier nom de la source de données.

Le pilote détermine comment les noms des sources de données sont mappés aux sources de données réelles.

Fonctions connexes

Pour obtenir des informations sur	Consultez
Découverte et liste des valeurs requises pour se connecter à une source de données	Fonction SQLBrowseConnect
Connexion à une source de données	SQLConnect, fonction
Connexion à une source de données à l’aide d’une chaîne de connexion ou d’une boîte de dialogue	SQLDriverConnect, fonction
Retour des descriptions et des attributs des pilotes	SQLDrivers, fonction

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC