Funzione SQLStatistics

Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ISO 92

Riepilogo
SQLStatistics recupera un elenco di statistiche relative a una singola tabella e agli indici associati alla tabella. Il driver restituisce le informazioni come set di risultati.

Sintassi

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

Argomenti

StatementHandle
[Input] Handle di istruzione.

CatalogName
[Input] Nome catalogo. Se un driver supporta cataloghi per alcune tabelle ma non per altri, ad esempio quando il driver recupera i dati da diversi DBMS, una stringa vuota ("") indica le tabelle che non dispongono di cataloghi. CatalogName non può contenere un criterio di ricerca di stringhe.

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, CatalogName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, CatalogName è un argomento ordinario; viene trattato letteralmente e il relativo caso è significativo. Per altre informazioni, vedere Argomenti in Funzioni del catalogo.

NameLength1
[Input] Lunghezza in caratteri di *CatalogName.

SchemaName
[Input] Nome schema. Se un driver supporta schemi per alcune tabelle, ma non per altri, ad esempio quando il driver recupera i dati da diversi DBMS, una stringa vuota ("") indica le tabelle che non dispongono di schemi. SchemaName non può contenere un criterio di ricerca di stringhe.

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, SchemaName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, SchemaName è un argomento ordinario; viene trattato letteralmente e il relativo caso è significativo.

NameLength2
[Input] Lunghezza in caratteri di *SchemaName.

TableName
[Input] Nome tabella. Questo argomento non può essere un puntatore Null. SchemaName non può contenere un criterio di ricerca di stringhe.

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, TableName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, TableName è un argomento ordinario; viene trattato letteralmente e il relativo case è significativo.

NameLength3
[Input] Lunghezza in caratteri di *TableName.

Univoco
[Input] Tipo di indice: SQL_INDEX_UNIQUE o SQL_INDEX_ALL.

Reserved
[Input] Indica l'importanza delle colonne CARDINALITY e PAGES nel set di risultati. Le opzioni seguenti influiscono solo sulla restituzione delle colonne CARDINALITY e PAGES; le informazioni sull'indice vengono restituite anche se CARDINALITY e PAGES non vengono restituite.

SQL_ENSURE richiede che il driver recuperi in modo incondizionato le statistiche. I driver conformi solo allo standard Open Group e non supportano le estensioni ODBC non saranno in grado di supportare SQL_ENSURE.

SQL_QUICK richiede che il driver recuperi CARDINALITY e PAGES solo se sono prontamente disponibili dal server. In tal caso, il driver non garantisce che i valori siano aggiornati. Le applicazioni scritte nello standard Open Group otterranno sempre SQL_QUICK comportamento da ODBC 3.x driver conformi.

Resi

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLStatistics restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleTypedi SQL_HANDLE_STMT e handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE restituiti in genere da SQLStatistics e ne spiega ognuno nel contesto di questa funzione. La notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

SQLSTATE	Errore	Descrizione
01000	Avviso generale	Messaggio informativo specifico del driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
08S01	Errore del collegamento di comunicazione	Collegamento di comunicazione tra il driver e l'origine dati a cui è stato connesso il driver non è riuscito prima del completamento dell'elaborazione della funzione.
24000	Stato del cursore non valido	È stato aperto un cursore in StatementHandle e è stato chiamato SQLFetch o SQLFetchScroll. Questo errore viene restituito da Gestione driver se SQLFetch o SQLFetchScroll non ha restituito SQL_NO_DATA e viene restituito dal driver se SQLFetch o SQLFetchScroll ha restituito SQL_NO_DATA. Un cursore è stato aperto in StatementHandle, ma SQLFetch o SQLFetchScroll non è stato chiamato.
40001	Errore di serializzazione	È stato eseguito il rollback della transazione a causa di un deadlock della risorsa con un'altra transazione.
40003	Completamento istruzione sconosciuto	La connessione associata non è riuscita durante l'esecuzione di questa funzione e non è possibile determinare lo stato della transazione.
HY000	Errore generale:	Si è verificato un errore per il quale non è stato specificato SQLSTATE e per il quale non è stato definito alcun SQLSTATE specifico dell'implementazione. Il messaggio di errore restituito da SQLGetDiagRec nel buffer *MessageText descrive l'errore e la relativa causa.
HY001	Errore di allocazione della memoria	Il driver non è riuscito ad allocare memoria necessaria per supportare l'esecuzione o il completamento della funzione.
HY008	Operazione annullata	L'elaborazione asincrona è stata abilitata per StatementHandle. La funzione è stata chiamata e prima di completare l'esecuzione, SQLCancel o SQLCancelHandle è stata chiamata su StatementHandle e quindi la funzione è stata chiamata nuovamente in StatementHandle. La funzione è stata chiamata e prima del completamento dell'esecuzione, SQLCancel o SQLCancelHandle è stato chiamato su StatementHandle da un thread diverso in un'applicazione multithread.
HY009	Uso non valido del puntatore Null	L'argomento TableName è un puntatore Null. L'attributo dell'istruzione SQL_ATTR_METADATA_ID è stato impostato su SQL_TRUE, l'argomento CatalogName è un puntatore Null e l'SQL_CATALOG_NAME InfoType restituisce che i nomi di catalogo sono supportati. (DM) L'attributo dell'istruzione SQL_ATTR_METADATA_ID è stato impostato su SQL_TRUE e l'argomento SchemaName era un puntatore Null.
HY010	Errore della sequenza di funzioni	(DM) È stata chiamata una funzione in esecuzione asincrona per l'handle di connessione associato a StatementHandle. Questa funzione asincrona era ancora in esecuzione quando è stata chiamata la funzione SQLStatistics . (DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per StatementHandle e restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata prima del recupero dei dati per tutti i parametri trasmessi. (DM) Una funzione in esecuzione asincrona (non questa) è stata chiamata per StatementHandle ed è ancora in esecuzione quando questa funzione è stata chiamata. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos è stato chiamato per StatementHandle e restituito SQL_NEED_DATA. Questa funzione è stata chiamata prima dell'invio dei dati per tutti i parametri o le colonne data-at-execution.
HY013	Errore di gestione della memoria	Impossibile elaborare la chiamata di funzione perché non è stato possibile accedere agli oggetti di memoria sottostanti, probabilmente a causa di condizioni di memoria insufficiente.
HY090	Lunghezza della stringa o del buffer non valida	(DM) Il valore di uno degli argomenti di lunghezza del nome è minore di 0 ma non uguale a SQL_NTS. Il valore di uno degli argomenti lunghezza nome ha superato il valore di lunghezza massima per il nome corrispondente.
HY100	Tipo di opzione di univocità non compreso nell'intervallo	(DM) È stato specificato un valore univoco non valido.
HY101	Tipo di opzione accuratezza non compreso nell'intervallo	(DM) È stato specificato un valore riservato non valido.
HY117	La connessione viene sospesa a causa dello stato sconosciuto della transazione. Sono consentite solo funzioni disconnesse e di sola lettura.	(DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran.
HYC00	Funzionalità facoltativa non implementata	È stato specificato un catalogo e il driver o l'origine dati non supporta i cataloghi. È stato specificato uno schema e il driver o l'origine dati non supporta gli schemi. La combinazione delle impostazioni correnti degli attributi delle istruzioni SQL_ATTR_CONCURRENCY e SQL_ATTR_CURSOR_TYPE non è supportata dal driver o dall'origine dati. L'attributo di istruzione SQL_ATTR_USE_BOOKMARKS è stato impostato su SQL_UB_VARIABLE e l'attributo dell'istruzione SQL_ATTR_CURSOR_TYPE è stato impostato su un tipo di cursore per cui il driver non supporta i segnalibri.
HYT00	Timeout scaduto	Periodo di timeout della query scaduto prima che l'origine dati restituisca il set di risultati richiesto. Il periodo di timeout viene impostato tramite SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01	Il timeout della connessione è scaduto	Periodo di timeout della connessione scaduto prima che l'origine dati rispondesse alla richiesta. Il periodo di timeout della connessione viene impostato tramite SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Il driver non supporta questa funzione	(DM) Il driver associato a StatementHandle non supporta la funzione.
IM017	Il polling è disabilitato in modalità di notifica asincrona	Ogni volta che viene usato il modello di notifica, il polling è disabilitato.
IM018	SQLCompleteAsync non è stato chiamato per completare l'operazione asincrona precedente su questo handle.	Se la chiamata di funzione precedente sull'handle restituisce SQL_STILL_EXECUTING e se la modalità di notifica è abilitata, è necessario chiamare SQLCompleteAsync sull'handle per eseguire la post-elaborazione e completare l'operazione.

Commenti

SQLStatistics restituisce informazioni su una singola tabella come set di risultati standard, ordinato per NON_UNIQUE, TYPE, INDEX_QUALIFIER, INDEX_NAME e ORDINAL_POSITION. Il set di risultati combina le informazioni sulle statistiche (nelle colonne CARDINALITY e PAGES del set di risultati) per la tabella con informazioni su ogni indice. Per informazioni su come usare queste informazioni, vedere Uses of Catalog Data.For information about how this information might be used, see Uses of Catalog Data.

Per determinare le lunghezze effettive delle colonne TABLE_CAT, TABLE_SCHEM, TABLE_NAME e COLUMN_NAME, un'applicazione può chiamare SQLGetInfo con le opzioni SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_TABLE_NAME_LEN e SQL_MAX_COLUMN_NAME_LEN.

Nota

Per altre informazioni sull'utilizzo generale, gli argomenti e i dati restituiti delle funzioni del catalogo ODBC, vedere Funzioni del catalogo.

Le colonne seguenti sono state rinominate per ODBC 3.x. Le modifiche apportate al nome della colonna non influiscono sulla compatibilità con le versioni precedenti perché le applicazioni si associano per numero di colonna.

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

Nella tabella seguente sono elencate le colonne nel set di risultati. Le colonne aggiuntive successive alla colonna 13 (FILTER_CONDITION) possono essere definite dal driver. Un'applicazione deve ottenere l'accesso alle colonne specifiche del driver con il conteggio dalla fine del set di risultati invece di specificare una posizione ordinale esplicita. Per altre informazioni, vedere Dati restituiti dalle funzioni del catalogo.

Nome colonna	Column number	Tipo di dati	Commenti
TABLE_CAT (ODBC 1.0)	1	Varchar	Nome del catalogo della tabella a cui si applica la statistica o l'indice; NULL se non applicabile all'origine dati. Se un driver supporta cataloghi per alcune tabelle ma non per altri, ad esempio quando il driver recupera i dati da diversi DBMS, restituisce una stringa vuota ("") per le tabelle che non dispongono di cataloghi.
TABLE_SCHEM (ODBC 1.0)	2	Varchar	Nome dello schema della tabella a cui si applica la statistica o l'indice; NULL se non applicabile all'origine dati. Se un driver supporta schemi per alcune tabelle ma non per altri, ad esempio quando il driver recupera i dati da diversi DBMS, restituisce una stringa vuota ("") per le tabelle che non dispongono di schemi.
TABLE_NAME (ODBC 1.0)	3	Varchar non NULL	Nome della tabella a cui si applica la statistica o l'indice.
NON_UNIQUE (ODBC 1.0)	4	Smallint	Indica se l'indice non consente valori duplicati: SQL_TRUE se i valori di indice possono essere non univoci. SQL_FALSE se i valori di indice devono essere univoci. Se TYPE è SQL_TABLE_STAT, viene restituito NULL.
INDEX_QUALIFIER (ODBC 1.0)	5	Varchar	Identificatore utilizzato per qualificare il nome dell'indice che esegue un'istruzione DROP INDEX; Viene restituito NULL se un qualificatore di indice non è supportato dall'origine dati o se TYPE è SQL_TABLE_STAT. Se in questa colonna viene restituito un valore non Null, deve essere utilizzato per qualificare il nome dell'indice in un'istruzione DROP INDEX . In caso contrario, è necessario utilizzare il TABLE_SCHEM per qualificare il nome dell'indice.
INDEX_NAME (ODBC 1.0)	6	Varchar	Nome indice; Se TYPE è SQL_TABLE_STAT, viene restituito NULL.
TYPE (ODBC 1.0)	7	Smallint non NULL	Tipo di informazioni restituite: SQL_TABLE_STAT indica una statistica per la tabella (nella colonna CARDINALITY o PAGES). SQL_INDEX_BTREE indica un indice albero B. SQL_INDEX_CLUSTERED indica un indice cluster. SQL_INDEX_CONTENT indica un indice di contenuto. SQL_INDEX_HASHED indica un indice con hash. SQL_INDEX_OTHER indica un altro tipo di indice.
ORDINAL_POSITION (ODBC 1.0)	8	Smallint	Numero di sequenza di colonna nell'indice (a partire da 1); Se TYPE è SQL_TABLE_STAT, viene restituito NULL.
COLUMN_NAME (ODBC 1.0)	9	Varchar	Nome colonna. Se la colonna è basata su un'espressione, ad esempio SALARY + BENEFITS, l'espressione viene restituita; se non è possibile determinare l'espressione, viene restituita una stringa vuota. Se TYPE è SQL_TABLE_STAT, viene restituito NULL.
ASC_OR_DESC (ODBC 1.0)	10	Char(1)	Sequenza di ordinamento per la colonna: "A" per l'ordine crescente; "D" per decrescente; Viene restituito NULL se la sequenza di ordinamento delle colonne non è supportata dall'origine dati o se TYPE è SQL_TABLE_STAT.
CARDINALITÀ (ODBC 1.0)	11	Integer	Cardinalità della tabella o dell'indice; numero di righe nella tabella se TYPE è SQL_TABLE_STAT; numero di valori univoci nell'indice se TYPE non è SQL_TABLE_STAT; Se il valore non è disponibile nell'origine dati, viene restituito NULL.
PAGES (ODBC 1.0)	12	Integer	Numero di pagine utilizzate per archiviare l'indice o la tabella; numero di pagine per la tabella se TYPE è SQL_TABLE_STAT; numero di pagine per l'indice se TYPE non è SQL_TABLE_STAT; Null viene restituito se il valore non è disponibile dall'origine dati o se non applicabile all'origine dati.
FILTER_CONDITION (ODBC 2.0)	13	Varchar	Se l'indice è un indice filtrato, si tratta della condizione di filtro, ad esempio SALARY > 30000. Se la condizione di filtro non può essere determinata, si tratta di una stringa vuota. NULL se l'indice non è un indice filtrato, non può essere determinato se l'indice è un indice filtrato o TYPE è SQL_TABLE_STAT.

Se la riga nel set di risultati corrisponde a una tabella, il driver imposta type su SQL_TABLE_STAT e imposta NON_UNIQUE, INDEX_QUALIFIER, INDEX_NAME, ORDINAL_POSITION, COLUMN_NAME e ASC_OR_DESC su NULL. Se CARDINALITY o PAGES non sono disponibili dall'origine dati, il driver li imposta su NULL.

Esempio di codice

Per un esempio di codice di una funzione simile, vedere SQLColumns.

Funzioni correlate

Per informazioni su	Vedere
Associazione di un buffer a una colonna in un set di risultati	Funzione SQLBindCol
Annullamento dell'elaborazione delle istruzioni	Funzione SQLCancel
Recupero di una singola riga o di un blocco di dati in una direzione forward-only.	Funzione SQLFetch
Recupero di un blocco di dati o scorrimento di un set di risultati	Funzione SQLFetchScroll
Restituzione delle colonne di chiavi esterne	Funzione SQLForeignKeys
Restituzione delle colonne di una chiave primaria	Funzione SQLPrimaryKeys

Vedi anche

Riferimento API ODBC
File di intestazione ODBC