SQLGetDescRec, fonction

  • Article

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

Résumé
SQLGetDescRec retourne les paramètres ou valeurs actuels de plusieurs champs d’un enregistrement de descripteur. Les champs retournés décrivent le nom, le type de données et le stockage des données de colonne ou de paramètre.

Syntaxe

  
SQLRETURN SQLGetDescRec(  
      SQLHDESC        DescriptorHandle,  
      SQLSMALLINT     RecNumber,  
      SQLCHAR *       Name,  
      SQLSMALLINT     BufferLength,  
      SQLSMALLINT *   StringLengthPtr,  
      SQLSMALLINT *   TypePtr,  
      SQLSMALLINT *   SubTypePtr,  
      SQLLEN *        LengthPtr,  
      SQLSMALLINT *   PrecisionPtr,  
      SQLSMALLINT *   ScalePtr,  
      SQLSMALLINT *   NullablePtr);

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 1, le numéro d’enregistrement 0 étant l’enregistrement de signet. L’argument RecNumber doit être inférieur ou égal à la valeur de SQL_DESC_COUNT. 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 à SQLGetDescRec renvoie les valeurs par défaut des champs. (Pour plus d’informations, consultez « Initialisation des champs de descripteur » dans SQLSetDescField.)

Nom
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le champ SQL_DESC_NAME pour l’enregistrement de descripteur.

Si Name a la valeur NULL, StringLengthPtr 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 pointée par Name.

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

StringLengthPtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle renvoyer le nombre de caractères de données disponibles à retourner dans la mémoire tampon *Nom , à l’exclusion du caractère d’arrêt Null. Si le nombre de caractères est supérieur ou égal à BufferLength, les données de *Name sont tronquées en BufferLength moins la longueur d’un caractère d’arrêt Null et sont terminées par la valeur Null par le pilote.

TypePtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner la valeur du champ SQL_DESC_TYPE pour l’enregistrement de descripteur.

SubTypePtr
[Sortie] Pour les enregistrements dont le type est SQL_DATETIME ou SQL_INTERVAL, il s’agit d’un pointeur vers une mémoire tampon dans laquelle retourner la valeur du champ SQL_DESC_DATETIME_INTERVAL_CODE.

LengthPtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner la valeur du champ SQL_DESC_OCTET_LENGTH pour l’enregistrement de descripteur.

PrecisionPtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner la valeur du champ SQL_DESC_PRECISION pour l’enregistrement de descripteur.

ScalePtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner la valeur du champ SQL_DESC_SCALE pour l’enregistrement de descripteur.

NullablePtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner la valeur du champ SQL_DESC_NULLABLE pour l’enregistrement de descripteur.

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 SQLGetDescRec 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_DESC et un Handlede DescriptorHandle. Le tableau suivant répertorie les valeurs SQLSTATE généralement retournées par SQLGetDescRec 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 *Name n’était pas assez grande pour renvoyer l’intégralité du champ de descripteur. Par conséquent, 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 L’argument FieldIdentifier était un champ d’enregistrement, l’argument RecNumber a été défini sur 0 et l’argument DescriptorHandle était un handle IPD.

(DM) L’argument RecNumber a été défini sur 0, et l’attribut d’instruction SQL_ATTR_USE_BOOKMARKS a été défini sur SQL_UB_OFF, et l’argument DescriptorHandle était un handle IRD.

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 IRD, et le handle d’instruction associé n’était pas à l’état 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 lors de l’appel de SQLGetDescRec .
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.
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é à DescriptorHandle ne prend pas en charge la fonction .

Commentaires

Une application peut appeler SQLGetDescRec pour récupérer les valeurs des champs de descripteur suivants pour une colonne ou un paramètre unique :

  • SQL_DESC_NAME

  • SQL_DESC_TYPE

  • SQL_DESC_DATETIME_INTERVAL_CODE (pour les enregistrements dont le type est SQL_DATETIME ou SQL_INTERVAL)

  • SQL_DESC_OCTET_LENGTH

  • SQL_DESC_PRECISION

  • SQL_DESC_SCALE

  • SQL_DESC_NULLABLE

SQLGetDescRec ne récupère pas les valeurs des champs d’en-tête.

Une application peut empêcher le retour d’un paramètre de champ en définissant l’argument qui correspond au champ sur un pointeur Null.

Lorsqu’une application appelle SQLGetDescRec 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 SQLGetDescRec pour le champ SQL_DESC_NAME ou SQL_DESC_NULLABLE d’un APD ou ARD renvoie SQL_SUCCESS mais une valeur non définie pour le champ.

Lorsqu’une application appelle SQLGetDescRec 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, consultez « Initialisation des champs de descripteur » dans SQLSetDescField.

Les valeurs des champs peuvent également être récupérées individuellement par un appel à SQLGetDescField. Pour obtenir une description des champs dans un en-tête ou un enregistrement de descripteur, consultez SQLSetDescField. Pour plus d’informations sur les descripteurs, consultez Descripteurs.

Pour obtenir des informations sur Consultez
Liaison d’une colonne Fonction SQLBindCol
Liaison d’un paramètre Fonction SQLBindParameter
Obtention d’un champ de descripteur Fonction SQLGetDescField
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