Partager via


SQLColAttribute

S’applique à : SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)

Vous pouvez utiliser SQLColAttribute pour récupérer un attribut d’une colonne de jeu de résultats pour les instructions ODBC préparées ou exécutées. L’appel de SQLColAttribute sur les instructions préparées entraîne un aller-retour vers SQL Server. Le pilote ODBC SQL Server Native Client reçoit les données de colonne du jeu de résultats dans le cadre de l’exécution de l’instruction. Par conséquent, l’appel de SQLColAttribute après l’achèvement de SQLExecute ou DE SQLExecDirect n’implique pas d’aller-retour de serveur.

Remarque

Les attributs d’identificateur de colonne ODBC ne sont pas disponibles sur tous les jeux de résultats SQL Server.

Identificateur de champ Description
SQL_COLUMN_TABLE_NAME Disponible dans des jeux de résultats extraits d'instructions générant des curseurs côté serveur ou sur des instructions SELECT exécutées qui contiennent une clause FOR BROWSE.
SQL_DESC_BASE_COLUMN_NAME Disponible dans des jeux de résultats extraits d'instructions générant des curseurs côté serveur ou sur des instructions SELECT exécutées qui contiennent une clause FOR BROWSE.
SQL_DESC_BASE_TABLE_NAME Disponible dans des jeux de résultats extraits d'instructions générant des curseurs côté serveur ou sur des instructions SELECT exécutées qui contiennent une clause FOR BROWSE.
SQL_DESC_CATALOG_NAME Nom de la base de données. Disponible dans des jeux de résultats extraits d'instructions générant des curseurs côté serveur ou sur des instructions SELECT exécutées qui contiennent une clause FOR BROWSE.
SQL_DESC_LABEL Disponible dans tous les jeux de résultats. La valeur est identique à la valeur du champ SQL_DESC_NAME.

La longueur du champ est nulle uniquement si une colonne est le résultat d'une expression et si l'expression ne comporte aucune étiquette affectée.
SQL_DESC_NAME Disponible dans tous les jeux de résultats. La valeur est identique à celle du champ SQL_DESC_LABEL_NAME.

La longueur du champ est nulle uniquement si une colonne est le résultat d'une expression et si l'expression ne comporte aucune étiquette affectée.
SQL_DESC_SCHEMA_NAME Nom du propriétaire. Disponible dans des jeux de résultats extraits d'instructions générant des curseurs côté serveur ou sur des instructions SELECT exécutées qui contiennent une clause FOR BROWSE.

Disponible uniquement si le nom du propriétaire est spécifié pour la colonne dans l'instruction SELECT.
SQL_DESC_TABLE_NAME Disponible dans des jeux de résultats extraits d'instructions générant des curseurs côté serveur ou sur des instructions SELECT exécutées qui contiennent une clause FOR BROWSE.
SQL_DESC_UNNAMED Valeur SQL_NAMED de toutes les colonnes dans un jeu de résultats sauf si une colonne est le résultat d'une expression qui ne contient aucune étiquette affectée dans le cadre de l'expression. Lorsque SQL_DESC_UNNAMED retourne la valeur SQL_UNNAMED, tous les attributs d'identificateur de colonne ODBC contiennent des chaînes de longueur nulle pour la colonne.

Le pilote ODBC SQL Server Native Client utilise l’instruction SET FMTONLY pour réduire la surcharge du serveur lorsque SQLColAttribute est appelé pour les instructions préparées mais non exécutées.

Pour les types de valeurs volumineuses, SQLColAttribute retourne les valeurs suivantes :

