SQLColAttribute
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 SQLColAttribute sur des instructions préparées entraîne un aller-retour à 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 SQLColAttribute après l’achèvement de SQLExecute ou DE SQLExecDirect n’implique pas d’aller-retour de serveur.
Notes
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. |
SQL Server Native Client pilote ODBC utilise l’instruction SET FMTONLY pour réduire la surcharge du serveur lorsqu’il SQLColAttribute est appelé pour des instructions préparées mais non exécutées.
Pour les types à grande valeur, 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 du 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 Select Transact-SQL 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 a introduit des champs de descripteur spécifiques au pilote pour fournir des informations supplémentaires pour indiquer respectivement le nom de la collection de schémas XML, le nom du schéma et le nom du catalogue. 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 a introduit de nouveaux champs descripteurs 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é d’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 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 grands types CLR définis par l'utilisateur. Pour plus d’informations, consultez Grands types de User-Defined CLR (ODBC).
Prise en charge SQLColAttribute pour les colonnes éparses
SQLColAttribute interroge le champ IRD (nouveau descripteur de ligne d’implémentation), SQL_CA_SS_IS_COLUMN_SET, pour déterminer si une colonne est une column_set colonne.
Pour plus d’informations, consultez Prise en charge des colonnes éparses (ODBC).
Voir aussi
Fonction SQLColAttribute
Détails de l’implémentation d’API ODBC
SQLSetStmtAttr