Fonction SQLColAttribute

Article
07/04/2024

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

Résumé
SQLColAttribute retourne des informations de descripteur pour une colonne dans un jeu de résultats. Les informations de descripteur sont retournées sous la forme d’une chaîne de caractères, d’une valeur dépendante du descripteur ou d’une valeur entière.

Remarque

Pour plus d’informations sur ce que le Gestionnaire de pilotes mappe cette fonction à lorsqu’une instance ODBC 3.x application fonctionne avec ODBC 2.Pilote x , consultez Fonctions de remplacement de mappage pour la compatibilité descendante des applications.

Syntaxe

  
SQLRETURN SQLColAttribute (  
      SQLHSTMT        StatementHandle,  
      SQLUSMALLINT    ColumnNumber,  
      SQLUSMALLINT    FieldIdentifier,  
      SQLPOINTER      CharacterAttributePtr,  
      SQLSMALLINT     BufferLength,  
      SQLSMALLINT *   StringLengthPtr,  
      SQLLEN *        NumericAttributePtr);

Arguments

StatementHandle
[Entrée] Handle d’instruction.

ColumnNumber
[Entrée] Numéro de l’enregistrement dans l’IRD à partir duquel la valeur du champ doit être récupérée. Cet argument correspond au nombre de colonnes de données de résultat, ordonné séquentiellement dans l’ordre croissant des colonnes, en commençant à 1. Les colonnes peuvent être décrites dans n’importe quel ordre.

La colonne 0 peut être spécifiée dans cet argument, mais toutes les valeurs, sauf SQL_DESC_TYPE et SQL_DESC_OCTET_LENGTH retournent des valeurs non définies.

FieldIdentifier
[Entrée] Handle de descripteur. Ce handle définit le champ dans l’IRD à interroger (par exemple, SQL_COLUMN_TABLE_NAME).

CharacterAttributePtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner la valeur dans le champ FieldIdentifier de la ligne ColumnNumber de l’IRD, si le champ est une chaîne de caractères. Sinon, le champ n’est pas utilisé.

Si CharacterAttributePtr a la valeur NULL, StringLengthPtr retourne toujours le nombre total d’octets (à l’exception du caractère d’arrêt null pour les données de caractères) disponible dans la mémoire tampon pointée par CharacterAttributePtr.

BufferLength
[Entrée] Si FieldIdentifier est un champ défini par ODBC et CharacterAttributePtr pointe vers une chaîne de caractères ou une mémoire tampon binaire, cet argument doit être la longueur de *CharacterAttributePtr. Si FieldIdentifier est un champ défini par ODBC et *CharacterAttributePtr est un entier, ce champ est ignoré. Si le *CharacterAttributePtr est une chaîne Unicode (lors de l’appel de SQLColAttributeW), 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 sur le Gestionnaire de pilotes en définissant l’argument BufferLength . BufferLength peut avoir les valeurs suivantes :

Si CharacterAttributePtr est un pointeur vers un pointeur, BufferLength doit avoir la valeur SQL_IS_POINTER.
Si CharacterAttributePtr est un pointeur vers une chaîne de caractères, bufferLength est la longueur de la mémoire tampon.
Si CharacterAttributePtr 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 CharacterAttributePtr est un pointeur vers un type de données de longueur fixe, BufferLength doit être l’un des éléments suivants : SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT ou SQL_IS_USMALLINT.

StringLengthPtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le nombre total d’octets (à l’exception de l’octet de terminaison Null pour les données de caractères) disponible dans *CharacterAttributePtr.

Pour les données de caractères, si le nombre d’octets disponibles à retourner est supérieur ou égal à BufferLength, les informations de descripteur dans *CharacterAttributePtr sont tronquées à BufferLength moins la longueur d’un caractère d’arrêt null et sont terminées par null par le pilote.

Pour tous les autres types de données, la valeur de BufferLength est ignorée et le pilote suppose que la taille de *CharacterAttributePtr est de 32 bits.

