Fonction SQLColAttribute
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.
Notes
Pour plus d’informations sur ce à quoi le Gestionnaire de pilotes mappe cette fonction lorsqu’un odbc 3. L’application x fonctionne avec odbc 2. x pilote, consultez Mappage des fonctions de remplacement 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 de champ doit être récupérée. Cet argument correspond au nombre de colonnes des données de résultat, ordonnées séquentiellement dans l’ordre croissant des colonnes, à partir de 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 à l’exception de 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 de l’IRD qui doit être interrogé (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’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 CharacterAttributePtr.
BufferLength
[Entrée] Si FieldIdentifier est un champ défini par ODBC et que 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 que *CharacterAttributePtr est un entier, ce champ est ignoré. Si * 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 au 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 correspond à 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’exclusion de l’octet de terminaison null pour les données de caractères) disponibles pour retourner dans *CharacterAttributePtr.
Pour les données de caractère, si le nombre d’octets disponibles à retourner est supérieur ou égal à BufferLength, les informations de descripteur dans *CharacterAttributePtr sont tronquées en BufferLength moins la longueur d’un caractère de terminaison 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 uniquement écrire les 32 bits ou 16 bits inférieurs d’une mémoire tampon et laisser le bit d’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 of StatementHandle. 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 | 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 *CharacterAttributePtr n’étant pas assez grande pour renvoyer la valeur de chaîne entière, la valeur de chaîne a été tronquée. La longueur de la valeur de chaîne non structurée est retournée dans *StringLengthPtr. (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 et FieldIdentifier n’a pas été SQL_DESC_COUNT. Il n’y avait aucune colonne à 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 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 SQLGetDiagField à partir de la structure de 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 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 aynchronous é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 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) La fonction a été appelée avant d’appeler SQLPrepare, SQLExecDirect ou une fonction de catalogue pour l’InstructionHandle. (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) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour l’InstructionHandle et a renvoyé 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 consultés, peut-être en raison de conditions de mémoire insuffisantes. |
| HY090 | Chaîne ou longueur de mémoire tampon non valide | (DM) *CharacterAttributePtr est une chaîne de caractères, et BufferLength était 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 Fonction SQLEndTran. |
| HYC00 | Pilote non compatible | La valeur spécifiée pour l’argument FieldIdentifier n’était pas prise en charge par le pilote. |
| 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. |
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 à l’InstructionHandle.
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 à partir des champs de descripteur de l’IRD. La fonction est appelée avec un handle d’instruction plutôt qu’un handle de 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 présentés plus loin dans cette section ; d’autres types de descripteurs peuvent être définis par les pilotes pour tirer parti de différentes sources de données.
Odbc 3. Le pilote x doit retourner une valeur pour chacun des champs de descripteur. Si un champ de 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.
Backward Compatibility
ODBC 3. La fonction x SQLColAttribute remplace le odbc 2 déprécié. fonction xSQLColAttributes. Lors du mappage de SQLColAttributes à SQLColAttribute (lors d’un odbc 2. L’application x fonctionne avec odbc 3. pilote x ) ou le mappage de SQLColAttribute à SQLColAttributes (quand odbc 3 est utilisé. L’application x fonctionne avec odbc 2. pilote x ), le Gestionnaire de pilotes passe la valeur de FieldIdentifier , la mappe à une nouvelle valeur ou retourne une erreur, comme suit :
Notes
Préfixe utilisé dans les valeurs FieldIdentifier dans ODBC 3. x a été modifié de celui utilisé dans ODBC 2. x. Le nouveau préfixe est « SQL_DESC » ; l’ancien préfixe était « SQL_COLUMN ».
Si le #define valeur d’ODBC 2. xFieldIdentifier est identique à la valeur #define d’ODBC 3. xFieldIdentifier, la valeur dans l’appel de fonction est simplement transmise.
Valeurs #define d’ODBC 2. xFieldIdentifiers SQL_COLUMN_LENGTH, SQL_COLUMN_PRECISION et SQL_COLUMN_SCALE sont différents des valeurs #define d’ODBC 3. xFieldIdentifiers SQL_DESC_PRECISION, SQL_DESC_SCALE et SQL_DESC_LENGTH. Odbc 2. Le pilote x doit uniquement 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 que dans ODBC 2. x. Pour plus d’informations, consultez Taille de colonne, Chiffres décimaux, Longueur des octets de transfert et Taille d’affichage.
Si le #define valeur d’ODBC 2. xFieldIdentifier est différent de la valeur #define d’ODBC 3. xFieldIdentifier, comme cela se produit avec les valeurs COUNT, NAME et NULLABLE, la valeur dans l’appel de fonction est mappée à la valeur correspondante. Par exemple, SQL_COLUMN_COUNT est mappée à SQL_DESC_COUNT, et SQL_DESC_COUNT est mappée à SQL_COLUMN_COUNT, en fonction de 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, elle ne sera pas mappée quand ODBC 3. L’application x l’utilise dans un appel à SQLColAttribute dans odbc 2. pilote x , et l’appel retourne SQLSTATE HY091 (identificateur de champ de descripteur non valide).
Le tableau suivant répertorie les types de descripteurs 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 si elle 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 de la colonne. Lorsqu’une insertion est effectuée dans une colonne d’insertion 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 d’auto-incrémentation démarre à un point particulier ou s’incrémente d’une valeur particulière. |
| SQL_DESC_BASE_COLUMN_NAME (ODBC 3.0) | CharacterAttributePtr | Nom de la colonne de base pour 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 respectant la casse pour les classements et les comparaisons. SQL_FALSE si la colonne n’est pas traitée comme respectant la casse pour les classements et les comparaisons, ou si elle n’est pas un caractère caractère. |
| 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 interval, 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 types 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. Cette opération retourne 0 s’il n’y a pas de colonnes 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 de transfert d’octet 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 n’a pas une précision fixe et une échelle différente de zéro qui sont spécifiques à la source de données. |
| SQL_DESC_LABEL (ODBC 2.0) | CharacterAttributePtr | Étiquette ou titre de colonne. Par exemple, une colonne nommée EmpName peut être étiquetée Nom d’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 sans nom, une chaîne vide est retournée. |
| SQL_DESC_LENGTH (ODBC 3.0) | NumericAttributePtr | Valeur numérique qui correspond à 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 pour 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 de terminaison 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 Taille de colonne, Chiffres décimaux, Longueur de transfert d’octet et 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 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 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 à des fins d’affichage uniquement. 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 la colonne est retourné. Dans les deux cas, SQL_DESC_UNNAMED est défini 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éfini 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 si l’on ne sait pas 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 la valeur 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 la valeur 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 de caractères de longueur fixe ou binaires, il s’agit de la longueur réelle en octets. Pour les caractères de longueur variable ou les types binaires, il s’agit de la longueur maximale en octets. Cette valeur n’inclut pas la fin null. Ces informations sont retournées à partir du champ d’enregistrement SQL_DESC_OCTET_LENGTH de l’IRD. Pour plus d’informations sur la longueur, consultez Taille de colonne, Chiffres décimaux, Longueur de transfert d’octet et 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 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 est 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 à l’exception de 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 des 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 interval, ce champ retourne le type de données détaillé : SQL_DATETIME ou SQL_INTERVAL. (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_TYPE de l’IRD. Note: Pour utiliser 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’y a pas de nom de colonne ou d’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 possibilité de 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. La mise à jour d’une colonne 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 peut être mise à jour, SQL_ATTR_READWRITE_UNKNOWN doit être retourné. |
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.
Fonctions connexes
| Pour obtenir des informations sur | Consultez |
|---|---|
| Liaison d’une mémoire tampon à une colonne dans un jeu de résultats | Fonction SQLBindCol |
| Annulation du traitement des instructions | SQLCancel, fonction |
| Retour d’informations sur une colonne dans un jeu de résultats | Fonction SQLDescribeCol |
| Extraction d’un bloc de données ou défilement d’un jeu de résultats | Fonction SQLFetchScroll |
| Extraction de plusieurs lignes de données | SQLFetch, fonction |
Exemple
L’exemple de code suivant ne libère pas les handles et les connexions. Consultez Fonction SQLFreeHandle, Exemple de programme ODBC et Fonction SQLFreeStmt pour obtenir des exemples de code permettant de 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
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour