SQLStatistics, fonction

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

Conformité

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

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 lorsque 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 de modèle de recherche de chaîne.

Si l’attribut SQL_ATTR_METADATA_ID d’instruction est défini SQL_TRUEsur , CatalogName est traité comme un identificateur et son cas n’est pas significatif. Si c’est SQL_FALSEle cas, 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 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, une chaîne vide ("") indique les tables qui n’ont pas de schémas. SchemaName ne peut pas contenir de modèle de recherche de chaîne.

Si l’attribut SQL_ATTR_METADATA_ID d’instruction est défini SQL_TRUEsur , SchemaName est traité comme un identificateur et son cas n’est pas significatif. Si c’est SQL_FALSEle cas, 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. TableName ne peut pas contenir de modèle de recherche de chaîne.

Si l’attribut SQL_ATTR_METADATA_ID d’instruction est défini SQL_TRUEsur , TableName est traité comme un identificateur et son cas n’est pas significatif. Si c’est SQL_FALSEle cas, TableName est un argument ordinaire ; il est traité littéralement, et son cas est significatif.

NameLength3

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

Unique

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

Reserved

[Entrée] Indique l’importance des colonnes et PAGES des CARDINALITY colonnes dans le jeu de résultats. Les options suivantes affectent le retour des CARDINALITY colonnes uniquement PAGES ; les informations d’index sont retournées même si CARDINALITY elles 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 ne prennent pas en charge les extensions ODBC ne pourront pas prendre en charge SQL_ENSURE.)

SQL_QUICK demande au pilote de récupérer le CARDINALITY pilote et PAGES uniquement s’il est facilement disponible à partir du serveur. Dans ce cas, le pilote ne garantit pas que les valeurs sont actuelles. (Les applications écrites dans la norme Open Group obtiennent SQL_QUICK toujours le comportement des pilotes compatibles ODBC 3.x.)

Retours

SQL_SUCCESS, , SQL_SUCCESS_WITH_INFOSQL_STILL_EXECUTING, , SQL_ERROR, ou SQL_INVALID_HANDLE.

Diagnostiques

Lorsque SQLStatistics cette propriété est retournée SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur associée SQLSTATE peut être obtenue en appelant SQLGetDiagRec avec un HandleType et SQL_HANDLE_STMT un Handle of StatementHandle. Le tableau suivant répertorie les SQLSTATE valeurs 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 chaque SQLSTATE retour par le Gestionnaire de pilotes. Le code de retour associé à chaque SQLSTATE valeur est SQL_ERROR, sauf indication contraire.