NumericAttributePtr
[Sortie] Pointeur vers une mémoire tampon entière dans laquelle retourner la valeur dans le champ FieldIdentifier de la ligne ColumnNumber de l’IRD, si le champ est un type de descripteur numérique, tel que SQL_DESC_COLUMN_LENGTH. Sinon, le champ n’est pas utilisé. Notez que certains pilotes peuvent écrire uniquement les bits 32 bits inférieurs ou 16 bits d’une mémoire tampon et laisser le bit de l’ordre supérieur inchangé. Par conséquent, les applications doivent initialiser la valeur sur 0 avant d’appeler cette fonction.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLColAttribute 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 d’instructionHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLColAttribute 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	Erreur	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 *CharacterAttributePtr n’a pas été suffisamment grande pour retourner la valeur de chaîne entière, de sorte que la valeur de chaîne a été tronquée. La longueur de la valeur de chaîne nontruncée est retournée dans *StringLengthPtr. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
07005	Instruction préparée et non pas une spécification de curseur	L’instruction associée à StatementHandle n’a pas retourné un jeu de résultats et FieldIdentifier n’a pas été SQL_DESC_COUNT. Il n’y avait pas de colonnes à décrire.
07009	Index de descripteur non valide	(DM) La valeur spécifiée pour ColumnNumber était égale à 0 et l’attribut 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.
HY000	Erreur générale	Une erreur s’est produite pour laquelle il n’y avait aucun SQLSTATE spécifique et pour lequel aucun SQLSTATE spécifique à l’implémentation n’a été défini. Le message d’erreur retourné par SQLGetDiagField à partir de la structure des données de diagnostic décrit l’erreur et sa cause.
HY001	Erreur d’allocation de mémoire	Le pilote n’a pas pu allouer de 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 StatementHandle. La fonction a été appelée et avant l’exécution terminée, SQLCancel ou SQLCancelHandle a été appelée sur StatementHandle. Ensuite, la fonction a été appelée à nouveau sur l’instructionHandle. La fonction a été appelée et avant qu’elle ait terminé l’exécution, SQLCancel ou SQLCancelHandle a été appelée sur l’InstructionHandleà partir d’un autre thread dans une application multithread.
HY010	Erreur de séquence de fonction	(DM) Une fonction en cours d’exécution asynchrone a été appelée pour le handle de connexion associé à StatementHandle. Cette fonction asynchrone était toujours en cours d’exécution lorsque SQLColAttribute a été appelé. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’instruction StatementHandle et 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. (DM) La fonction a été appelée avant d’appeler SQLPrepare, SQLExecDirect ou une fonction de catalogue pour StatementHandle. (DM) Une fonction en cours d’exécution asynchrone (et non celle-ci) a été appelée pour l’instruction StatementHandle et était toujours en cours d’exécution lorsque cette fonction a été appelée. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour l’instructionHandle et retourné SQL_NEED_DATA. Cette fonction a été appelée avant que les données ne soient envoyées pour tous les paramètres ou colonnes de données à 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, éventuellement en raison de conditions de mémoire insuffisantes.
HY090	Longueur de la chaîne ou de la mémoire tampon non valide	(DM) CharacterAttributePtr est une chaîne de caractères, et BufferLength* a été inférieur à 0, mais pas égal à SQL_NTS.
HY091	Identificateur de champ de descripteur non valide	La valeur spécifiée pour l’argument FieldIdentifier n’était pas l’une des valeurs définies et n’était pas une valeur définie par l’implémentation.
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 la fonction SQLEndTran.
HYC00	Pilote non capable	La valeur spécifiée pour l’argument FieldIdentifier n’a pas été prise en charge par le pilote.
HYT01	Délai d’attente de la connexion expiré	La période d’expiration de la connexion a expiré avant que la source de données ne réponde à la demande. La période d’expiration de connexion est définie via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Le pilote ne prend pas en charge cette fonction	(DM) Le pilote associé à StatementHandle 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 terminer 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 un post-traitement et terminer l’opération.

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

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

Commentaires

Pour plus d’informations sur la façon dont les applications utilisent les informations retournées par SQLColAttribute, consultez Métadonnées du jeu de résultats.

SQLColAttribute retourne des informations dans *NumericAttributePtr ou dans *CharacterAttributePtr. Les informations entières sont retournées dans *NumericAttributePtr en tant que valeur SQLLEN ; tous les autres formats d’informations sont retournés dans *CharacterAttributePtr. Lorsque des informations sont retournées dans *NumericAttributePtr, le pilote ignore CharacterAttributePtr, BufferLength et StringLengthPtr. Lorsque des informations sont retournées dans *CharacterAttributePtr, le pilote ignore NumericAttributePtr.