Identificateur de champ Description de la modification
SQL_DESC_DISPLAY_SIZE Nombre maximal de caractères requis pour l'affichage des données à partir de la colonne. Pour les colonnes de type de valeur élevée, la valeur retournée est SQL_SS_LENGTH_UNLIMITED.
SQL_DESC_LENGTH Retourne la longueur réelle de la colonne dans le jeu de résultats. Pour les colonnes de type de valeur élevée, la valeur retournée est SQL_SS_LENGTH_UNLIMITED.
SQL_DESC_OCTET_LENGTH Retourne la longueur maximale d'une colonne de type de valeur élevée. SQL_SS_LENGTH_UNLIMITED est utilisé pour indiquer une taille illimitée.
SQL_DESC_PRECISION Retourne la valeur SQL_SS_LENGTH_UNLIMITED pour les colonnes de type de valeur élevée.
SQL_DESC_TYPE Retourne SQL_VARCHAR, SQL_WVARCHAR et SQL_VARBINARY pour les types de valeur élevée.
SQL_DESC_TYPE_NAME Retourne « varchar », « varbinary » et « nvarchar » pour les types de valeur élevée.

Pour toutes les versions, les attributs de colonne sont signalés uniquement pour le premier jeu de résultats lorsque plusieurs jeux de résultats sont générés par un lot préparé d'instructions SQL.

Les attributs de colonne suivants sont des extensions exposées par le pilote ODBC SQL Server Native Client. Le pilote ODBC SQL Server Native Client retourne toutes les valeurs dans le paramètre NumericAttrPtr . Les valeurs sont retournées en tant qu'éléments SDWORD (long signé) sauf SQL_CA_SS_COMPUTE_BYLIST qui désigne un pointeur vers un tableau WORD.

Identificateur de champ Valeur retournée
SQL_CA_SS_COLUMN_HIDDEN* TRUE si la colonne référencée appartient à une clé primaire masquée et créée afin de prendre en charge une instruction Transact-SQL SELECT contenant la clause FOR BROWSE.
SQL_CA_SS_COLUMN_ID Position ordinale d'une colonne de résultats d'une clause COMPUTE dans l'instruction Transact-SQL SELECT actuelle.
SQL_CA_SS_COLUMN_KEY* TRUE si la colonne référencée appartient à une clé primaire de la ligne et si l'instruction Transact-SQL SELECT contient la clause FOR BROWSE.
SQL_CA_SS_COLUMN_OP Entier spécifiant l'opérateur d'agrégation responsable de la valeur d'une colonne de la clause COMPUTE. Les définitions des valeurs entières sont disponibles dans sqlncli.h.
SQL_CA_SS_COLUMN_ORDER Position ordinale de la colonne dans une clause ORDER BY d'une instruction ODBC ou Transact-SQL SELECT.
SQL_CA_SS_COLUMN_SIZE Longueur maximale (en octets) requise pour lier une valeur de données extraite de la colonne à une variable SQL_C_BINARY.
SQL_CA_SS_COLUMN_SSTYPE Type de données natif des données stockées dans la colonne SQL Server. Les définitions des valeurs de type sont disponibles dans sqlncli.h.
SQL_CA_SS_COLUMN_UTYPE Type de données de base du type de données défini par l'utilisateur de la colonne SQL Server. Les définitions des valeurs de type sont disponibles dans sqlncli.h.
SQL_CA_SS_COLUMN_VARYLEN TRUE si la longueur des données de la colonne est variable, FALSE sinon.
SQL_CA_SS_COMPUTE_BYLIST Pointeur vers un tableau WORD (court non signé) spécifiant les colonnes employées dans l'expression BY d'une clause COMPUTE. Si la clause COMPUTE ne spécifie aucune expression BY, un pointeur NULL est retourné.

Le premier élément du tableau contient le nombre de colonnes dans la liste BY. Les éléments supplémentaires correspondent aux nombres de colonnes.
SQL_CA_SS_COMPUTE_ID computeid d’une ligne qui est le résultat d’une clause COMPUTE dans l’instruction Transact-SQL SELECT actuelle.
SQL_CA_SS_NUM_COMPUTES Nombre de clauses COMPUTE spécifiées dans l'instruction SELECT Transact-SQL actuelle.
SQL_CA_SS_NUM_ORDERS Nombre de colonnes spécifiées dans une clause ORDER BY d'une instruction Transact-SQL SELECT.

* Disponible si l’attribut d’instruction SQL_SOPT_SS_HIDDEN_COLUMNS est défini sur SQL_HC_ON.

