Fonction SQLGetTypeInfo
Conformité
Version introduite : Conformité aux normes ODBC 1.0 : ISO 92
Résumé
SQLGetTypeInfo retourne des informations sur les types de données pris en charge par la source de données. Le pilote retourne les informations sous la forme d’un jeu de résultats SQL. Les types de données sont destinés à être utilisés dans les instructions DDL (Data Definition Language).
Important
Les applications doivent utiliser les noms de type retournés dans la colonne TYPE_NAME du jeu de résultats SQLGetTypeInfo dans les instructions ALTER TABLE et CREATE TABLE . SQLGetTypeInfo peut renvoyer plusieurs lignes avec la même valeur dans la colonne DATA_TYPE.
Syntaxe
SQLRETURN SQLGetTypeInfo(
SQLHSTMT StatementHandle,
SQLSMALLINT DataType);
Arguments
StatementHandle
[Entrée] Handle d’instruction pour le jeu de résultats.
DataType
[Entrée] Type de données SQL. Il doit s’agir de l’une des valeurs de la section Types de données SQL de l’Annexe D : Types de données ou type de données SQL spécifique au pilote. SQL_ALL_TYPES spécifie que les informations relatives à tous les types de données doivent être retournées.
Retours
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnostics
Lorsque SQLGetTypeInfo 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 SQLGetTypeInfo et explique chacune d’elles dans le contexte de cette fonction ; la notation « (DM) » précède les descriptions des 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.) |
| 01S02 | Valeur d’option modifiée | Un attribut d’instruction spécifié n’était pas valide en raison de conditions de travail d’implémentation. Par conséquent, une valeur similaire a été temporairement remplacée. (Appel SQLGetStmtAttr pour déterminer la valeur temporairement substituée.) La valeur de remplacement est valide pour l’InstructionHandle jusqu’à ce que le curseur soit fermé. Les attributs d’instruction qui peuvent être modifiés sont les suivants : SQL_ATTR_CONCURRENCY, SQL_ATTR_CURSOR_TYPE, SQL_ATTR_KEYSET_SIZE, SQL_ATTR_MAX_LENGTH, SQL_ATTR_MAX_ROWS, SQL_ATTR_QUERY_TIMEOUT et SQL_ATTR_SIMULATE_CURSOR. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Échec du lien de communication | Le lien de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant l’achèvement du traitement de la fonction. |
| 24 000 | État de curseur non valide | Un curseur a été ouvert sur StatementHandle, et SQLFetch ou SQLFetchScroll avait été appelé. Cette erreur est retournée par le Gestionnaire de pilotes si SQLFetch ou SQLFetchScroll n’a pas retourné SQL_NO_DATA et est retournée par le pilote si SQLFetch ou SQLFetchScroll a retourné SQL_NO_DATA. Un jeu de résultats a été ouvert sur StatementHandle, mais SQLFetch ou SQLFetchScroll n’avait pas été appelé. |
| 40001 | Échec de sérialisation | La transaction a été restaurée en raison d’un interblocage de ressources avec une autre transaction. |
| 40003 | Saisie semi-automatique de l’instruction inconnue | La connexion associée a échoué pendant l’exécution de cette fonction et l’état de la transaction ne peut pas être déterminé. |
| 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 SQLGetDiagRec dans la mémoire tampon *MessageText 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. |
| HY004 | Type de données SQL non valide | La valeur spécifiée pour l’argument DataType n’était ni un identificateur de type de données ODBC SQL valide ni un identificateur de type de données spécifique au pilote pris en charge par le pilote. |
| HY008 | Opération annulée | Le traitement asynchrone a été activé pour l’instruction StatementHandle, puis la fonction a été appelée et, avant qu’elle ait terminé l’exécution, 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 la fonction SQLGetTypeInfo a été appelée. (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) 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. |
| 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 | Fonctionnalité facultative non implémentée | La combinaison des paramètres actuels des attributs d’instruction SQL_ATTR_CONCURRENCY et SQL_ATTR_CURSOR_TYPE n’a pas été prise en charge par le pilote ou la source de données. L’attribut d’instruction SQL_ATTR_USE_BOOKMARKS a été défini sur SQL_UB_VARIABLE, et l’attribut d’instruction SQL_ATTR_CURSOR_TYPE a été défini sur un type de curseur pour lequel le pilote ne prend pas en charge les signets. |
| HYT00 | Délai expiré | La période d’expiration de la requête a expiré avant que la source de données ne retourne le jeu de résultats. La période d’expiration est définie via SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| 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 correspondant à 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. |
Commentaires
SQLGetTypeInfo retourne les résultats sous la forme d’un jeu de résultats standard, classés par DATA_TYPE, puis en fonction du niveau de correspondance du type de données ODBC SQL correspondant. Les types de données définis par la source de données sont prioritaires sur les types de données définis par l’utilisateur. Par conséquent, l’ordre de tri n’est pas nécessairement cohérent, mais peut être généralisé comme DATA_TYPE d’abord, suivi de TYPE_NAME, les deux croissants. Par exemple, supposons qu’une source de données a défini des types de données INTEGER et COUNTER, où COUNTER est incrémenté automatiquement, et qu’un type de données défini par l’utilisateur WHOLENUM a également été défini. Ceux-ci sont retournés dans l’ordre ENTIER, WHOLENUM et COUNTER, car WHOLENUM est mappé étroitement au type de données ODBC SQL SQL_INTEGER, tandis que le type de données incrémentant automatiquement, même si pris en charge par la source de données, ne correspond pas étroitement à un type de données ODBC SQL. Pour plus d’informations sur l’utilisation de ces informations, consultez les instructions DDL.
Si l’argument DataType spécifie un type de données valide pour la version d’ODBC prise en charge par le pilote, mais n’est pas pris en charge par le pilote, il retourne un jeu de résultats vide.
Remarque
Pour plus d’informations sur l’utilisation générale, les arguments et les données retournées des fonctions de catalogue ODBC, consultez Fonctions de catalogue.
Les colonnes suivantes ont été renommées pour ODBC 3.x. Les modifications de nom de colonne n’affectent pas la compatibilité descendante, car les applications sont liées par numéro de colonne.
| Colonne ODBC 2.0 | ODBC 3.colonne x |
|---|---|
| PRECISION | COLUMN_SIZE |
| MONEY | FIXED_PREC_SCALE |
| AUTO_INCREMENT | AUTO_UNIQUE_VALUE |
Les colonnes suivantes ont été ajoutées au jeu de résultats retourné par SQLGetTypeInfo pour ODBC 3.x :
SQL_DATA_TYPE
INTERVAL_PRECISION
SQL_DATETIME_SUB
NUM_PREC_RADIX
Le tableau suivant répertorie les colonnes du jeu de résultats. Des colonnes supplémentaires au-delà de la colonne 19 (INTERVAL_PRECISION) peuvent être définies par le pilote. Une application doit accéder à des colonnes spécifiques au pilote en comptant à partir de la fin du jeu de résultats plutôt que de spécifier une position ordinale explicite. Pour plus d’informations, consultez Données retournées par les fonctions de catalogue.
Remarque
SQLGetTypeInfo peut ne pas renvoyer tous les types de données. Par exemple, un pilote peut ne pas retourner de types de données définis par l’utilisateur. Les applications peuvent utiliser n’importe quel type de données valide, qu’elles soient retournées par SQLGetTypeInfo. Les types de données retournés par SQLGetTypeInfo sont ceux pris en charge par la source de données. Elles sont destinées à être utilisées dans les instructions DDL (Data Definition Language). Les pilotes peuvent retourner des données de jeu de résultats à l’aide de types de données autres que les types retournés par SQLGetTypeInfo. Lors de la création du jeu de résultats pour une fonction de catalogue, le pilote peut utiliser un type de données qui n’est pas pris en charge par la source de données.
| Nom de la colonne | Colonne nombre |
Type de données | Commentaires |
|---|---|---|---|
| TYPE_NAME (ODBC 2.0) | 1 | Varchar non NULL | 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 ». Les applications doivent utiliser ce nom dans les instructions CREATE TABLE et ALTER TABLE . |
| DATA_TYPE (ODBC 2.0) | 2 | Smallint non NULL | Type de données SQL. Il peut s’agir d’un type de données SQL ODBC ou d’un type de données SQL spécifique au pilote. Pour les types de données datetime ou intervalle, cette colonne retourne le type de données concis (par exemple, SQL_TYPE_TIME ou SQL_INTERVAL_YEAR_TO_MONTH). Pour obtenir la liste des types de données ODBC SQL valides, consultez l’annexe D : Types de données SQL. Pour plus d’informations sur les types de données SQL spécifiques au pilote, consultez la documentation du pilote. |
| COLUMN_SIZE (ODBC 2.0) | 3 | Integer | Taille maximale de colonne prise en charge par le serveur pour ce type de données. Pour les données numériques, il s’agit de la précision maximale. Pour les données de chaîne, il s’agit de la longueur en caractères. Pour les types de données datetime, il s’agit de la longueur en caractères de la représentation sous forme de chaîne (en supposant la précision maximale autorisée du composant fraction de secondes). NULL est retourné pour les types de données où la taille de colonne n’est pas applicable. Pour les types de données d’intervalle, il s’agit du nombre de caractères dans la représentation de caractère du littéral d’intervalle (tel que défini par la précision de début de l’intervalle ; consultez La longueur du type de données d’intervalle dans l’annexe D : Types de données). Pour plus d’informations sur la taille des colonnes, consultez Taille de colonne, Chiffres décimaux, Longueur des octets de transfert et Taille d’affichage dans l’annexe D : Types de données. |
| LITERAL_PREFIX (ODBC 2.0) | 4 | Varchar | Caractère ou caractères utilisés pour préfixer un littéral ; par exemple, un guillemet unique (') pour les types de données caractères ou 0x pour les types de données binaires ; NULL est retourné pour les types de données où un préfixe littéral n’est pas applicable. |
| LITERAL_SUFFIX (ODBC 2.0) | 5 | Varchar | Caractère ou caractères utilisés pour mettre fin à un littéral ; par exemple, un guillemet unique (') pour les types de données caractères ; NULL est retourné pour les types de données où un suffixe littéral n’est pas applicable. |
| CREATE_PARAMS (ODBC 2.0) | 6 | Varchar | Liste de mots clés, séparés par des virgules, correspondant à chaque paramètre que l’application peut spécifier entre parenthèses lors de l’utilisation du nom retourné dans le champ TYPE_NAME. Les mots clés de la liste peuvent être l’un des éléments suivants : longueur, précision ou échelle. Ils apparaissent dans l’ordre dans lequel la syntaxe exige qu’elles soient utilisées. Par exemple, CREATE_PARAMS pour DECIMAL serait « précision, échelle » ; CREATE_PARAMS pour VARCHAR équivaut à « length ». NULL est retourné s’il n’existe aucun paramètre pour la définition du type de données ; par exemple, INTEGER. Le pilote fournit le texte CREATE_PARAMS dans la langue du pays/de la région où il est utilisé. |
| NULLABLE (ODBC 2.0) | 7 | Smallint non NULL | Indique si le type de données accepte une valeur NULL : SQL_NO_NULLS si le type de données n’accepte pas les valeurs NULL. SQL_NULLABLE si le type de données accepte des valeurs NULL. SQL_NULLABLE_UNKNOWN s’il n’est pas connu si la colonne accepte les valeurs NULL. |
| CASE_SENSITIVE (ODBC 2.0) | 8 | Smallint non NULL | Indique si un type de données caractère respecte la casse dans les classements et les comparaisons : SQL_TRUE si le type de données est un type de données caractère et respecte la casse. SQL_FALSE si le type de données n’est pas un type de données caractère ou n’est pas sensible à la casse. |
| SEARCHABLE (ODBC 2.0) | 9 | Smallint non NULL | Utilisation du type de données dans une clause WHERE : 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 (comparaison, comparaison quantifiée, BETWEEN, DISTINCT, IN, MATCH et UNIQUE). (Il s’agit de la même valeur que la valeur SQL_ALL_EXCEPT_LIKE dans ODBC 2.x.) SQL_SEARCHABLE si la colonne peut être utilisée dans une clause WHERE avec n’importe quel opérateur de comparaison. |
| UNSIGNED_ATTRIBUTE (ODBC 2.0) | 10 | Smallint | Indique si le type de données n’est pas signé : SQL_TRUE si le type de données n’est pas signé. SQL_FALSE si le type de données est signé. NULL est retourné si l’attribut n’est pas applicable au type de données ou si le type de données n’est pas numérique. |
| FIXED_PREC_SCALE (ODBC 2.0) | 11 | Smallint non NULL | Indique si le type de données a prédéfini une précision fixe et une échelle (qui sont spécifiques à la source de données), comme un type de données money : SQL_TRUE si elle a prédéfini une précision et une échelle fixes. SQL_FALSE s’il n’a pas de précision et d’échelle fixe prédéfinies. |
| AUTO_UNIQUE_VALUE (ODBC 2.0) | 12 | Smallint | Indique si le type de données est en cours de création automatique : SQL_TRUE si le type de données est en cours de création automatique. SQL_FALSE si le type de données n’est pas en cours de création automatique. NULL est retourné si l’attribut n’est pas applicable au type de données ou si le type de données n’est pas numérique. Une application peut insérer des valeurs dans une colonne ayant cet attribut, mais ne peut généralement pas mettre à jour les valeurs dans la colonne. Lorsqu’une insertion est effectuée dans une colonne incrémentée automatiquement, 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’incrémentation automatique commence à un point particulier ou incrémente par une valeur particulière. |
| LOCAL_TYPE_NAME (ODBC 2.0) | 13 | Varchar | Version localisée du nom de type de données dépendant de la source de données. La valeur NULL est retournée si un nom localisé n'est pas pris en charge par la source de données. Ce nom est destiné uniquement à l’affichage, par exemple dans les boîtes de dialogue. |
| MINIMUM_SCALE (ODBC 2.0) | 14 | Smallint | Échelle minimale du type de données sur la source de données. Si un type de données possède une échelle fixe, les colonnes MINIMUM_SCALE et MAXIMUM_SCALE contiennent toutes les deux cette valeur. Par exemple, une colonne SQL_TYPE_TIMESTAMP peut avoir une échelle fixe pendant des fractions de seconde. La valeur NULL est retournée lorsque l'échelle n'est pas applicable. Pour plus d’informations, 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. |
| MAXIMUM_SCALE (ODBC 2.0) | 15 | Smallint | Échelle maximale du type de données sur la source de données. La valeur NULL est retournée lorsque l'échelle n'est pas applicable. Si l’échelle maximale n’est pas définie séparément sur la source de données, mais qu’elle est définie pour être identique à la précision maximale, cette colonne contient la même valeur que la colonne COLUMN_SIZE. Pour plus d’informations, 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_DATA_TYPE (ODBC 3.0) | 16 | Smallint NOT NULL | Valeur du type de données SQL tel qu’il apparaît dans le champ SQL_DESC_TYPE du descripteur. Cette colonne est identique à la colonne DATA_TYPE, à l’exception des types de données interval et datetime. Pour les types de données interval et datetime, le champ SQL_DATA_TYPE dans le jeu de résultats retourne SQL_INTERVAL ou SQL_DATETIME, et le champ SQL_DATETIME_SUB retourne le sous-code pour l’intervalle ou le type de données datetime spécifique. (Voir Annexe D : Types de données.) |
| SQL_DATETIME_SUB (ODBC 3.0) | 17 | Smallint | Lorsque la valeur de SQL_DATA_TYPE est SQL_DATETIME ou SQL_INTERVAL, cette colonne contient le sous-code datetime/interval. Pour les types de données autres que datetime et intervalle, ce champ a la valeur NULL. Pour les types de données interval ou datetime, le champ SQL_DATA_TYPE dans le jeu de résultats retourne SQL_INTERVAL ou SQL_DATETIME, et le champ SQL_DATETIME_SUB retourne le sous-code pour le type de données date/heure spécifique. (Voir Annexe D : Types de données.) |
| NUM_PREC_RADIX (ODBC 3.0) | 18 | Integer | Si le type de données est un type numérique approximatif, cette colonne contient la valeur 2 pour indiquer que COLUMN_SIZE spécifie un certain nombre de bits. Pour les types numériques exacts, cette colonne contient la valeur 10 pour indiquer que COLUMN_SIZE spécifie un nombre de chiffres décimaux. Sinon, cette colonne est NULL. |
| INTERVAL_PRECISION (ODBC 3.0) | 19 | Smallint | Si le type de données est un type de données d’intervalle, cette colonne contient la valeur de la précision de début de l’intervalle. (Voir Précision du type de données d’intervalle dans l’annexe D : Types de données.) Sinon, cette colonne a la valeur NULL. |
Les informations d’attribut peuvent s’appliquer aux types de données ou à des colonnes spécifiques dans un jeu de résultats. SQLGetTypeInfo retourne des informations sur les attributs associés aux types de données ; SQLColAttribute retourne des informations sur les attributs associés aux colonnes dans un jeu de résultats.
Fonctions connexes
| 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 | SQLColAttribute, fonction |
| Extraction d’un bloc de données ou défilement d’un jeu de résultats | SQLFetchScroll, fonction |
| Extraction d’une seule ligne ou d’un bloc de données dans une direction vers l’avant uniquement | SQLFetch, fonction |
| Retour d’informations sur un pilote ou une source de données | SQLGetInfo, fonction |
Voir aussi
Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC