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 retourner 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 d’un type de données SQL spécifique au pilote. SQL_ALL_TYPES spécifie que des informations sur 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 de 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 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.) |
| 01S02 | Valeur de l’option modifiée | Un attribut d’instruction spécifié n’étant pas valide en raison des conditions de travail d’implémentation, une valeur similaire a été temporairement substituée. (Appelez 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 de la liaison de communication | Le lien de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant la fin du traitement de la fonction. |
| 24 000 | État de curseur non valide | Un curseur était ouvert sur l’InstructionHandle etSQLFetchScroll 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 était ouvert sur l’InstructionHandle, mais SQLFetchou SQLFetchScroll n’avait pas été appelé. |
| 40001 | Échec de sérialisation | La transaction a été annulée en raison d’un interblocage de ressources avec une autre transaction. |
| 40003 | Saisie semi-automatique d’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 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 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 la 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 SQL ODBC 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’InstructionHandle, puis la fonction a été appelée et, avant la fin de 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 la fin de son exécution, SQLCancel ou SQLCancelHandle a été appelé sur l’InstructionHandle à partir d’un thread différent dans une application multithread. |
| HY010 | Erreur de séquence de fonction | (DM) Une fonction en exécution asynchrone a été appelée pour le handle de connexion associé à l’InstructionHandle. 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’InstructionHandle 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 en continu. (DM) Une fonction en cours d’exécution asynchrone (et non celle-ci) a été appelée pour l’InstructionHandle 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 a retourné 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 accessibles, peut-être 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 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’était pas 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é | Le délai d’expiration de la requête a expiré avant que la source de données n’a retourné le jeu de résultats. Le délai d’expiration est défini via SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| 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 correspondant à 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 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é par DATA_TYPE, puis par rapport au type de données SQL ODBC 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é en premier DATA_TYPE, suivi de TYPE_NAME, tous 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 WHOLENUM défini par l’utilisateur a également été défini. Ceux-ci sont retournés dans l’ordre INTEGER, 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émentation automatique, même si pris en charge par la source de données, ne mappe pas étroitement à un type de données SQL ODBC. Pour plus d’informations sur l’utilisation de ces informations, consultez Instructions DDL.
Si l’argument DataType spécifie un type de données qui est valide pour la version d’ODBC prise en charge par le pilote, mais qui n’est pas pris en charge par le pilote, il retourne un jeu de résultats vide.
Notes
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 changements de nom de colonne n’affectent pas la compatibilité descendante, car les applications se lient 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 vers le bas à 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.
Notes
SQLGetTypeInfo peut ne pas retourner tous les types de données. Par exemple, un pilote peut ne pas retourner les types de données définis par l’utilisateur. Les applications peuvent utiliser n’importe quel type de données valide, qu’ils soient retournés ou non 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 ceux 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 not 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 ODBC SQL ou d’un type de données SQL spécifique au pilote. Pour les types de données datetime ou interval, 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 Types de données SQL dans l’Annexe D : Types de données. Pour plus d’informations sur les types de données SQL spécifiques aux pilotes, consultez la documentation du pilote. |
| COLUMN_SIZE (ODBC 2.0) | 3 | Integer | Taille de colonne maximale 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 de chaîne (en supposant la précision maximale autorisée du composant fractionnaire seconde). La valeur NULL est retournée pour les types de données pour lesquels 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 en caractères du littéral d’intervalle (tel que défini par la précision de début d’intervalle ; consultez 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 de transfert d’octet 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ère ou 0x pour les types de données binaires ; Null est retourné pour les types de données pour lesquels un préfixe littéral n’est pas applicable. |
| LITERAL_SUFFIX (ODBC 2.0) | 5 | Varchar | Caractère ou caractères utilisés pour terminer un littéral ; par exemple, un guillemet unique (') pour les types de données caractère ; Null est retourné pour les types de données pour lesquels 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 suivants : longueur, précision ou échelle. Ils s’affichent dans l’ordre dans lequel la syntaxe les requiert. Par exemple, CREATE_PARAMS pour DECIMAL serait « précision, échelle » ; CREATE_PARAMS pour VARCHAR équivaudrait à « longueur ». 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 ou 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 les valeurs NULL. SQL_NULLABLE_UNKNOWN si l’on ne sait pas 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 ne respecte pas la casse. |
| SEARCHABLE (ODBC 2.0) | 9 | Smallint non NULL | Comment le type de données est utilisé 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 à l’exception de 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é. La valeur NULL est retournée 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 une précision et une échelle fixes prédéfinies (qui sont spécifiques à la source de données), par exemple un type de données money : SQL_TRUE s’il a une précision et une échelle fixes prédéfinies. SQL_FALSE s’il n’a pas de précision et d’échelle fixes prédéfinies. |
| AUTO_UNIQUE_VALUE (ODBC 2.0) | 12 | Smallint | Indique si le type de données est en cours d’incrémentation 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. La valeur NULL est retournée 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 de la colonne. Lorsqu’une insertion est effectuée dans une colonne d’incrémentation 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’incrémentation automatique commence à un point particulier ou s’incrémente d’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é à être affiché uniquement, 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 pour des fractions de secondes. La valeur NULL est retournée lorsque l'échelle n'est pas applicable. Pour plus d’informations, consultez Taille de colonne, Chiffres décimaux, Longueur des octets de transfert et 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 Taille de colonne, Chiffres décimaux, Longueur des octets de transfert et 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 telle qu’elle 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 renvoie le sous-code pour le type de données interval ou 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 interval, ce champ est 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 renvoie le sous-code pour le type de données interval ou datetime 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 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 d’intervalle. (Voir Interval Data Type Precision dans l’Annexe D : Types de données.) Sinon, cette colonne est NULL. |
Les informations d’attribut peuvent s’appliquer à des 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 d’un jeu de résultats.
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 SQLColAttribute |
| Extraction d’un bloc de données ou défilement d’un jeu de résultats | Fonction SQLFetchScroll |
| Extraction d’une seule ligne ou d’un bloc de données dans une direction avant uniquement | SQLFetch, fonction |
| Retour d’informations sur un pilote ou une source de données | Fonction SQLGetInfo |
Voir aussi
Informations de référence sur l’API ODBC
Fichiers d’en-tête 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