SQL Server 2005 (9.x) a introduit des champs de descripteur spécifiques au pilote pour fournir des informations supplémentaires pour indiquer le nom de la collection de schémas XML, le nom du schéma et le nom du catalogue, respectivement. Ces propriétés ne nécessitent pas l'usage de guillemets ou d'un caractère d'échappement si elles contiennent des caractères non alphanumériques. Le tableau suivant répertorie ces nouveaux champs de descripteur :

Nom de la colonne Type Description
SQL_CA_SS_XML_SCHEMACOLLECTION_CATALOG_NAME CharacterAttributePtr Nom du catalogue dans lequel un nom de collection de schémas XML est défini. Si le nom du catalogue est introuvable, cette variable contient une chaîne vide.

Ces informations sont retournées à partir du champ d'enregistrement SQL_DESC_SS_XML_SCHEMACOLLECTION_CATALOG_NAME de l'IRD qui est un champ en lecture-écriture.
SQL_CA_SS_XML_SCHEMACOLLECTION_SCHEMA_NAM E CharacterAttributePtr Nom du schéma dans lequel un nom de collection de schémas XML est défini. Si le nom du schéma est introuvable, cette variable contient une chaîne vide.

Ces informations sont retournées à partir du champ d'enregistrement SQL_DESC_SS_XML_SCHEMACOLLECTION_SCHEMA_NAME du champ de descripteur de ligne d'implémentation (IRD) en lecture-écriture.
SQL_CA_SS_XML_SCHEMACOLLECTION_NAME CharacterAttributePtr Nom d'une collection de schémas XML. Si le nom est introuvable, cette variable contient une chaîne vide.

Ces informations sont retournées à partir du champ d'enregistrement SQL_DESC_SS_XML_SCHEMACOLLECTION_NAME du champ de descripteur de ligne d'implémentation (IRD) en lecture-écriture.

En outre, SQL Server 2005 (9.x) a introduit de nouveaux champs de descripteur spécifiques au pilote pour fournir des informations supplémentaires pour une colonne de type défini par l’utilisateur (UDT) d’un jeu de résultats ou un paramètre UDT d’une procédure stockée ou d’une requête paramétrable. Ces propriétés ne nécessitent pas l'usage de guillemets ou d'un caractère d'échappement si elles contiennent des caractères non alphanumériques. Le tableau suivant répertorie ces nouveaux champs de descripteur :

Nom de la colonne Type Description
SQL_CA_SS_UDT_CATALOG_NAME CharacterAttributePtr Nom du catalogue contenant le type défini par l'utilisateur (UDT).
SQL_CA_SS_UDT_SCHEMA_NAME CharacterAttributePtr Nom du schéma contenant l’UDT.
SQL_CA_SS_UDT_TYPE_NAME CharacterAttributePtr Nom de l’UDT.
SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME CharacterAttributePtr Nom qualifié de l’assembly de l’UDT.

L'identificateur du champ de descripteur SQL_DESC_TYPE_NAME existant est utilisé pour indiquer le nom de l'UDT. Le champ SQL_DESC_TYPE pour une colonne de type défini par l'utilisateur (UDT) est SQL_SS_UDT.

Prise en charge de la fonction SQLColAttribute pour les fonctionnalités de date et heure améliorées

Pour connaître les valeurs retournées pour les types date/heure, consultez la section « Informations retournées dans les champs IRD » dans Les métadonnées de paramètre et de résultat.

Pour plus d’informations, consultez Améliorations de date et d’heure (ODBC).

Prise en charge SQLColAttribute pour les types CLR volumineux définis par l'utilisateur

SQLColAttribute prend en charge les types clR définis par l’utilisateur (UDT). Pour plus d’informations, consultez Les types CLR définis par l’utilisateur (ODBC) volumineux.

Prise en charge SQLColAttribute pour les colonnes éparses

SQLColAttribute interroge le nouveau champ de descripteur de ligne d’implémentation (IRD), SQL_CA_SS_IS_COLUMN_SET, pour déterminer si une colonne est une colonne column_set .

Pour plus d’informations, consultez La prise en charge des colonnes éparses (ODBC).

Voir aussi

SQLColAttribute, fonction
Détails de l’implémentation d’API ODBC
SQLSetStmtAttr