Fonction SQLGetDescField

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

Résumé
SQLGetDescField retourne le paramètre actuel ou la valeur d’un champ unique d’un enregistrement de descripteur.

Syntaxe

  
SQLRETURN SQLGetDescField(  
     SQLHDESC        DescriptorHandle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     FieldIdentifier,  
     SQLPOINTER      ValuePtr,  
     SQLINTEGER      BufferLength,  
     SQLINTEGER *    StringLengthPtr);  

Arguments

DescriptorHandle
[Entrée] Handle de descripteur.

RecNumber
[Entrée] Indique l’enregistrement de descripteur à partir duquel l’application recherche des informations. Les enregistrements de descripteur sont numérotés à partir de 0, le numéro d’enregistrement 0 étant l’enregistrement de signet. Si l’argument FieldIdentifier indique un champ d’en-tête, RecNumber est ignoré. Si RecNumber est inférieur ou égal à SQL_DESC_COUNT mais que la ligne ne contient pas de données pour une colonne ou un paramètre, un appel à SQLGetDescField renvoie les valeurs par défaut des champs. (Pour plus d’informations, consultez « Initialisation des champs de descripteur » dans SQLSetDescField.)

FieldIdentifier
[Entrée] Indique le champ du descripteur dont la valeur doit être retournée. Pour plus d’informations, consultez la section « Argument FieldIdentifier » dans SQLSetDescField.

ValuePtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner les informations de descripteur. Le type de données dépend de la valeur de FieldIdentifier.

Si ValuePtr est de type entier, les applications doivent utiliser une mémoire tampon de SQLULEN et initialiser la valeur sur 0 avant d’appeler cette fonction, car certains pilotes peuvent écrire uniquement les 32 bits inférieurs ou 16 bits d’une mémoire tampon et laisser le bit d’ordre supérieur inchangé.

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

BufferLength
[Entrée] Si FieldIdentifier est un champ défini par ODBC et que ValuePtr pointe vers une chaîne de caractères ou une mémoire tampon binaire, cet argument doit être la longueur de *ValuePtr. Si FieldIdentifier est un champ défini par ODBC et *ValuePtr est un entier, BufferLength est ignoré. Si la valeur dans *ValuePtr est d’un type de données Unicode (lors de l’appel de SQLGetDescFieldW), l’argument BufferLength doit être un nombre pair.

Si FieldIdentifier est un champ défini par le pilote, l’application indique la nature du champ au Gestionnaire de pilotes en définissant l’argument BufferLength . BufferLength peut avoir les valeurs suivantes :

• Si *ValuePtr est un pointeur vers une chaîne de caractères, BufferLength est la longueur de la chaîne ou du SQL_NTS.

• Si *ValuePtr est un pointeur vers une mémoire tampon binaire, l’application place le résultat de la macro SQL_LEN_BINARY_ATTR(length) dans BufferLength. Cela place une valeur négative dans BufferLength.

• Si *ValuePtr est un pointeur vers une valeur autre qu’une chaîne de caractères ou une chaîne binaire, BufferLength doit avoir la valeur SQL_IS_POINTER.

• Si *ValuePtr contient un type de données de longueur fixe, BufferLength est SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT ou SQL_IS_USMALLINT, le cas échéant.

StringLengthPtr
[Sortie] Pointeur vers la mémoire tampon dans laquelle retourner le nombre total d’octets (à l’exclusion du nombre d’octets requis pour le caractère d’arrêt null) pouvant être retournés dans *ValuePtr.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA ou SQL_INVALID_HANDLE.

SQL_NO_DATA est retourné si RecNumber est supérieur au nombre actuel d’enregistrements de descripteur.

SQL_NO_DATA est retourné si DescriptorHandle est un handle IRD et que l’instruction est à l’état préparé ou exécuté, mais qu’aucun curseur ouvert n’y était associé.

Diagnostics

