Freigeben über

SQLStatistics-Funktion

  • Artikel

Konformität
Eingeführte Version: ODBC 1.0-Standards Compliance: ISO 92

Zusammenfassung
SQLStatistics ruft eine Liste von Statistiken zu einer einzelnen Tabelle und den der Tabelle zugeordneten Indizes ab. Der Treiber gibt die Informationen als Resultset zurück.

Syntax

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

Argumente

StatementHandle
[Eingabe] Anweisungshandle.

Catalogname
[Eingabe] Katalogname. Wenn ein Treiber Kataloge für einige Tabellen, aber nicht für andere unterstützt, z. B. wenn der Treiber Daten aus verschiedenen DBMs abruft, gibt eine leere Zeichenfolge ("") die Tabellen an, die keine Kataloge enthalten. CatalogName kann kein Zeichenfolgensuchmuster enthalten.

Wenn das SQL_ATTR_METADATA_ID-Anweisungsattribut auf SQL_TRUE festgelegt ist, wird CatalogName als Bezeichner behandelt, und die Groß-/Kleinschreibung ist nicht signifikant. Wenn es SQL_FALSE ist, ist CatalogName ein gewöhnliches Argument. es wird wörtlich behandelt, und sein Fall ist signifikant. Weitere Informationen finden Sie unter Argumente in Katalogfunktionen.

NameLength1
[Eingabe] Länge in Zeichen von *CatalogName.

Schemaname
[Eingabe] Schemaname. Wenn ein Treiber Schemas für einige Tabellen, aber nicht für andere unterstützt, z. B. wenn der Treiber Daten aus verschiedenen DBMS abruft, gibt eine leere Zeichenfolge ("") die Tabellen an, die keine Schemas aufweisen. SchemaName kann kein Zeichenfolgensuchmuster enthalten.

Wenn das SQL_ATTR_METADATA_ID-Anweisungsattribut auf SQL_TRUE festgelegt ist, wird SchemaName als Bezeichner behandelt, und die Groß-/Kleinschreibung ist nicht signifikant. Wenn es SQL_FALSE ist, ist SchemaName ein gewöhnliches Argument. es wird wörtlich behandelt, und sein Fall ist signifikant.

NameLength2
[Eingabe] Länge in Zeichen von *SchemaName.

TableName
[Eingabe] Tabellenname. Dieses Argument darf kein NULL-Zeiger sein. SchemaName kann kein Zeichenfolgensuchmuster enthalten.

Wenn das SQL_ATTR_METADATA_ID-Anweisungsattribut auf SQL_TRUE festgelegt ist, wird TableName als Bezeichner behandelt, und die Groß-/Kleinschreibung ist nicht signifikant. Wenn es SQL_FALSE ist, ist TableName ein gewöhnliches Argument. es wird wörtlich behandelt, und sein Fall ist signifikant.

NameLength3
[Eingabe] Länge in Zeichen von *TableName.

Eindeutig
[Eingabe] Indextyp: SQL_INDEX_UNIQUE oder SQL_INDEX_ALL.

Reserved
[Eingabe] Gibt die Wichtigkeit der Spalten CARDINALITY und PAGES im Resultset an. Die folgenden Optionen wirken sich nur auf die Rückgabe der Spalten CARDINALITY und PAGES aus. Indexinformationen werden auch dann zurückgegeben, wenn CARDINALITY und PAGES nicht zurückgegeben werden.

SQL_ENSURE fordert an, dass der Treiber die Statistiken bedingungslos abruft. (Treiber, die nur dem Open Group-Standard entsprechen und ODBC-Erweiterungen nicht unterstützen, können SQL_ENSURE nicht unterstützen.)

SQL_QUICK fordert an, dass der Treiber cardinality und PAGES nur dann abruft, wenn sie vom Server verfügbar sind. In diesem Fall wird vom Treiber nicht sichergestellt, dass die Werte aktuell sind. (Anwendungen, die in den Open Group-Standard geschrieben werden, erhalten immer SQL_QUICK Verhalten von ODBC 3.x-kompatiblen Treibern.)

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnose

Wenn SQLStatistics SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle von StatementHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die in der Regel von SQLStatistics zurückgegeben werden, und die einzelnen Werte werden im Kontext dieser Funktion erläutert. die Notation "(DM)" steht vor den Beschreibungen von SQLSTATEs, die vom Treiber-Manager zurückgegeben werden. Der Rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

SQLSTATE Fehler BESCHREIBUNG
01000 Allgemeine Warnung Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
08S01 Kommunikationslinkfehler Die Kommunikationsverbindung zwischen dem Treiber und der Datenquelle, mit der der Treiber verbunden wurde, ist fehlgeschlagen, bevor die Verarbeitung der Funktion abgeschlossen wurde.
24.000 Ungültiger Cursorstatus Im StatementHandle war ein Cursor geöffnet, und SQLFetch oder SQLFetchScroll wurde aufgerufen. Dieser Fehler wird vom Treiber-Manager zurückgegeben, wenn SQLFetch oder SQLFetchScroll nicht SQL_NO_DATA zurückgegeben hat und vom Treiber zurückgegeben wird, wenn SQLFetch oder SQLFetchScroll SQL_NO_DATA zurückgegeben hat.

Im StatementHandle war ein Cursor geöffnet, aber SQLFetch oder SQLFetchScroll wurde nicht aufgerufen.
40001 Serialisierungsfehler Die Transaktion wurde aufgrund eines Ressourcen-Deadlocks mit einer anderen Transaktion zurückgesetzt.
40003 Anweisungsabschluss unbekannt Die zugeordnete Verbindung ist während der Ausführung dieser Funktion fehlgeschlagen, und der Status der Transaktion kann nicht bestimmt werden.
HY000 Allgemeiner Fehler Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den keine implementierungsspezifische SQLSTATE definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und seine Ursache.
HY001 Fehler bei der Speicherbelegung Der Treiber konnte arbeitsspeicher nicht zuordnen, der zur Unterstützung der Ausführung oder Fertigstellung der Funktion erforderlich ist.
HY008 Vorgang abgebrochen Die asynchrone Verarbeitung wurde für statementHandle aktiviert. Die Funktion wurde aufgerufen, und bevor die Ausführung abgeschlossen war, wurde SQLCancel oder SQLCancelHandle für die StatementHandle aufgerufen, und dann wurde die Funktion erneut für statementHandle aufgerufen.

Die Funktion wurde aufgerufen, und bevor die Ausführung abgeschlossen wurde, wurde SQLCancel oder SQLCancelHandle für die StatementHandle aus einem anderen Thread in einer Multithreadanwendung aufgerufen.
HY009 Ungültige Verwendung des NULL-Zeigers Das Argument TableName war ein NULL-Zeiger.

Das SQL_ATTR_METADATA_ID-Anweisungsattribut wurde auf SQL_TRUE festgelegt, das CatalogName-Argument war ein NULL-Zeiger, und die SQL_CATALOG_NAME InfoType gibt zurück, dass Katalognamen unterstützt werden.

(DM) Das SQL_ATTR_METADATA_ID-Anweisungsattribut wurde auf SQL_TRUE festgelegt, und das SchemaName-Argument war ein NULL-Zeiger.
HY010 Funktionssequenzfehler (DM) Eine asynchron ausgeführte Funktion wurde für das Verbindungshandle aufgerufen, das dem StatementHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, als die FUNKTION SQLStatistics aufgerufen wurde.

(DM) SQLExecute, SQLExecDirect oder SQLMoreResults wurde für statementHandle aufgerufen und SQL_PARAM_DATA_AVAILABLE zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle gestreamten Parameter abgerufen wurden.

