SQLDrivers, fonction

Conformité
Version introduite : Conformité aux normes ODBC 2.0 : ODBC

Résumé
SQLDrivers répertorie les descriptions des pilotes et les mots clés d’attribut du pilote. Cette fonction est implémentée uniquement par le Gestionnaire de pilotes.

Syntaxe

  
SQLRETURN SQLDrivers(  
     SQLHENV         EnvironmentHandle,  
     SQLUSMALLINT    Direction,  
     SQLCHAR *       DriverDescription,  
     SQLSMALLINT     BufferLength1,  
     SQLSMALLINT *   DescriptionLengthPtr,  
     SQLCHAR *       DriverAttributes,  
     SQLSMALLINT     BufferLength2,  
     SQLSMALLINT *   AttributesLengthPtr);  

Arguments

EnvironmentHandle
[Entrée] Handle d’environnement.

Sens
[Entrée] Détermine si le Gestionnaire de pilotes extrait la description du pilote suivante dans la liste (SQL_FETCH_NEXT) ou si la recherche commence à partir du début de la liste (SQL_FETCH_FIRST).

DriverDescription
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner la description du pilote.

Si DriverDescription a la valeur NULL, DescriptionLengthPtr 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 driverDescription pointe.

BufferLength1
[Entrée] Longueur de la mémoire tampon *DriverDescription , en caractères.

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

DriverAttributes
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner la liste des paires de valeurs d’attribut de pilote (voir « Commentaires »).

Si DriverAttributes a la valeur NULL, AttributesLengthPtr retourne toujours le nombre total d’octets (à 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 driverAttributes pointe.

BufferLength2
[Entrée] Longueur de la mémoire tampon *DriverAttributes , en caractères. Si la valeur *DriverDescription est une chaîne Unicode (lors de l’appel de SQLDriversW), l’argument BufferLength doit être un nombre pair.

AttributesLengthPtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le nombre total d’octets (à l’exclusion de l’octet de terminaison Null) disponibles à retourner dans *DriverAttributes. Si le nombre d’octets disponibles à retourner est supérieur ou égal à BufferLength2, la liste des paires de valeurs d’attribut dans *DriverAttributes est tronquée en BufferLength2 moins la longueur du caractère d’arrêt Null.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLDrivers 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 SQLDrivers 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 *DriverDescription 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 complète du pilote est retournée dans *DescriptionLengthPtr. (La fonction retourne SQL_SUCCESS_WITH_INFO.) (DM) La mémoire tampon *DriverAttributes n’était pas assez grande pour renvoyer la liste complète des paires de valeurs d’attribut. Par conséquent, la liste a été tronquée. La longueur de la liste non structurée de paires de valeurs d’attribut est retournée dans *AttributesLengthPtr. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
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 *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 ou égale à 1.
HY103	Code de récupération non valide	(DM) La valeur spécifiée pour l’argument Direction n’était pas égale à SQL_FETCH_FIRST 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

SQLDrivers retourne la description du pilote dans la mémoire tampon *DriverDescription . Il retourne des informations supplémentaires sur le pilote dans la mémoire tampon *DriverAttributes sous la forme d’une liste de paires mot clé-valeur. Tous les mots clés répertoriés dans les informations système pour les pilotes sont retournés pour tous les pilotes, à l’exception de CreateDSN, qui est utilisé pour demander la création de sources de données et est donc facultatif. Chaque paire se termine par un octet null, et la liste complète se termine par un octet null (autrement dit, deux octets Null marquent la fin de la liste). Par exemple, un pilote basé sur un fichier utilisant la syntaxe C peut retourner la liste d’attributs suivante (« \0 » représente un caractère null) :

FileUsage=1\0FileExtns=*.dbf\0\0  

Si *DriverAttributes n’est pas assez grand pour contenir la liste entière, la liste est tronquée, SQLDrivers renvoie SQLSTATE 01004 (Données tronquées) et la longueur de la liste (à l’exclusion de l’octet final de terminaison Null) est retournée dans *AttributesLengthPtr.

Les mots clés d’attribut de pilote sont ajoutés à partir des informations système lors de l’installation du pilote. Pour plus d’informations, consultez Installation de composants ODBC.

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

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

Étant donné que SQLDrivers 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.

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
Retour des noms de sources de données	SQLDataSources, fonction
Connexion à une source de données à l’aide d’une chaîne de connexion ou d’une boîte de dialogue	SQLDriverConnect, fonction

Voir aussi

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