Fonction SQLTables
Conformité
Version introduite : Conformité aux normes ODBC 1.0 : Groupe ouvert
Résumé
SQLTables retourne la liste des noms de table, de catalogue ou de schéma, ainsi que des types de tables, stockés dans une source de données spécifique. Le pilote retourne les informations sous forme de jeu de résultats.
Syntaxe
SQLRETURN SQLTables(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * TableName,
SQLSMALLINT NameLength3,
SQLCHAR * TableType,
SQLSMALLINT NameLength4);
Arguments
StatementHandle
[Entrée] Handle d’instruction pour les résultats récupérés.
CatalogName
[Entrée] Nom du catalogue. L’argument CatalogName accepte les modèles de recherche si l’attribut d’environnement SQL_ODBC_VERSION est SQL_OV_ODBC3 ; il n’accepte pas les modèles de recherche si SQL_OV_ODBC2 est défini. Si un pilote prend en charge les catalogues pour certaines tables, mais pas pour d’autres, par exemple lorsqu’un pilote récupère des données à partir de différents SGBD, une chaîne vide ( » « ) indique les tables qui n’ont pas de catalogues.
Si l’attribut d’instruction SQL_ATTR_METADATA_ID a la valeur SQL_TRUE, CatalogName est traité comme un identificateur et sa casse n’est pas significative. S’il est SQL_FALSE, CatalogName est un argument de valeur de modèle ; il est traité littéralement, et son cas est significatif. Pour plus d’informations, consultez Arguments dans les fonctions de catalogue.
NameLength1
[Entrée] Longueur en caractères de *CatalogName.
SchemaName
[Entrée] Modèle de recherche de chaîne pour les noms de schéma. Si un pilote prend en charge des schémas pour certaines tables, mais pas pour d’autres, par exemple quand le pilote récupère des données à partir de différents SGBD, une chaîne vide ( » « ) indique les tables qui n’ont pas de schémas.
Si l’attribut d’instruction SQL_ATTR_METADATA_ID a la valeur SQL_TRUE, SchemaName est traité comme un identificateur et sa casse n’est pas significative. S’il est SQL_FALSE, SchemaName est un argument de valeur de modèle ; il est traité littéralement, et son cas est significatif.
NameLength2
[Entrée] Longueur en caractères de *SchemaName.
TableName
[Entrée] Modèle de recherche de chaînes pour les noms de table.
Si l’attribut d’instruction SQL_ATTR_METADATA_ID a la valeur SQL_TRUE, TableName est traité comme un identificateur et sa casse n’est pas significative. S’il est SQL_FALSE, TableName est un argument de valeur de modèle ; il est traité littéralement, et son cas est significatif.
NameLength3
[Entrée] Longueur en caractères *TableName.
TableType
[Entrée] Liste des types de tables à mettre en correspondance.
Notez que l’attribut d’instruction SQL_ATTR_METADATA_ID n’a aucun effet sur l’argument TableType . TableType est un argument de liste de valeurs, quel que soit le paramètre de SQL_ATTR_METADATA_ID.
NameLength4
[Entrée] Longueur en caractères *TableType.
Retours
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnostics
Lorsque SQLTables 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 handled’instructionHandle. Le tableau suivant répertorie les valeurs SQLSTATE généralement retournées par SQLTables 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.) |
| 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 et 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 curseur é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. |
| HY008 | Opération annulée | Le traitement asynchrone a été activé pour l’InstructionHandle. La fonction a été appelée et, avant la fin de son exécution, SQLCancel ou SQLCancelHandle a été appelée 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. |
| HY009 | Utilisation non valide du pointeur Null | L’attribut d’instruction SQL_ATTR_METADATA_ID a été défini sur SQL_TRUE, l’argument CatalogName était un pointeur Null et l’SQL_CATALOG_NAME InfoType retourne que les noms de catalogue sont pris en charge. (DM) L’attribut d’instruction SQL_ATTR_METADATA_ID a été défini sur SQL_TRUE, et l’argument SchemaName ou TableName était un pointeur null. |
| 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 lors de l’appel de SQLTables. (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. |
| HY090 | Chaîne ou longueur de mémoire tampon non valide | (DM) La valeur de l’un des arguments de longueur est inférieure à 0, mais n’est pas égale à SQL_NTS. La valeur de l’un des arguments de longueur de nom a dépassé la valeur de longueur maximale pour le nom correspondant. |
| 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 | Un catalogue a été spécifié et le pilote ou la source de données ne prend pas en charge les catalogues. Un schéma a été spécifié et le pilote ou la source de données ne prend pas en charge les schémas. Un modèle de recherche sous forme de chaîne a été spécifié pour le nom du catalogue, le schéma de table ou le nom de la table, et la source de données ne prend pas en charge les modèles de recherche pour un ou plusieurs de ces arguments. La combinaison des paramètres actuels de l’SQL_ATTR_CONCURRENCY et des attributs d’instruction 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 renvoie le jeu de résultats demandé. 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 réponde à la demande. La période de délai d’expiration de la connexion est définie 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 un post-traitement et terminer l’opération. |
Commentaires
SQLTables répertorie toutes les tables de la plage demandée. Un utilisateur peut ou non disposer des privilèges SELECT sur l’une de ces tables. Pour vérifier l’accessibilité, une application peut :
Appelez SQLGetInfo et vérifiez le type d’informations SQL_ACCESSIBLE_TABLES.
Appelez SQLTablePrivileges pour vérifier les privilèges de chaque table.
Sinon, l’application doit être en mesure de gérer une situation où l’utilisateur sélectionne une table pour laquelle les privilèges SELECT ne sont pas accordés.
Les arguments SchemaName et TableName acceptent les modèles de recherche. L’argument CatalogName accepte les modèles de recherche si l’attribut d’environnement SQL_ODBC_VERSION est SQL_OV_ODBC3 ; il n’accepte pas les modèles de recherche si SQL_OV_ODBC2 est défini. Si SQL_OV_ODBC3 est défini, un pilote ODBC 3*.x* exigera que les caractères génériques de l’argument CatalogName soient placés dans une séquence d’échappement pour être traités littéralement. Pour plus d’informations sur les modèles de recherche valides, consultez Arguments de valeur de modèle.
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.
Pour prendre en charge l’énumération des catalogues, des schémas et des types de table, la sémantique spéciale suivante est définie pour les arguments CatalogName, SchemaName, TableName et TableType de SQLTables :
Si CatalogName est SQL_ALL_CATALOGS et Que SchemaName et TableName sont des chaînes vides, le jeu de résultats contient une liste de catalogues valides pour la source de données. (Toutes les colonnes à l’exception de la colonne TABLE_CAT contiennent des VALEURS NULL.)
Si SchemaName est SQL_ALL_SCHEMAS et Que CatalogName et TableName sont des chaînes vides, le jeu de résultats contient une liste de schémas valides pour la source de données. (Toutes les colonnes à l’exception de la colonne TABLE_SCHEM contiennent des VALEURS NULL.)
Si TableType est SQL_ALL_TABLE_TYPES et Que CatalogName, SchemaName et TableName sont des chaînes vides, le jeu de résultats contient une liste de types de table valides pour la source de données. (Toutes les colonnes à l’exception de la colonne TABLE_TYPE contiennent des VALEURS NULL.)
Si TableType n’est pas une chaîne vide, il doit contenir une liste de valeurs séparées par des virgules pour les types d’intérêt ; chaque valeur peut être placée entre guillemets simples (') ou sans guillemets, par exemple, 'TABLE', 'VIEW' ou TABLE, VIEW. Une application doit toujours spécifier le type de table en majuscules ; le pilote doit convertir le type de table dans n’importe quel cas requis par la source de données. Si la source de données ne prend pas en charge un type de table spécifié, SQLTables ne retourne aucun résultat pour ce type.
SQLTables retourne les résultats sous la forme d’un jeu de résultats standard, classé par TABLE_TYPE, TABLE_CAT, TABLE_SCHEM et TABLE_NAME. Pour plus d’informations sur la façon dont ces informations peuvent être utilisées, consultez Utilisations des données de catalogue.
Pour déterminer la longueur réelle des colonnes TABLE_CAT, TABLE_SCHEM et TABLE_NAME, une application peut appeler SQLGetInfo avec les types d’informations SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN et SQL_MAX_TABLE_NAME_LEN.
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 | Colonne ODBC 3*.x* |
|---|---|
| TABLE_QUALIFIER | TABLE_CAT |
| TABLE_OWNER | TABLE_SCHEM |
Le tableau suivant répertorie les colonnes du jeu de résultats. Des colonnes supplémentaires au-delà de la colonne 5 (REMARQUEs) 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 au lieu de spécifier une position ordinale explicite. Pour plus d’informations, consultez Données retournées par les fonctions de catalogue.
| Nom de la colonne | Numéro de colonne | Type de données | Commentaires |
|---|---|---|---|
| TABLE_CAT (ODBC 1.0) | 1 | Varchar | Nom du catalogue ; NULL s’il n’est pas applicable à la source de données. Si un pilote prend en charge les catalogues pour certaines tables, mais pas pour d’autres, par exemple lorsque le pilote récupère des données à partir de différents SGBD, il retourne une chaîne vide (« ») pour les tables qui n’ont pas de catalogues. |
| TABLE_SCHEM (ODBC 1.0) | 2 | Varchar | Nom du schéma ; NULL s’il n’est pas applicable à la source de données. Si un pilote prend en charge les schémas pour certaines tables, mais pas pour d’autres, par exemple lorsque le pilote récupère des données à partir de différents SGBD, il retourne une chaîne vide (« ») pour les tables qui n’ont pas de schémas. |
| TABLE_NAME (ODBC 1.0) | 3 | Varchar | Nom de la table. |
| TABLE_TYPE (ODBC 1.0) | 4 | Varchar | Nom du type de table ; l’un des éléments suivants : « TABLE », « VIEW », « SYSTEM TABLE », « GLOBAL TEMPORARY », « LOCAL TEMPORARY », « ALIAS », « SYNONYM » ou un nom de type spécifique à la source de données. Les significations de « ALIAS » et « SYNONYM » sont spécifiques au pilote. |
| REMARQUES (ODBC 1.0) | 5 | Varchar | Description de la table. |
Exemple
L’exemple de code suivant ne libère pas les handles et les connexions. Consultez FONCTION SQLFreeHandle et FONCTION SQLFreeStmt pour obtenir des exemples de code sur des handles et des instructions libres.
// SQLTables.cpp
// compile with: user32.lib odbc32.lib
#include <windows.h>
#include <sqlext.h>
#include <strsafe.h>
// simple helper functions
int MySQLSuccess(SQLRETURN rc) {
return (rc == SQL_SUCCESS || rc == SQL_SUCCESS_WITH_INFO);
}
struct DataBinding {
SQLSMALLINT TargetType;
SQLPOINTER TargetValuePtr;
SQLINTEGER BufferLength;
SQLLEN StrLen_or_Ind;
};
void printCatalog(const struct DataBinding* catalogResult) {
if (catalogResult[0].StrLen_or_Ind != SQL_NULL_DATA)
printf("Catalog Name = %s\n", (char *)catalogResult[0].TargetValuePtr);
}
// remember to disconnect and free memory, and free statements and handles
int main() {
int bufferSize = 1024, i, numCols = 5;
struct DataBinding* catalogResult = (struct DataBinding*) malloc( numCols * sizeof(struct DataBinding) );
wchar_t* dbName = (wchar_t *)malloc( sizeof(wchar_t)*bufferSize );
wchar_t* userName = (wchar_t *)malloc( sizeof(wchar_t)*bufferSize );
// declare and initialize the environment, connection, statement handles
SQLHENV henv = NULL; // Environment
SQLHDBC hdbc = NULL; // Connection handle
SQLHSTMT hstmt = NULL; // Statement handle
SQLRETURN retCode;
HWND desktopHandle = GetDesktopWindow(); // desktop's window handle
SQLWCHAR connStrbuffer[1024];
SQLSMALLINT connStrBufferLen;
retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (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, (SQLCHAR*)"Driver={SQL Server}", SQL_NTS, (SQLCHAR*)connStrbuffer, 1024 + 1, &connStrBufferLen, SQL_DRIVER_PROMPT);
retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
retCode = SQLGetInfo(hdbc, SQL_DATABASE_NAME, dbName, (SQLSMALLINT)bufferSize, (SQLSMALLINT *)&bufferSize);
retCode = SQLGetInfo(hdbc, SQL_USER_NAME, userName, (SQLSMALLINT)bufferSize, (SQLSMALLINT *)&bufferSize);
bufferSize = 1024;
// allocate memory for the binding
// free this memory when done
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 );
}
// setup the binding (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));
// all catalogs query
printf( "A list of names of all catalogs\n" );
retCode = SQLTables( hstmt, (SQLCHAR*)SQL_ALL_CATALOGS, SQL_NTS, (SQLCHAR*)"", SQL_NTS, (SQLCHAR*)"", SQL_NTS, (SQLCHAR*)"", SQL_NTS );
for ( retCode = SQLFetch(hstmt) ; MySQLSuccess(retCode) ; retCode = SQLFetch(hstmt) )
printCatalog( catalogResult );
}
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 de privilèges pour une colonne ou des colonnes | Fonction SQLColumnPrivileges |
| Retour des colonnes d’une ou plusieurs tables | Fonction SQLColumns |
| Extraction d’une seule ligne ou d’un bloc de données dans une direction vers l’avant uniquement | SQLFetch, fonction |
| Extraction d’un bloc de données ou défilement d’un jeu de résultats | Fonction SQLFetchScroll |
| Statistiques et index de table retournés | Fonction SQLStatistics |
| Retour de privilèges pour une ou plusieurs tables | Fonction SQLTablePrivileges |
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