(DM) Eine asynchron ausgeführte Funktion (nicht diese) wurde für das StatementHandle aufgerufen und wurde noch ausgeführt, als diese Funktion aufgerufen wurde.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für statementHandle aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei der Ausführungsparameter oder -spalten gesendet wurden.
HY013 Fehler bei der Speicherverwaltung Der Funktionsaufruf konnte nicht verarbeitet werden, weil auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von geringen Arbeitsspeicherbedingungen.
HY090 Ungültige Zeichenfolgen- oder Pufferlänge (DM) Der Wert eines der Namenslängenargumente war kleiner als 0, aber nicht gleich SQL_NTS.

Der Wert eines der Namenslängenargumente hat den maximalen Längenwert für den entsprechenden Namen überschritten.
HY100 Eindeutigkeitsoptionstyp außerhalb des Bereichs (DM) Ein ungültiger Eindeutiger Wert wurde angegeben.
HY101 Genauigkeitsoptionstyp außerhalb des Bereichs (DM) Ein ungültiger reservierter Wert wurde angegeben.
HY117 Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur trenn- und schreibgeschützte Funktionen sind zulässig. (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran-Funktion.
HYC00 Optionales Feature nicht implementiert Ein Katalog wurde angegeben, und der Treiber oder die Datenquelle unterstützt keine Kataloge.

Es wurde ein Schema angegeben, und der Treiber oder die Datenquelle unterstützt keine Schemas.

Die Kombination aus den aktuellen Einstellungen des SQL_ATTR_CONCURRENCY- und SQL_ATTR_CURSOR_TYPE-Anweisungsattributes wurde vom Treiber oder der Datenquelle nicht unterstützt.

Das SQL_ATTR_USE_BOOKMARKS-Anweisungsattribut wurde auf SQL_UB_VARIABLE festgelegt, und das Attribut der SQL_ATTR_CURSOR_TYPE-Anweisung wurde auf einen Cursortyp festgelegt, für den der Treiber keine Lesezeichen unterstützt.
HYT00 Timeout abgelaufen Der Abfragetimeoutzeitraum ist abgelaufen, bevor die Datenquelle das angeforderte Resultset zurückgegeben hat. Der Timeoutzeitraum wird über SQLSetStmtAttr festgelegt, SQL_ATTR_QUERY_TIMEOUT.
HYT01 Verbindungstimeout abgelaufen Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Treiber unterstützt diese Funktion nicht. (DM) Der Der StatementHandle zugeordnete Treiber unterstützt die Funktion nicht.
IM017 Abruf ist im asynchronen Benachrichtigungsmodus deaktiviert. Wenn das Benachrichtigungsmodell verwendet wird, wird die Abfrage deaktiviert.
IM018 SQLCompleteAsync wurde nicht aufgerufen, um den vorherigen asynchronen Vorgang für dieses Handle abzuschließen. Wenn der vorherige Funktionsaufruf für das Handle SQL_STILL_EXECUTING zurückgibt und der Benachrichtigungsmodus aktiviert ist, muss SQLCompleteAsync für das Handle aufgerufen werden, um die Nachverarbeitung durchzuführen und den Vorgang abzuschließen.

Kommentare

SQLStatistics gibt Informationen zu einer einzelnen Tabelle als Standardresultset zurück, geordnet nach NON_UNIQUE, TYPE, INDEX_QUALIFIER, INDEX_NAME und ORDINAL_POSITION. Das Resultset kombiniert Statistikinformationen (in den Spalten CARDINALITY und PAGES des Resultsets) für die Tabelle mit Informationen zu jedem Index. Informationen dazu, wie diese Informationen verwendet werden können, finden Sie unter Verwendung von Katalogdaten.

Um die tatsächliche Länge der Spalten TABLE_CAT, TABLE_SCHEM, TABLE_NAME und COLUMN_NAME zu bestimmen, kann eine Anwendung SQLGetInfo mit den Optionen SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_TABLE_NAME_LEN und SQL_MAX_COLUMN_NAME_LEN aufrufen.

Hinweis

Weitere Informationen zur allgemeinen Verwendung, zu Argumenten und zurückgegebenen Daten von ODBC-Katalogfunktionen finden Sie unter Katalogfunktionen.

Die folgenden Spalten wurden für ODBC 3.x umbenannt. Die Änderungen des Spaltennamens wirken sich nicht auf die Abwärtskompatibilität aus, da Anwendungen anhand der Spaltennummer gebunden werden.

ODBC 2.0-Spalte ODBC 3.x-Spalte
TABLE_QUALIFIER TABLE_CAT
TABLE_OWNER TABLE_SCHEM
SEQ_IN_INDEX ORDINAL_POSITION
COLLATION ASC_OR_DESC

In der folgenden Tabelle sind die Spalten im Resultset aufgeführt. Zusätzliche Spalten über Spalte 13 (FILTER_CONDITION) hinaus können vom Treiber definiert werden. Eine Anwendung sollte Zugriff auf treiberspezifische Spalten erhalten, indem sie vom Ende des Resultsets heruntergezählt wird, anstatt eine explizite Ordnungsposition anzugeben. Weitere Informationen finden Sie unter Von Katalogfunktionen zurückgegebene Daten.

Spaltenname Spaltennummer Datentyp Kommentare
TABLE_CAT (ODBC 1.0) 1 Varchar Katalogname der Tabelle, auf die sich die Statistik oder der Index bezieht; NULL, wenn nicht auf die Datenquelle anwendbar. Wenn ein Treiber Kataloge für einige Tabellen, aber nicht für andere unterstützt, z. B. wenn der Treiber Daten aus verschiedenen DBMS abruft, gibt er eine leere Zeichenfolge ("") für die Tabellen zurück, die keine Kataloge enthalten.
TABLE_SCHEM (ODBC 1.0) 2 Varchar Schemaname der Tabelle, für die die Statistik oder der Index gilt; NULL, wenn nicht auf die Datenquelle anwendbar. Wenn ein Treiber Schemas für einige Tabellen unterstützt, aber nicht für andere, z. B. wenn der Treiber Daten aus verschiedenen DBMS abruft, gibt er eine leere Zeichenfolge ("") für die Tabellen zurück, die keine Schemas haben.
TABLE_NAME (ODBC 1.0) 3 Varchar nicht NULL Tabellenname der Tabelle, auf die die Statistik oder der Index angewendet wird.
NON_UNIQUE (ODBC 1.0) 4 Smallint Gibt an, ob der Index keine doppelten Werte zulässt:

SQL_TRUE, ob die Indexwerte nicht eindeutig sein können.

SQL_FALSE, wenn die Indexwerte eindeutig sein müssen.

NULL wird zurückgegeben, wenn TYPE SQL_TABLE_STAT ist.
INDEX_QUALIFIER (ODBC 1.0) 5 Varchar Der Bezeichner, der verwendet wird, um den Indexnamen zu qualifizieren, der einen DROP INDEX ausführt; NULL wird zurückgegeben, wenn ein Indexqualifizierer von der Datenquelle nicht unterstützt wird oder WENN TYPE SQL_TABLE_STAT ist. Wenn in dieser Spalte ein Wert ungleich NULL zurückgegeben wird, muss er verwendet werden, um den Indexnamen für eine DROP INDEX-Anweisung zu qualifizieren. Andernfalls sollte die TABLE_SCHEM verwendet werden, um den Indexnamen zu qualifizieren.
INDEX_NAME (ODBC 1.0) 6 Varchar Indexname; NULL wird zurückgegeben, wenn TYPE SQL_TABLE_STAT ist.
TYPE (ODBC 1.0) 7 Smallint nicht NULL Art der zurückgegebenen Informationen:

SQL_TABLE_STAT gibt eine Statistik für die Tabelle an (in der Spalte CARDINALITY oder PAGES).

SQL_INDEX_BTREE gibt einen B-Tree-Index an.

SQL_INDEX_CLUSTERED gibt einen gruppierten Index an.

SQL_INDEX_CONTENT gibt einen Inhaltsindex an.

SQL_INDEX_HASHED gibt einen Hashindex an.

SQL_INDEX_OTHER gibt einen anderen Indextyp an.
ORDINAL_POSITION (ODBC 1.0) 8 Smallint Spaltensequenznummer im Index (ab 1); NULL wird zurückgegeben, wenn TYPE SQL_TABLE_STAT ist.
COLUMN_NAME (ODBC 1.0) 9 Varchar Spaltenname. Wenn die Spalte auf einem Ausdruck basiert, z. B. SALARY + BENEFITS, wird der Ausdruck zurückgegeben. wenn der Ausdruck nicht bestimmt werden kann, wird eine leere Zeichenfolge zurückgegeben. NULL wird zurückgegeben, wenn TYPE SQL_TABLE_STAT ist.
ASC_OR_DESC (ODBC 1.0) 10 Char(1) Sortiersequenz für die Spalte: "A" für aufsteigend; "D" für absteigend; NULL wird zurückgegeben, wenn die Spaltensortiersequenz von der Datenquelle nicht unterstützt wird oder WENN TYPE SQL_TABLE_STAT ist.
KARDINALITÄT (ODBC 1.0) 11 Integer Kardinalität der Tabelle oder des Indexes; Anzahl der Zeilen in der Tabelle, wenn TYPE SQL_TABLE_STAT ist; Anzahl eindeutiger Werte im Index, wenn TYPE nicht SQL_TABLE_STAT ist; NULL wird zurückgegeben, wenn der Wert nicht aus der Datenquelle verfügbar ist.
PAGES (ODBC 1.0) 12 Integer Anzahl der Seiten, die zum Speichern des Index oder der Tabelle verwendet werden; Anzahl der Seiten für die Tabelle, wenn TYPE SQL_TABLE_STAT ist; Anzahl der Seiten für den Index, wenn TYPE nicht SQL_TABLE_STAT ist; NULL wird zurückgegeben, wenn der Wert nicht aus der Datenquelle verfügbar ist oder nicht für die Datenquelle zutreffend ist.
FILTER_CONDITION (ODBC 2.0) 13 Varchar Wenn der Index ein gefilterter Index ist, ist dies die Filterbedingung, z. B. SALARY > 30000. Wenn die Filterbedingung nicht bestimmt werden kann, ist dies eine leere Zeichenfolge.

NULL, wenn der Index kein gefilterter Index ist, kann nicht bestimmt werden, ob es sich bei dem Index um einen gefilterten Index handelt, oder TYPE ist SQL_TABLE_STAT.

Wenn die Zeile im Resultset einer Tabelle entspricht, legt der Treiber TYPE auf SQL_TABLE_STAT fest und legt NON_UNIQUE, INDEX_QUALIFIER, INDEX_NAME, ORDINAL_POSITION, COLUMN_NAME und ASC_OR_DESC auf NULL fest. Wenn CARDINALITY oder PAGES in der Datenquelle nicht verfügbar sind, legt der Treiber sie auf NULL fest.

Codebeispiel

Ein Codebeispiel für eine ähnliche Funktion finden Sie unter SQLColumns.

Informationen über Finden Sie unter
Binden eines Puffers an eine Spalte in einem Resultset SQLBindCol-Funktion
Abbrechen der Anweisungsverarbeitung SQLCancel-Funktion
Abrufen einer einzelnen Zeile oder eines Datenblocks in einer vorwärtsgerichteten Richtung. SQLFetch-Funktion
Abrufen eines Datenblocks oder Scrollen durch ein Resultset SQLFetchScroll-Funktion
Zurückgeben der Spalten von Fremdschlüsseln SQLForeignKeys-Funktion
Zurückgeben der Spalten eines Primärschlüssels SQLPrimaryKeys-Funktion

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien