Fonction SQLDescribeCol

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

Résumé
SQLDescribeCol retourne le descripteur de résultat ( nom de colonne, type, taille de colonne, chiffres décimaux et nullabilité) pour une colonne dans le jeu de résultats. Ces informations sont également disponibles dans les champs de l’IRD.

Syntaxe

  
SQLRETURN SQLDescribeCol(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   ColumnNumber,  
      SQLCHAR *      ColumnName,  
      SQLSMALLINT    BufferLength,  
      SQLSMALLINT *  NameLengthPtr,  
      SQLSMALLINT *  DataTypePtr,  
      SQLULEN *      ColumnSizePtr,  
      SQLSMALLINT *  DecimalDigitsPtr,  
      SQLSMALLINT *  NullablePtr);  

Arguments

StatementHandle
[Entrée] Handle d’instruction.

ColumnNumber
[Entrée] Nombre de colonnes de données de résultat, classés séquentiellement dans l’ordre croissant des colonnes, à partir de 1. L’argument ColumnNumber peut également être défini sur 0 pour décrire la colonne bookmark.

ColumnName
[Sortie] Pointeur vers une mémoire tampon terminée par null dans laquelle retourner le nom de colonne. Cette valeur est lue à partir du champ SQL_DESC_NAME de l’IRD. Si la colonne n’est pas nommée ou si le nom de la colonne ne peut pas être déterminé, le pilote retourne une chaîne vide.

Si ColumnName a la valeur NULL, NameLengthPtr retourne toujours le nombre total de caractères (à l’exclusion du caractère de fin null pour les données de caractères) disponibles pour retourner dans la mémoire tampon pointée par ColumnName.

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

NameLengthPtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle renvoyer le nombre total de caractères (à l’exclusion de l’arrêt null) disponibles pour retourner dans *ColumnName. Si le nombre de caractères disponibles à retourner est supérieur ou égal à BufferLength, le nom de colonne dans *ColumnName est tronqué en BufferLength moins la longueur d’un caractère de terminaison null.

DataTypePtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le type de données SQL de la colonne. Cette valeur est lue à partir du champ SQL_DESC_CONCISE_TYPE de l’IRD. Il s’agit de l’une des valeurs des types de données SQL ou d’un type de données SQL spécifique au pilote. Si le type de données ne peut pas être déterminé, le pilote retourne SQL_UNKNOWN_TYPE.

Dans ODBC 3. x, SQL_TYPE_DATE, SQL_TYPE_TIME ou SQL_TYPE_TIMESTAMP sont retournés dans *DataTypePtr pour les données de date, d’heure ou d’horodatage, respectivement ; dans ODBC 2. x, SQL_DATE, SQL_TIME ou SQL_TIMESTAMP est retourné. Le Gestionnaire de pilotes effectue les mappages requis lorsqu’un fichier ODBC 2. l’application x fonctionne avec odbc 3. x pilote ou lorsqu’un ODBC 3. L’application x fonctionne avec odbc 2. x pilote.

Lorsque ColumnNumber est égal à 0 (pour une colonne de signet), SQL_BINARY est retourné dans *DataTypePtr pour les signets de longueur variable. (SQL_INTEGER est retourné si les signets sont utilisés par un odbc 3. x application fonctionnant avec odbc 2. x pilote ou par un ODBC 2. x application fonctionnant avec odbc 3. x pilote.)

Pour plus d’informations sur ces types de données, consultez Types de données SQL dans l’Annexe D : Types de données. Pour plus d’informations sur les types de données SQL spécifiques aux pilotes, consultez la documentation du pilote.

ColumnSizePtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner la taille (en caractères) de la colonne sur la source de données. Si la taille de colonne ne peut pas être déterminée, le pilote retourne 0. Pour plus d’informations sur la taille des colonnes, consultez Taille de colonne, Chiffres décimaux, Longueur de transfert d’octet et Taille d’affichage dans l’Annexe D : Types de données.

DecimalDigitsPtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le nombre de chiffres décimaux de la colonne sur la source de données. Si le nombre de chiffres décimaux ne peut pas être déterminé ou n’est pas applicable, le pilote retourne 0. Pour plus d’informations sur les chiffres décimaux, consultez Taille de colonne, Chiffres décimaux, Longueur de transfert d’octet et Taille d’affichage dans l’Annexe D : Types de données.

NullablePtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle renvoyer une valeur qui indique si la colonne autorise les valeurs NULL. Cette valeur est lue à partir du champ SQL_DESC_NULLABLE de l’IRD. Les valeurs possibles sont les suivantes :

SQL_NO_NULLS : la colonne n’autorise pas les valeurs NULL.

SQL_NULLABLE : la colonne autorise les valeurs NULL.

SQL_NULLABLE_UNKNOWN : le pilote ne peut pas déterminer si la colonne autorise les valeurs NULL.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLDescribeCol 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 Handle of StatementHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLDescribeCol 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 *ColumnName n’étant pas assez grande pour renvoyer le nom de colonne entier, le nom de la colonne a été tronqué. La longueur du nom de la colonne non structurée est retournée dans *NameLengthPtr. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
07005	Instruction préparée et non spécification de curseur	L’instruction associée à l’instruction StatementHandle n’a pas retourné de jeu de résultats. Il n’y avait aucune colonne à décrire.
07009	Index de descripteur non valide	(DM) La valeur spécifiée pour l’argument ColumnNumber était égale à 0 et l’option d’instruction SQL_ATTR_USE_BOOKMARKS était SQL_UB_OFF. La valeur spécifiée pour l’argument ColumnNumber était supérieure au nombre de colonnes dans le jeu de résultats.
08S01	Échec de la liaison de communication	La liaison de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant que la fonction n’ait terminé le traitement.
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	Échec 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.
HY008	Opération annulée	Le traitement asynchrone a été activé pour l’instruction StatementHandle. La fonction a été appelée et, avant de terminer l’exécution, SQLCancel ou SQLCancelHandle a été appelé sur l’InstructionHandle. Ensuite, la fonction a été appelée à nouveau sur l’InstructionHandle. La fonction a été appelée et, avant de terminer l’exécution, SQLCancel ou SQLCancelHandle a été appelé sur l’InstructionHandle à partir d’un autre thread dans une application multithread.
HY010	Erreur de séquence de fonction	(DM) Une fonction d’exécution asynchrone a été appelée pour le handle de connexion associé à l’InstructionHandle. Cette fonction asynchrone était toujours en cours d’exécution lorsque SQLDescribeCol a été appelé. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’instruction StatementHandle 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. (DM) Une fonction d’exécution asynchrone (et non celle-ci) a été appelée pour l’InstructionHandle et s’exécutait toujours lorsque cette fonction a été appelée. (DM) La fonction a été appelée avant d’appeler SQLPrepare, SQLExecute ou une fonction de catalogue sur le handle d’instruction. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour l’InstructionHandle et a 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.
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 BufferLength était inférieure à 0.
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é à l’InstructionHandle ne prend pas en charge la fonction .
IM017	L’interrogation est désactivée en mode de notification asynchrone	Chaque fois que le modèle de notification est utilisé, l’interrogation est désactivée.
IM018	SQLCompleteAsync n’a pas été appelé pour effectuer l’opération asynchrone précédente sur ce handle.	Si l’appel de fonction précédent sur le handle retourne SQL_STILL_EXECUTING et si le mode de notification est activé, SQLCompleteAsync doit être appelé sur le handle pour effectuer le post-traitement et terminer l’opération.

SQLDescribeCol peut retourner n’importe quel SQLSTATE qui peut être retourné par SQLPrepare ou SQLExecute lorsqu’il est appelé après SQLPrepare et avant SQLExecute, selon le moment où la source de données évalue l’instruction SQL associée au handle d’instruction.

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

Commentaires

Une application appelle généralement SQLDescribeCol après un appel à SQLPrepare et avant ou après l’appel associé à SQLExecute. Une application peut également appeler SQLDescribeCol après un appel à SQLExecDirect. Pour plus d’informations, consultez Métadonnées du jeu de résultats.

SQLDescribeCol récupère le nom, le type et la longueur de colonne générés par une instruction SELECT . Si la colonne est une expression, *ColumnName est une chaîne vide ou un nom défini par le pilote.

Notes

ODBC prend en charge SQL_NULLABLE_UNKNOWN en tant qu’extension, même si la spécification Open Group et SQL Access Group Call Level Interface ne spécifie pas l’option pour SQLDescribeCol.

Fonctions connexes

Pour obtenir des informations sur	Consultez
Liaison d’une mémoire tampon à une colonne dans un jeu de résultats	SQLBindCol
Annulation du traitement des instructions	SQLCancel
Retour d’informations sur une colonne dans un jeu de résultats	SQLColAttribute
Extraction de plusieurs lignes de données	SQLFetch
Retour du nombre de colonnes de jeu de résultats	SQLNumResultCols
Préparation d’une instruction pour l’exécution	SQLPrepare

Voir aussi

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