SQLColAttribute retourne des valeurs des champs de descripteur de l’IRD. La fonction est appelée avec un handle d’instruction plutôt qu’un descripteur. Les valeurs retournées par SQLColAttribute pour les valeurs FieldIdentifier répertoriées plus loin dans cette section peuvent également être récupérées en appelant SQLGetDescField avec le handle IRD approprié.

Les champs de descripteur actuellement définis, la version d’ODBC dans laquelle ils ont été introduits et les arguments dans lesquels les informations sont retournées sont affichés plus loin dans cette section ; D’autres types de descripteur peuvent être définis par les pilotes pour tirer parti de différentes sources de données.

ODBC 3.x driver doit retourner une valeur pour chacun des champs de descripteur. Si un champ descripteur ne s’applique pas à un pilote ou à une source de données et, sauf indication contraire, le pilote retourne 0 dans *StringLengthPtr ou une chaîne vide dans *CharacterAttributePtr.

Compatibilité descendante

ODBC 3.x function SQLColAttribute remplace l’ODBC 2 déconseillé.x function SQLColAttributes. Lors du mappage de SQLColAttributes à SQLColAttribute (lorsqu’un ODBC 2.x application fonctionne avec ODBC 3.x driver) ou mapper SQLColAttribute à SQLColAttributes (lorsqu’un ODBC 3.x application fonctionne avec ODBC 2.x driver), le Gestionnaire de pilotes transmet la valeur de FieldIdentifier par le biais de FieldIdentifier , le mappe à une nouvelle valeur ou retourne une erreur, comme suit :

Remarque

Préfixe utilisé dans les valeurs FieldIdentifier dans ODBC 3.x a été modifié à partir de celui utilisé dans ODBC 2.x. Le nouveau préfixe est « SQL_DESC » ; l’ancien préfixe était « SQL_COLUMN ».

Si la valeur #define du odbc 2.xFieldIdentifier est identique à la valeur #define du odbc 3.xFieldIdentifier, la valeur de l’appel de fonction vient d’être transmise.
Valeurs #define du ODBC 2.xFieldIdentifiers SQL_COLUMN_LENGTH, SQL_COLUMN_PRECISION et SQL_COLUMN_SCALE sont différents des valeurs #define du odbc 3.xFieldIdentifiers SQL_DESC_PRECISION, SQL_DESC_SCALE et SQL_DESC_LENGTH. ODBC 2.Le pilote x n’a besoin que de prendre en charge ODBC 2.valeurs x . ODBC 3.Le pilote x doit prendre en charge les valeurs « SQL_COLUMN » et « SQL_DESC » pour ces trois FieldIdentifiers. Ces valeurs sont différentes, car la précision, l’échelle et la longueur sont définies différemment dans ODBC 3.x qu’ils étaient dans ODBC 2.x. Pour plus d’informations, consultez La taille des colonnes, les chiffres décimaux, la longueur des octets de transfert et la taille d’affichage.
Si la valeur #define du odbc 2.xFieldIdentifier est différent de la valeur #define du odbc 3.xFieldIdentifier, tel qu’il se produit avec les valeurs COUNT, NAME et NULLABLE, la valeur de l’appel de fonction est mappée à la valeur correspondante. Par exemple, SQL_COLUMN_COUNT est mappé à SQL_DESC_COUNT et SQL_DESC_COUNT est mappé à SQL_COLUMN_COUNT, selon la direction du mappage.
Si FieldIdentifier est une nouvelle valeur dans ODBC 3.x, pour lequel il n’y avait aucune valeur correspondante dans ODBC 2.x, il ne sera pas mappé lorsqu’un ODBC 3.x application l’utilise dans un appel à SQLColAttribute dans un ODBC 2.x driver, et l’appel retourne SQLSTATE HY091 (identificateur de champ de descripteur non valide).

Le tableau suivant répertorie les types de descripteur retournés par SQLColAttribute. Le type des valeurs NumericAttributePtr est SQLLEN *.

