Partage via

Fonction SQLStatistics

  • Article

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.

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, puis 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’argument TableName était un 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 é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 lorsque la fonction SQLStatistics 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 consultés, 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 de nom était inférieure à 0, mais non égale à SQL_NTS.

La valeur de l’un des arguments de longueur de nom a dépassé la valeur de longueur maximale du nom correspondant.
HY100 Type d’option d’unicité hors de la plage (DM) Une valeur unique non valide a été spécifiée.
HY101 Type d’option de précision hors de la plage (DM) Une valeur réservée non valide a été spécifiée.
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.

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

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.

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 Colonne ODBC 3.x
TABLE_QUALIFIER TABLE_CAT
TABLE_OWNER TABLE_SCHEM
SEQ_IN_INDEX ORDINAL_POSITION
COLLATION ASC_OR_DESC

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.

Nom de la colonne Numéro de colonne Type de données Commentaires
TABLE_CAT (ODBC 1.0) 1 Varchar Nom du catalogue de la table à laquelle la statistique ou l’index s’applique ; 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 de schéma de la table à laquelle la statistique ou l’index s’applique ; 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 not NULL Nom de la table à laquelle la statistique ou l’index s’applique.
NON_UNIQUE (ODBC 1.0) 4 Smallint Indique si l’index n’autorise pas les valeurs en double :

SQL_TRUE si les valeurs d’index peuvent être non uniques.

SQL_FALSE si les valeurs d’index doivent être uniques.

La valeur NULL est retournée si TYPE est SQL_TABLE_STAT.
INDEX_QUALIFIER (ODBC 1.0) 5 Varchar Identificateur utilisé pour qualifier le nom d’index faisant un DROP INDEX ; Null est retourné si un qualificateur d’index n’est pas pris en charge par la source de données ou si TYPE est SQL_TABLE_STAT. Si une valeur non null est retournée dans cette colonne, elle doit être utilisée pour qualifier le nom d’index sur une instruction DROP INDEX ; sinon, le TABLE_SCHEM doit être utilisé pour qualifier le nom de l’index.
INDEX_NAME (ODBC 1.0) 6 Varchar Nom de l’index ; La valeur NULL est retournée si TYPE est SQL_TABLE_STAT.
TYPE (ODBC 1.0) 7 Smallint non NULL Type d’informations retournées :

SQL_TABLE_STAT indique une statistique pour la table (dans la colonne CARDINALITÉ ou PAGES).

SQL_INDEX_BTREE indique un index B-Tree.

SQL_INDEX_CLUSTERED indique un index cluster.

SQL_INDEX_CONTENT indique un index de contenu.

SQL_INDEX_HASHED indique un index haché.

SQL_INDEX_OTHER indique un autre type d’index.
ORDINAL_POSITION (ODBC 1.0) 8 Smallint Numéro séquentiel de colonne dans l’index (à partir de 1) ; La valeur NULL est retournée si TYPE est SQL_TABLE_STAT.
COLUMN_NAME (ODBC 1.0) 9 Varchar Nom de la colonne. Si la colonne est basée sur une expression, telle que SALARY + BENEFITS, l’expression est retournée ; si l’expression ne peut pas être déterminée, une chaîne vide est retournée. La valeur NULL est retournée si TYPE est SQL_TABLE_STAT.
ASC_OR_DESC (ODBC 1.0) 10 Char (1) Séquence de tri pour la colonne : « A » pour l’ordre croissant ; « D » pour décroissant; La valeur NULL est retournée si la séquence de tri de colonne n’est pas prise en charge par la source de données ou si TYPE est SQL_TABLE_STAT.
CARDINALITÉ (ODBC 1.0) 11 Integer Cardinalité de la table ou de l’index ; nombre de lignes dans la table si TYPE est SQL_TABLE_STAT ; nombre de valeurs uniques dans l’index si TYPE n’est pas SQL_TABLE_STAT ; La valeur NULL est retournée si la valeur n’est pas disponible à partir de la source de données.
PAGES (ODBC 1.0) 12 Integer Nombre de pages utilisées pour stocker l’index ou la table ; nombre de pages pour la table si TYPE est SQL_TABLE_STAT ; nombre de pages pour l’index si TYPE n’est pas SQL_TABLE_STAT ; La valeur NULL est retournée si la valeur n’est pas disponible à partir de la source de données ou si elle n’est pas applicable à la source de données.
FILTER_CONDITION (ODBC 2.0) 13 Varchar Si l’index est un index filtré, il s’agit de la condition de filtre, telle que SALARY > 30000 ; si la condition de filtre ne peut pas être déterminée, il s’agit d’une chaîne vide.

NULL si l’index n’est pas un index filtré, il ne peut pas être déterminé si l’index est un index filtré ou si TYPE est SQL_TABLE_STAT.

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.

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
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
Retour des colonnes de clés étrangères Fonction SQLForeignKeys
Retour des colonnes d’une clé primaire Fonction SQLPrimaryKeys

Voir aussi

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