SQLSTATE	Erreur	Descriptif
`01000`	Avertissement général	Message d’information spécifique au pilote. (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.
`24000`	État du curseur non valide	Un curseur a été ouvert sur StatementHandle et `SQLFetch` a `SQLFetchScroll` é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 a été ouvert sur StatementHandle, mais `SQLFetch` n’avait `SQLFetchScroll` 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 pas de spécifique `SQLSTATE` et pour laquelle aucune implémentation `SQLSTATE` spécifique n’a été définie. Le message d’erreur retourné dans `SQLGetDiagRec` 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.
`HY008`	Opération annulée	Le traitement asynchrone a été activé pour StatementHandle. La fonction a été appelée, et avant d’avoir terminé l’exécution, `SQLCancel` ou `SQLCancelHandle` a été appelée sur StatementHandle, puis 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.
`HY009`	Utilisation non valide du pointeur Null	L’argument TableName était un pointeur Null. L’attribut `SQL_ATTR_METADATA_ID` d’instruction a été défini `SQL_TRUE`sur , l’argument CatalogName était un pointeur Null et InfoType`SQL_CATALOG_NAME` retourne que les noms de catalogue sont pris en charge. (DM) L’attribut `SQL_ATTR_METADATA_ID` d’instruction a été défini `SQL_TRUE`sur , et l’argument SchemaName était un pointeur Null.
`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 `SQLStatistics` fonction a été appelée. (DM) `SQLExecute`, `SQLExecDirect`ou `SQLMoreResults` a été appelé pour l’instructionHandle 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`, ou `SQLBulkOperationsSQLSetPos` 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.
`HY090`	Longueur de la chaîne ou de la mémoire tampon non valide	(DM) La valeur de l’un des arguments de longueur de nom était inférieure à 0, mais 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.
`HY100`	Type d’option d’unicité hors plage	(DM) Une valeur unique non valide a été spécifiée.
`HY101`	Type d’option d’exactitude hors 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 la 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 des attributs et `SQL_ATTR_CURSOR_TYPE` attributs d’instruction `SQL_ATTR_CONCURRENCY` n’a pas été prise en charge par le pilote ou la source de données. L’attribut `SQL_ATTR_USE_BOOKMARKS` d’instruction a été défini `SQL_UB_VARIABLE`sur , et l’attribut `SQL_ATTR_CURSOR_TYPE` d’instruction a été défini sur un type de curseur pour lequel le pilote ne prend pas en charge les signets.
`HYT00`	Expiration du délai d’expiration	La période d’expiration de la requête a expiré avant que la source de données n’a retourné le jeu de résultats demandé. La période d’expiration est définie à l’aide `SQLSetStmtAttr`de , `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 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é à 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

SQLStatistics retourne des informations sur une table unique sous la forme d’un jeu de résultats standard, ordonnée par NON_UNIQUE, TYPE, INDEX_QUALIFIER, INDEX_NAMEet ORDINAL_POSITION. Le jeu de résultats combine les informations de statistiques (dans les colonnes et PAGES les CARDINALITY colonnes du jeu de résultats) pour la table avec des informations sur chaque index. Pour plus d’informations sur l’utilisation de ces informations, consultez Utilisations des données de catalogue.

Pour déterminer les longueurs réelles des colonnes , TABLE_SCHEMet TABLE_NAMECOLUMN_NAME des TABLE_CATcolonnes, une application peut appeler SQLGetInfo avec les options , SQL_MAX_SCHEMA_NAME_LENSQL_MAX_TABLE_NAME_LENet SQL_MAX_COLUMN_NAME_LEN les SQL_MAX_CATALOG_NAME_LENoptions.

Note

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	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 à 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 colonne	Numéro de colonne	Type de données	Commentaires
`TABLE_CAT` (ODBC 1.0)	1	varchar	Nom du catalogue de la table à laquelle s’applique la statistique ou l’index ; `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 ces tables qui n’ont pas de catalogues.
`TABLE_SCHEM` (ODBC 1.0)	2	varchar	Nom du schéma de la table à laquelle s’applique la statistique ou l’index ; `NULL` s’il n’est pas applicable à la source de données. Si un pilote prend en charge des 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 ces tables qui n’ont pas de schémas.
`TABLE_NAME` (ODBC 1.0)	3	varchar non `NULL`	Nom de table de la table à laquelle s’applique la statistique ou l’index.
`NON_UNIQUE` (ODBC 1.0)	4	smallint	Indique si l’index n’autorise pas les valeurs dupliquées : `SQL_TRUE` si les valeurs d’index peuvent être non uniques. `SQL_FALSE` si les valeurs d’index doivent être uniques. `NULL` est retourné si `TYPE` c’est `SQL_TABLE_STAT`.
`INDEX_QUALIFIER` (ODBC 1.0)	5	varchar	L’identificateur utilisé pour qualifier le nom d’index qui effectue un `DROP INDEX`; est retourné si un qualificateur d’index n’est pas pris en charge par la source de données ou si c’est le cas `TYPESQL_TABLE_STAT`. `NULL` Si une valeur non null est retournée dans cette colonne, elle doit être utilisée pour qualifier le nom d’index sur une `DROP INDEX` instruction ; sinon, elle `TABLE_SCHEM` doit être utilisée pour qualifier le nom de l’index.
`INDEX_NAME` (ODBC 1.0)	6	varchar	Nom de l’index ; `NULL` est retourné si `TYPE` c’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 ou `PAGES` la `CARDINALITY` colonne). `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 de séquence de colonnes dans l’index (à partir de 1) ; `NULL` est retourné si `TYPE` c’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. `NULL` est retourné si `TYPE` c’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 ; `NULL` est retourné si la séquence de tri de colonne n’est pas prise en charge par la source de données ou si c’est le cas `TYPESQL_TABLE_STAT`.
`CARDINALITY` (ODBC 1.0)	11	entier	Cardinalité de la table ou de l’index ; nombre de lignes de la table si `TYPE` elle est `SQL_TABLE_STAT`; nombre de valeurs uniques dans l’index si `TYPE` ce n’est pas `SQL_TABLE_STAT`le cas ; `NULL` est retourné si la valeur n’est pas disponible à partir de la source de données.
`PAGES` (ODBC 1.0)	12	entier	Nombre de pages utilisées pour stocker l’index ou la table ; nombre de pages de la table si `TYPE` c’est `SQL_TABLE_STAT`le cas ; nombre de pages pour l’index si `TYPE` ce n’est pas `SQL_TABLE_STAT`le cas ; `NULL` est retourné 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 `TYPE` s’il s’agit `SQL_TABLE_STAT`d’un index filtré.

Si la ligne du jeu de résultats correspond à une table, le pilote définit TYPESQL_TABLE_STAT et définit NON_UNIQUE, , INDEX_QUALIFIER, INDEX_NAMEORDINAL_POSITION, COLUMN_NAMEet ASC_OR_DESC à NULL. PAGES S’il CARDINALITY n’est pas disponible à partir de la source de données, le pilote les NULLdéfinit sur .

Exemple de code

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

Pour plus d’informations sur	Article
Liaison d’une mémoire tampon à une colonne dans un jeu de résultats	SQLBindCol, fonction
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	SQLFetchScroll, fonction
Retour des colonnes de clés étrangères	SQLForeignKeys, fonction
Retour des colonnes d’une clé primaire	SQLPrimaryKeys, fonction

Commentaires

Est-ce que cette page vous a été utile?

Last updated on 2025-12-29

Partage via

SQLStatistics, fonction

Conformité

Syntaxe

Arguments

StatementHandle

CatalogName

NameLength1

SchemaName

NameLength2

TableName

NameLength3

Unique

Reserved

Retours

Diagnostiques

Commentaires

Exemple de code

Fonctions associées

Contenu connexe

Commentaires

Ressources supplémentaires