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.

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

Voir aussi

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