FieldIdentifier	Information retourné dans	Description
SQL_DESC_AUTO_UNIQUE_VALUE (ODBC 1.0)	NumericAttributePtr	SQL_TRUE si la colonne est une colonne de création automatique. SQL_FALSE si la colonne n’est pas une colonne de création automatique ou n’est pas numérique. Ce champ est valide uniquement pour les colonnes de type de données numériques. Une application peut insérer des valeurs dans une ligne contenant une colonne de création automatique, mais ne peut généralement pas mettre à jour les valeurs dans la colonne. Lorsqu’une insertion est effectuée dans une colonne de création automatique, une valeur unique est insérée dans la colonne au moment de l’insertion. L’incrément n’est pas défini, mais est spécifique à la source de données. Une application ne doit pas supposer qu’une colonne de création automatique commence à un point particulier ou incrémente par une valeur particulière.
SQL_DESC_BASE_COLUMN_NAME (ODBC 3.0)	CharacterAttributePtr	Nom de colonne de base de la colonne du jeu de résultats. Si un nom de colonne de base n’existe pas (comme dans le cas des colonnes qui sont des expressions), cette variable contient une chaîne vide. Ces informations sont retournées à partir du champ d’enregistrement SQL_DESC_BASE_COLUMN_NAME de l’IRD, qui est un champ en lecture seule.
SQL_DESC_BASE_TABLE_NAME (ODBC 3.0)	CharacterAttributePtr	Nom de la table de base qui contient la colonne. Si le nom de la table de base ne peut pas être défini ou n’est pas applicable, cette variable contient une chaîne vide. Ces informations sont retournées à partir du champ d’enregistrement SQL_DESC_BASE_TABLE_NAME de l’IRD, qui est un champ en lecture seule.
SQL_DESC_CASE_SENSITIVE (ODBC 1.0)	NumericAttributePtr	SQL_TRUE si la colonne est traitée comme sensible à la casse pour les classements et les comparaisons. SQL_FALSE si la colonne n’est pas traitée comme sensible à la casse pour les classements et les comparaisons ou si elle n’est pas traitée.
SQL_DESC_CATALOG_NAME (ODBC 2.0)	CharacterAttributePtr	Catalogue de la table qui contient la colonne. La valeur retournée est définie par l’implémentation si la colonne est une expression ou si la colonne fait partie d’une vue. Si la source de données ne prend pas en charge les catalogues ou si le nom du catalogue ne peut pas être déterminé, une chaîne vide est retournée. Ce champ d’enregistrement VARCHAR n’est pas limité à 128 caractères.
SQL_DESC_CONCISE_TYPE (ODBC 1.0)	NumericAttributePtr	Type de données concis. Pour les types de données datetime et intervalle, ce champ retourne le type de données concis ; par exemple, SQL_TYPE_TIME ou SQL_INTERVAL_YEAR. (Pour plus d’informations, consultez Identificateurs et descripteurs de type de données dans l’annexe D : Types de données.) Ces informations sont retournées à partir du champ d’enregistrement SQL_DESC_CONCISE_TYPE de l’IRD.
SQL_DESC_COUNT (ODBC 1.0)	NumericAttributePtr	Nombre de colonnes disponibles dans le jeu de résultats. Cela retourne 0 s’il n’existe aucune colonne dans le jeu de résultats. La valeur de l’argument ColumnNumber est ignorée. Ces informations sont retournées à partir du champ d’en-tête SQL_DESC_COUNT de l’IRD.
SQL_DESC_DISPLAY_SIZE (ODBC 1.0)	NumericAttributePtr	Nombre maximal de caractères requis pour afficher les données de la colonne. Pour plus d’informations sur la taille d’affichage, consultez Taille de colonne, Chiffres décimaux, Longueur des octets de transfert et Taille d’affichage dans l’annexe D : Types de données.
SQL_DESC_FIXED_PREC_SCALE (ODBC 1.0)	NumericAttributePtr	SQL_TRUE si la colonne a une précision fixe et une échelle différente de zéro qui sont spécifiques à la source de données. SQL_FALSE si la colonne ne dispose pas d’une précision fixe et d’une échelle différente de zéro qui sont spécifiques à la source de données.
SQL_DESC_LABEL (ODBC 2.0)	CharacterAttributePtr	Étiquette de colonne ou titre. Par exemple, une colonne nommée EmpName peut être étiquetée Nom de l’employé ou être étiquetée avec un alias. Si une colonne n’a pas d’étiquette, le nom de la colonne est retourné. Si la colonne n’est pas étiquetée et non nommée, une chaîne vide est retournée.
SQL_DESC_LENGTH (ODBC 3.0)	NumericAttributePtr	Valeur numérique qui est la longueur maximale ou réelle d’une chaîne de caractères ou d’un type de données binaire. Il s’agit de la longueur maximale des caractères d’un type de données de longueur fixe ou de la longueur réelle d’un type de données de longueur variable. Sa valeur exclut toujours l’octet d’arrêt null qui met fin à la chaîne de caractères. Ces informations sont retournées à partir du champ d’enregistrement SQL_DESC_LENGTH de l’IRD. Pour plus d’informations sur la longueur, consultez La taille des colonnes, les chiffres décimaux, la longueur des octets de transfert et la taille d’affichage dans l’annexe D : Types de données.
SQL_DESC_LITERAL_PREFIX (ODBC 3.0)	CharacterAttributePtr	Ce champ d’enregistrement VARCHAR(128) contient le caractère ou les caractères que le pilote reconnaît comme préfixe pour un littéral de ce type de données. Ce champ contient une chaîne vide pour un type de données pour lequel un préfixe littéral n’est pas applicable. Pour plus d’informations, consultez Préfixes littérals et suffixes.
SQL_DESC_LITERAL_SUFFIX (ODBC 3.0)	CharacterAttributePtr	Ce champ d’enregistrement VARCHAR(128) contient le caractère ou les caractères que le pilote reconnaît comme suffixe pour un littéral de ce type de données. Ce champ contient une chaîne vide pour un type de données pour lequel un suffixe littéral n’est pas applicable. Pour plus d’informations, consultez Préfixes littérals et suffixes.
SQL_DESC_LOCAL_TYPE_NAME (ODBC 3.0)	CharacterAttributePtr	Ce champ d’enregistrement VARCHAR(128) contient n’importe quel nom localisé (langue native) pour le type de données qui peut être différent du nom normal du type de données. S’il n’existe aucun nom localisé, une chaîne vide est retournée. Ce champ est uniquement à des fins d’affichage. Le jeu de caractères de la chaîne dépend des paramètres régionaux et est généralement le jeu de caractères par défaut du serveur.
SQL_DESC_NAME (ODBC 3.0)	CharacterAttributePtr	Alias de colonne, s’il s’applique. Si l’alias de colonne ne s’applique pas, le nom de colonne est retourné. Dans les deux cas, SQL_DESC_UNNAMED est définie sur SQL_NAMED. S’il n’existe aucun nom de colonne ou alias de colonne, une chaîne vide est retournée et SQL_DESC_UNNAMED est définie sur SQL_UNNAMED. Ces informations sont retournées à partir du champ d’enregistrement SQL_DESC_NAME de l’IRD.
SQL_DESC_NULLABLE (ODBC 3.0)	NumericAttributePtr	SQL_ NULLABLE si la colonne peut avoir des valeurs NULL ; SQL_NO_NULLS si la colonne n’a pas de valeurs NULL ; ou SQL_NULLABLE_UNKNOWN s’il n’est pas connu si la colonne accepte les valeurs NULL. Ces informations sont retournées à partir du champ d’enregistrement SQL_DESC_NULLABLE de l’IRD.
SQL_DESC_NUM_PREC_RADIX (ODBC 3.0)	NumericAttributePtr	Si le type de données dans le champ SQL_DESC_TYPE est un type de données numérique approximatif, ce champ SQLINTEGER contient une valeur de 2, car le champ SQL_DESC_PRECISION contient le nombre de bits. Si le type de données dans le champ SQL_DESC_TYPE est un type de données numérique exact, ce champ contient une valeur de 10, car le champ SQL_DESC_PRECISION contient le nombre de chiffres décimaux. Ce champ est défini sur 0 pour tous les types de données non numériques.
SQL_DESC_OCTET_LENGTH (ODBC 3.0)	NumericAttributePtr	Longueur, en octets, d’une chaîne de caractères ou d’un type de données binaire. Pour les types binaires ou caractères de longueur fixe, il s’agit de la longueur réelle en octets. Pour les types binaires ou caractères de longueur variable, il s’agit de la longueur maximale en octets. Cette valeur n’inclut pas le terminateur Null. Ces informations sont retournées par le champ d’enregistrement SQL_DESC_OCTET_LENGTH de l’IRD. Pour plus d’informations sur la longueur, consultez La taille des colonnes, les chiffres décimaux, la longueur des octets de transfert et la taille d’affichage dans l’annexe D : Types de données.
SQL_DESC_PRECISION (ODBC 3.0)	NumericAttributePtr	Valeur numérique qui, pour un type de données numérique, indique la précision applicable. Pour les types de données SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP et tous les types de données d’intervalle qui représentent un intervalle de temps, sa valeur est la précision applicable du composant fractionnaire de secondes. Ces informations sont retournées à partir du champ d’enregistrement SQL_DESC_PRECISION de l’IRD.
SQL_DESC_SCALE (ODBC 3.0)	NumericAttributePtr	Valeur numérique qui correspond à l’échelle applicable pour un type de données numérique. Pour les types de données DECIMAL et NUMERIC, il s’agit de l’échelle définie. Il n’est pas défini pour tous les autres types de données. Ces informations sont retournées à partir du champ d’enregistrement SCALE de l’IRD.
SQL_DESC_SCHEMA_NAME (ODBC 2.0)	CharacterAttributePtr	Schéma de la table qui contient la colonne. La valeur retournée est définie par l’implémentation si la colonne est une expression ou si la colonne fait partie d’une vue. Si la source de données ne prend pas en charge les schémas ou si le nom du schéma ne peut pas être déterminé, une chaîne vide est retournée. Ce champ d’enregistrement VARCHAR n’est pas limité à 128 caractères.
SQL_DESC_SEARCHABLE (ODBC 1.0)	NumericAttributePtr	SQL_PRED_NONE si la colonne ne peut pas être utilisée dans une clause WHERE. (Il s’agit de la même valeur que la valeur SQL_UNSEARCHABLE dans ODBC 2.x.) SQL_PRED_CHAR si la colonne peut être utilisée dans une clause WHERE, mais uniquement avec le prédicat LIKE. (Il s’agit de la même valeur que la valeur SQL_LIKE_ONLY dans ODBC 2.x.) SQL_PRED_BASIC si la colonne peut être utilisée dans une clause WHERE avec tous les opérateurs de comparaison, sauf LIKE. (Il s’agit de la même valeur que la valeur SQL_EXCEPT_LIKE dans ODBC 2.x.) SQL_PRED_SEARCHABLE si la colonne peut être utilisée dans une clause WHERE avec n’importe quel opérateur de comparaison. Les colonnes de type SQL_LONGVARCHAR et SQL_LONGVARBINARY retournent généralement SQL_PRED_CHAR.
SQL_DESC_TABLE_NAME (ODBC 2.0)	CharacterAttributePtr	Nom de la table qui contient la colonne. La valeur retournée est définie par l’implémentation si la colonne est une expression ou si la colonne fait partie d’une vue. Si le nom de la table ne peut pas être déterminé, une chaîne vide est retournée.
SQL_DESC_TYPE (ODBC 3.0)	NumericAttributePtr	Valeur numérique qui spécifie le type de données SQL. Lorsque ColumnNumber est égal à 0, SQL_BINARY est retourné pour les signets de longueur variable et SQL_INTEGER est retourné pour les signets de longueur fixe. Pour les types de données datetime et intervalle, ce champ retourne le type de données détaillé : SQL_DATETIME ou SQL_INTERVAL. (Pour plus d’informations, consultez Identificateurs et de descripteurs de type de données dans l’annexe D : types de données. Ces informations sont retournées à partir du champ d’enregistrement SQL_DESC_TYPE de l’IRD. Remarque : Pour travailler sur ODBC 2.x pilotes, utilisez SQL_DESC_CONCISE_TYPE à la place.
SQL_DESC_TYPE_NAME (ODBC 1.0)	CharacterAttributePtr	Nom du type de données dépendant de la source de données ; par exemple, « CHAR », « VARCHAR », « MONEY », « LONG VARBINARY » ou « CHAR ( ) FOR BIT DATA ». Si le type est inconnu, une chaîne vide est retournée.
SQL_DESC_UNNAMED (ODBC 3.0)	NumericAttributePtr	SQL_NAMED ou SQL_UNNAMED. Si le champ SQL_DESC_NAME de l’IRD contient un alias de colonne ou un nom de colonne, SQL_NAMED est retourné. S’il n’existe aucun nom de colonne ou alias de colonne, SQL_UNNAMED est retourné. Ces informations sont retournées à partir du champ d’enregistrement SQL_DESC_UNNAMED de l’IRD.
SQL_DESC_UNSIGNED (ODBC 1.0)	NumericAttributePtr	SQL_TRUE si la colonne n’est pas signée (ou non numérique). SQL_FALSE si la colonne est signée.
SQL_DESC_UPDATABLE (ODBC 1.0)	NumericAttributePtr	La colonne est décrite par les valeurs des constantes définies : SQL_ATTR_READONLY SQL_ATTR_WRITE SQL_ATTR_READWRITE_UNKNOWN SQL_DESC_UPDATABLE décrit la mise à jour de la colonne dans le jeu de résultats, et non la colonne de la table de base. La mise à jour de la colonne de base sur laquelle la colonne du jeu de résultats est basée peut être différente de la valeur de ce champ. Si une colonne est pouvant être mise à jour peut être basée sur le type de données, les privilèges utilisateur et la définition du jeu de résultats lui-même. S’il n’est pas clair si une colonne est pouvant être mise à jour, SQL_ATTR_READWRITE_UNKNOWN doit être retournée.

SQLColAttribute est une alternative extensible à SQLDescribeCol. SQLDescribeCol retourne un ensemble fixe d’informations de descripteur basées sur ANSI-89 SQL. SQLColAttribute permet d’accéder à l’ensemble plus complet d’informations de descripteur disponibles dans les extensions de fournisseur ANSI SQL-92 et SGBD.

Pour plus d’informations sur	Consultez
Liaison d’une mémoire tampon à une colonne dans un jeu de résultats	SQLBindCol, fonction
Annulation du traitement des instructions	SQLCancel, fonction
Retour d’informations sur une colonne dans un jeu de résultats	SQLDescribeCol, fonction
Extraction d’un bloc de données ou défilement d’un jeu de résultats	SQLFetchScroll, fonction
Extraction de plusieurs lignes de données	SQLFetch, fonction

Exemple

L’exemple de code suivant ne libère pas de handles et de connexions. Consultez la fonction SQLFreeHandle, l’exemple de programme ODBC et la fonction SQLFreeStmt pour obtenir des exemples de code pour libérer des handles et des instructions.

// SQLColAttibute.cpp  
// compile with: user32.lib odbc32.lib  
  
#define UNICODE  
  
#include <windows.h>  
#include <sqlext.h>  
#include <strsafe.h>  
  
struct DataBinding {  
   SQLSMALLINT TargetType;  
   SQLPOINTER TargetValuePtr;  
   SQLINTEGER BufferLength;  
   SQLLEN StrLen_or_Ind;  
};  
  
void printStatementResult(SQLHSTMT hstmt) {  
   int bufferSize = 1024, i;  
   SQLRETURN retCode;  
   SQLSMALLINT numColumn = 0, bufferLenUsed;
   
   retCode = SQLNumResultCols(hstmt, &numColumn);  
   
   SQLPOINTER* columnLabels = (SQLPOINTER *)malloc( numColumn * sizeof(SQLPOINTER*) );  
   struct DataBinding* columnData = (struct DataBinding*)malloc( numColumn * sizeof(struct DataBinding) );  
  
   printf( "Columns from that table:\n" );  
   for ( i = 0 ; i < numColumn ; i++ ) {  
      columnLabels[i] = (SQLPOINTER)malloc( bufferSize*sizeof(char) );  
  
      retCode = SQLColAttribute(hstmt, (SQLUSMALLINT)i + 1, SQL_DESC_LABEL, columnLabels[i], (SQLSMALLINT)bufferSize, &bufferLenUsed, NULL);  
      wprintf( L"Column %d: %s\n", i, (wchar_t*)columnLabels[i] );  
   }  
  
   // allocate memory for the binding  
   for ( i = 0 ; i < numColumn ; i++ ) {  
      columnData[i].TargetType = SQL_C_CHAR;  
      columnData[i].BufferLength = (bufferSize+1);  
      columnData[i].TargetValuePtr = malloc( sizeof(unsigned char)*columnData[i].BufferLength );  
   }  
  
   // setup the binding   
   for ( i = 0 ; i < numColumn ; i++ ) {  
      retCode = SQLBindCol(hstmt, (SQLUSMALLINT)i + 1, columnData[i].TargetType,   
         columnData[i].TargetValuePtr, columnData[i].BufferLength, &(columnData[i].StrLen_or_Ind));  
   }  
  
   printf( "Data from that table:\n" );  
   // fetch the data and print out the data  
   for ( retCode = SQLFetch(hstmt) ; retCode == SQL_SUCCESS || retCode == SQL_SUCCESS_WITH_INFO ; retCode = SQLFetch(hstmt) ) {  
      int j;  
      for ( j = 0 ; j < numColumn ; j++ )  
         wprintf( L"%s: %hs\n", columnLabels[j], columnData[j].TargetValuePtr );  
      printf( "\n" );  
   }  
   printf( "\n" );   
}  
  
int main() {  
   int bufferSize = 1024, i, count = 1, numCols = 5;  
   wchar_t firstTableName[1024], * dbName = (wchar_t *)malloc( sizeof(wchar_t)*bufferSize ), * userName = (wchar_t *)malloc( sizeof(wchar_t)*bufferSize );  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
   SQLWCHAR connStrbuffer[1024];  
   SQLSMALLINT connStrBufferLen, bufferLen;  
   SQLRETURN retCode;  
  
   SQLHENV henv = NULL;   // Environment     
   SQLHDBC hdbc = NULL;   // Connection handle  
   SQLHSTMT hstmt = NULL;   // Statement handle  
  
   struct DataBinding* catalogResult = (struct DataBinding*) malloc( numCols * sizeof(struct DataBinding) );  
   SQLWCHAR* selectAllQuery = (SQLWCHAR *)malloc( sizeof(SQLWCHAR) * bufferSize );  
  
   // connect to database  
   retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLCHAR *)(void*)SQL_OV_ODBC3, -1);  
   retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
   retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);  
   retCode = SQLDriverConnect(hdbc, desktopHandle, L"Driver={SQL Server}", SQL_NTS, connStrbuffer, 1025, &connStrBufferLen, SQL_DRIVER_PROMPT);  
   retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   // display the database information  
   retCode = SQLGetInfo(hdbc, SQL_DATABASE_NAME, dbName, (SQLSMALLINT)bufferSize, (SQLSMALLINT *)&bufferLen);  
   retCode = SQLGetInfo(hdbc, SQL_USER_NAME, userName, (SQLSMALLINT)bufferSize, &bufferLen);  
  
   for ( i = 0 ; i < numCols ; i++ ) {  
      catalogResult[i].TargetType = SQL_C_CHAR;  
      catalogResult[i].BufferLength = (bufferSize + 1);  
      catalogResult[i].TargetValuePtr = malloc( sizeof(unsigned char)*catalogResult[i].BufferLength );  
   }  
  
   // Set up the binding. This can be used even if the statement is closed by closeStatementHandle  
   for ( i = 0 ; i < numCols ; i++ )  
      retCode = SQLBindCol(hstmt, (SQLUSMALLINT)i + 1, catalogResult[i].TargetType, catalogResult[i].TargetValuePtr, catalogResult[i].BufferLength, &(catalogResult[i].StrLen_or_Ind));  
  
   retCode = SQLTables( hstmt, (SQLWCHAR*)SQL_ALL_CATALOGS, SQL_NTS, L"", SQL_NTS, L"", SQL_NTS, L"", SQL_NTS );  
   retCode = SQLFreeStmt(hstmt, SQL_CLOSE);  
  
   retCode = SQLTables( hstmt, dbName, SQL_NTS, userName, SQL_NTS, L"%", SQL_NTS, L"TABLE", SQL_NTS );  
  
   for ( retCode = SQLFetch(hstmt) ; retCode == SQL_SUCCESS || retCode == SQL_SUCCESS_WITH_INFO ; retCode = SQLFetch(hstmt), ++count )  
      if ( count == 1 )  
         StringCchPrintfW( firstTableName, 1024, L"%hs", catalogResult[2].TargetValuePtr );  
   retCode = SQLFreeStmt(hstmt, SQL_CLOSE);  
  
   wprintf( L"Select all data from the first table (%s)\n", firstTableName );  
   StringCchPrintfW( selectAllQuery, bufferSize, L"SELECT * FROM %s", firstTableName );  
  
   retCode = SQLExecDirect(hstmt, selectAllQuery, SQL_NTS);  
   printStatementResult(hstmt);  
}

Voir aussi

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

Partager via

Fonction SQLColAttribute

Syntaxe

Arguments

Retours

Diagnostics

Commentaires

Compatibilité descendante

Exemple

Voir aussi

Commentaires

Ressources supplémentaires

Partager via

Fonction SQLColAttribute

Syntaxe

Arguments

Retours

Diagnostics

Commentaires

Compatibilité descendante

Fonctions connexes

Exemple

Voir aussi

Commentaires

Ressources supplémentaires