Lorsque SQLGetDescField 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_STMT et un handled’instructionHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLGetDescField 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	Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
01004	Données de chaîne, tronquées à droite	La mémoire tampon *ValuePtr n’étant pas assez grande pour renvoyer l’intégralité du champ de descripteur, le champ a été tronqué. La longueur du champ de descripteur non fractionné est retournée dans *StringLengthPtr. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
07009	Index de descripteur non valide	(DM) L’argument RecNumber était égal à 0, l’attribut d’instruction SQL_ATTR_USE_BOOKMARK était SQL_UB_OFF et l’argument DescriptorHandle était un handle IRD. (Cette erreur peut être retournée pour un descripteur explicitement alloué uniquement si le descripteur est associé à un handle d’instruction.) L’argument FieldIdentifier était un champ d’enregistrement, l’argument RecNumber était 0 et l’argument DescriptorHandle était un handle IPD. L’argument RecNumber était inférieur à 0.
08S01	Échec de la liaison de communication	Le lien de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant la fin du traitement de la fonction.
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	Le pilote n’a pas pu allouer la mémoire nécessaire pour prendre en charge l’exécution ou l’achèvement de la fonction.
HY007	L’instruction associée n’est pas préparée	DescriptorHandle était associé à un InstructionHandle en tant qu’IRD, et le handle d’instruction associé n’avait pas été préparé ou exécuté.
HY010	Erreur de séquence de fonction	(DM) DescriptorHandle était associé à un InstructionHandle pour lequel une fonction en cours d’exécution asynchrone (et non celle-ci) était appelée et était toujours en cours d’exécution lorsque cette fonction a été appelée. (DM) DescriptorHandle a été associé à un InstructionHandle pour lequel SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé et retourné SQL_NEED_DATA. Cette fonction a été appelée avant l’envoi des données pour toutes les colonnes ou paramètres de données au moment de l’exécution. (DM) Une fonction d’exécution asynchrone a été appelée pour le handle de connexion associé au DescriptorHandle. Cette fonction asynchrone était toujours en cours d’exécution lorsque la fonction SQLGetDescField a été appelée.
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.
HY021	Informations de descripteur incohérentes	Les champs SQL_DESC_TYPE et SQL_DESC_DATETIME_INTERVAL_CODE ne forment pas un type SQL ODBC valide, un type SQL spécifique au pilote valide (pour les IPD) ou un type C ODBC valide (pour les API ou LES ARD).
HY090	Chaîne ou longueur de mémoire tampon non valide	(DM) *ValuePtr était une chaîne de caractères et BufferLength était inférieur à zéro.
HY091	Identificateur de champ de descripteur non valide	FieldIdentifier n’était pas un champ défini par ODBC et n’était pas une valeur définie par l’implémentation. FieldIdentifier n’était pas défini pour le DescriptorHandle.
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.
HYT01	Délai d’attente de la connexion expiré	Le délai d’expiration de la connexion a expiré avant que la source de données ne réponde à la demande. Le délai d’expiration de connexion est défini via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Le pilote ne prend pas en charge cette fonction	(DM) Le pilote associé au DescriptorHandle ne prend pas en charge la fonction .

Commentaires

Une application peut appeler SQLGetDescField pour retourner la valeur d’un champ unique d’un enregistrement de descripteur. Un appel à SQLGetDescField peut retourner le paramètre de n’importe quel champ dans n’importe quel type de descripteur, y compris les champs d’en-tête, les champs d’enregistrement et les champs de signet. Une application peut obtenir les paramètres de plusieurs champs dans les descripteurs identiques ou différents, dans un ordre arbitraire, en effectuant des appels répétés à SQLGetDescField. SQLGetDescField peut également être appelé pour retourner des champs de descripteur définis par le pilote.

Pour des raisons de performances, une application ne doit pas appeler SQLGetDescField pour un IRD avant d’exécuter une instruction.

Les paramètres de plusieurs champs qui décrivent le nom, le type de données et le stockage des données de colonne ou de paramètre peuvent également être récupérés en un seul appel à SQLGetDescRec. SQLGetStmtAttr peut être appelé pour retourner le paramètre d’un champ unique dans l’en-tête de descripteur qui est également un attribut d’instruction. SQLColAttribute, SQLDescribeCol et SQLDescribeParam retournent des champs d’enregistrement ou de signet.

Lorsqu’une application appelle SQLGetDescField pour récupérer la valeur d’un champ qui n’est pas défini pour un type de descripteur particulier, la fonction retourne SQL_SUCCESS mais la valeur retournée pour le champ n’est pas définie. Par exemple, l’appel de SQLGetDescField pour le champ SQL_DESC_NAME ou SQL_DESC_NULLABLE d’un champ APD ou ARD renvoie SQL_SUCCESS mais une valeur non définie pour le champ.

Lorsqu’une application appelle SQLGetDescField pour récupérer la valeur d’un champ défini pour un type de descripteur particulier, mais qui n’a pas de valeur par défaut et qui n’a pas encore été défini, la fonction retourne SQL_SUCCESS mais la valeur retournée pour le champ n’est pas définie. Pour plus d’informations sur l’initialisation des champs de descripteur et leur description, consultez « Initialisation des champs de descripteur » dans SQLSetDescField. Pour plus d’informations sur les descripteurs, consultez Descripteurs.

Fonctions connexes

Pour obtenir des informations sur	Consultez
Obtention de plusieurs champs de descripteur	SQLGetDescRec, fonction
Définition d’un champ de descripteur unique	SQLSetDescField, fonction
Définition de plusieurs champs de descripteur	SQLSetDescRec, fonction

Voir aussi

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