Fonction SQLStatistics

Conformité
Version introduite : Conformité aux normes ODBC 1.0 : ISO 92

Résumé
SQLStatistics récupère une liste de statistiques sur une seule table et les index associés à la table. Le pilote retourne les informations sous forme de jeu de résultats.

Syntaxe

  
SQLRETURN SQLStatistics(  
     SQLHSTMT        StatementHandle,  
     SQLCHAR *       CatalogName,  
     SQLSMALLINT     NameLength1,  
     SQLCHAR *       SchemaName,  
     SQLSMALLINT     NameLength2,  
     SQLCHAR *       TableName,  
     SQLSMALLINT     NameLength3,  
     SQLUSMALLINT    Unique,  
     SQLUSMALLINT    Reserved);  

Arguments

StatementHandle
[Entrée] Handle d’instruction.

CatalogName
[Entrée] Nom du catalogue. Si un pilote prend en charge les catalogues 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 catalogues. CatalogName ne peut pas contenir un modèle de recherche de chaîne.

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 ordinaire ; 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] Nom du 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. SchemaName ne peut pas contenir un modèle de recherche de chaîne.

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 ordinaire ; il est traité littéralement, et son cas est significatif.

NameLength2
[Entrée] Longueur en caractères de *SchemaName.

TableName
[Entrée] Nom de la table. Cet argument ne peut pas être un pointeur Null. SchemaName ne peut pas contenir un modèle de recherche de chaîne.

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 ordinaire ; il est traité littéralement, et son cas est significatif.

NameLength3
[Entrée] Longueur en caractères *TableName.

Unique
[Entrée] Type d’index : SQL_INDEX_UNIQUE ou SQL_INDEX_ALL.

Reserved
[Entrée] Indique l’importance des colonnes CARDINALITY et PAGES dans le jeu de résultats. Les options suivantes affectent uniquement le retour des colonnes CARDINALITÉ et PAGES ; les informations d’index sont retournées même si CARDINALITY et PAGES ne sont pas retournées.

SQL_ENSURE demande que le pilote récupère inconditionnellement les statistiques. (Les pilotes qui sont conformes uniquement à la norme Open Group et qui ne prennent pas en charge les extensions ODBC ne peuvent pas prendre en charge SQL_ENSURE.)

SQL_QUICK demande que le pilote récupère la CARDINALITÉ et les PAGES uniquement si elles sont facilement disponibles à partir du serveur. Dans ce cas, le pilote ne s'assure pas que les valeurs sont actuelles. (Les applications écrites dans la norme Open Group obtiennent toujours SQL_QUICK comportement des pilotes compatibles ODBC 3.x.)

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLStatistics 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 généralement retournées par SQLStatistics 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.

Commentaires

SQLStatistics retourne des informations sur une table unique en tant que jeu de résultats standard, classé par NON_UNIQUE, TYPE, INDEX_QUALIFIER, INDEX_NAME et ORDINAL_POSITION. Le jeu de résultats combine des informations statistiques (dans les colonnes CARDINALITY et PAGES du jeu de résultats) pour la table avec des informations sur chaque index. 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, TABLE_NAME et COLUMN_NAME, une application peut appeler SQLGetInfo avec les options SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_TABLE_NAME_LEN et SQL_MAX_COLUMN_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.

Le tableau suivant répertorie les colonnes du jeu de résultats. Des colonnes supplémentaires au-delà de la colonne 13 (FILTER_CONDITION) 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.

Si la ligne du jeu de résultats correspond à une table, le pilote définit TYPE sur SQL_TABLE_STAT et définit NON_UNIQUE, INDEX_QUALIFIER, INDEX_NAME, ORDINAL_POSITION, COLUMN_NAME et ASC_OR_DESC sur NULL. Si CARDINALITY ou PAGES ne sont pas disponibles à partir de la source de données, le pilote les définit sur NULL.

Exemple de code

Pour obtenir un exemple de code d’une fonction similaire, consultez SQLColumns.

Fonctions connexes

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC