SQLStatistics 取得一份關於單一資料表及其相關索引的統計資料清單。 驅動程式會將資訊以結果集的形式回傳。
一致性
推出版本：ODBC 1.0 標準合規性：ISO 92
語法
SQLRETURN SQLStatistics(
SQLHSTMT StatementHandle ,
SQLCHAR * CatalogName ,
SQLSMALLINT NameLength1 ,
SQLCHAR * SchemaName ,
SQLSMALLINT NameLength2 ,
SQLCHAR * TableName ,
SQLSMALLINT NameLength3 ,
SQLUSMALLINT Unique ,
SQLUSMALLINT Reserved);
Arguments
StatementHandle
[輸入]語句標題。
目錄名稱
[輸入]目錄名稱。 如果驅動程式支援某些資料表的目錄，但不支援其他資料表，例如當驅動從不同資料庫管理系統（DBMS）取得資料時，空字串""（）表示那些沒有目錄的資料表。
CatalogName 不能包含字串搜尋模式。
如果 SQL_ATTR_METADATA_ID 陳述屬性設為 SQL_TRUE，目錄 名稱 會被視為識別碼，且其案例不重要。 如果是 SQL_FALSE， 目錄名稱 是一個普通的論點;它是字面處理的，且其案例具有重要意義。 欲了解更多資訊，請參閱 目錄函數中的參數。
名稱長度1
[輸入]目錄 名稱字元長度。
結構名稱
[輸入]模式名稱。 如果驅動程式支援某些資料表的結構，但不支援其他資料表，例如當驅動從不同資料庫管理系統（DBMS）取得資料時，空字串（""）表示那些沒有結構的資料表。
SchemaName 不能包含字串搜尋模式。
如果 SQL_ATTR_METADATA_ID 陳述句屬性被設定為 SQL_TRUE， SchemaName 會被視為識別碼，其大小寫不重要。 如果是 SQL_FALSE， SchemaName 是一個普通的論元;它被字面處理，且其情況很重要。
名稱長度2
[輸入] SchemaName 字元長度。
TableName
[輸入]桌名。 這個參數不可能是空指標。 TableName 不能包含字串搜尋模式。
如果 SQL_ATTR_METADATA_ID 陳述句屬性設為 SQL_TRUE， TableName 會被視為識別碼，其大小寫不重要。 如果是 ，TableNameSQL_FALSE是一個普通的論元;它是字面處理的，且其情況具有重要性。
名稱長度3
[輸入] TableName 字元長度。
獨特
[輸入]索引類型： SQL_INDEX_UNIQUE 或 SQL_INDEX_ALL。
保留的
[輸入]表示 和 CARDINALITYPAGES 欄位在結果集中的重要性。 以下選項僅影響 和 PAGES 欄位的回傳CARDINALITY;即使 CARDINALITY 和 PAGES 未回傳，索引資訊仍會回傳。
SQL_ENSURE 請求驅動程式無條件取得統計資料。 （僅符合 Open Group 標準且不支援 ODBC 擴充的驅動程式將無法支援 SQL_ENSURE。）
SQL_QUICK請求驅動程式只有在伺服器上可立即取得 and PAGES 時才會取CARDINALITY回。 在此情況下，驅動程式不會確保這些值是目前的。 （依照 Open Group 標準編寫的應用程式，必然會從符合 ODBC 3.x 的驅動程式中獲得SQL_QUICK行為。）
退貨
SQL_SUCCESS、、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTINGSQL_ERROR、或SQL_INVALID_HANDLE。
Diagnostics
當SQLStatistics回傳 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO時，可透過呼叫 SQLGetDiagRecHandleType 的 SQL_HANDLE_STMT HandleType 與 StatementHandle 的 Handle，獲得相應SQLSTATE的值。 下表列出 SQLSTATE 通常回傳的 SQLStatistics 值，並在函式情境下說明每個值;符號 (DM) 會放在驅動程式管理器對每個 SQLSTATE 回傳的描述之前。 每個值所對應 SQLSTATE 的回傳代碼為 SQL_ERROR，除非另有說明。
| SQLSTATE | 錯誤 | Description |
|---|---|---|
01000 |
一般警告 | 針對駕駛人的資訊訊息。 （函式回傳 SQL_SUCCESS_WITH_INFO。） |
08S01 |
通訊連結故障 | 驅動程式與驅動程式所連接的資料來源之間的通訊連結在函式完成處理前就已失效。 |
24000 |
游標狀態無效 |
StatementHandleSQLFetch 上開啟了一個游標，或SQLFetchScroll是被呼叫過。 如果SQLFetch錯誤出現或SQLFetchScroll未回傳SQL_NO_DATA，驅動管理員會回傳，若或已返回SQL_NO_DATA，則由駕駛SQLFetchSQLFetchScroll回傳。StatementHandle 上有個游標開啟，但 SQLFetchSQLFetchScroll或尚未被呼叫。 |
40001 |
序列化失敗 | 該交易因與另一筆交易發生資源死結而被回滾。 |
40003 |
陳述補全未知 | 該關聯連線在執行此函式時失敗，無法確定交易狀態。 |
HY000 |
一般錯誤 | 發生錯誤時，沒有特定 SQLSTATE 錯誤的定義，也沒有針對實 SQLSTATE 作定義。 *MessageText 緩衝區中回傳的SQLGetDiagRec錯誤訊息描述了錯誤及其原因。 |
HY001 |
記憶體配置錯誤 | 驅動程式無法分配支援執行或完成函式所需的記憶體。 |
HY008 |
行動取消 |
StatementHandle 啟用了非同步處理。 函式被呼叫，且在執行完成 SQLCancel 前，或 SQLCancelHandle 在 StatementHandle 上被呼叫，接著在 StatementHandle 上再次呼叫該函式。函式被呼叫，且在完成執行 SQLCancel 前，或 SQLCancelHandle 在多執行緒應用程式中被呼叫於 StatementHandle 上。 |
HY009 |
空指標的無效使用 |
TableName 參數是空指標。SQL_ATTR_METADATA_ID陳述屬性被設定為 SQL_TRUE，CatalogName 參數為空指標，SQL_CATALOG_NAMEInfoType 回傳支援目錄名稱。（DM） SQL_ATTR_METADATA_ID 陳述句屬性被設定為 SQL_TRUE，而 SchemaName 參數為空指標。 |
HY010 |
函數序列誤差 | （DM） 一個非同步執行的函式被呼叫，用於與 StatementHandle 相關的連接句柄。 當呼叫該函式時 SQLStatistics ，這個非同步函式仍在執行中。（DM） SQLExecute， SQLExecDirect， 或 SQLMoreResults 被呼叫 StatementHandle 並回傳 SQL_PARAM_DATA_AVAILABLE。 此函式在取得所有串流參數資料前就被呼叫。（DM） 一個非同步執行的函式（不是這個）被呼叫用於 StatementHandle ，且在呼叫該函式時仍在執行中。 （DM） SQLExecute， SQLExecDirect， ， SQLBulkOperations， 或 SQLSetPos 被呼叫用於 StatementHandle 並返回 SQL_NEED_DATA。 此函式在所有執行時資料參數或欄位資料傳送前就被呼叫。 |
HY013 |
記憶體管理錯誤 | 函式呼叫無法被處理，因為底層的記憶體物件無法被存取，可能是因為記憶體條件不足。 |
HY090 |
字串或緩衝區長度無效 | （DM） 其中一個名稱長度參數的值小於 0，但不等 SQL_NTS於 。其中一個名稱長度參數的值超過了對應名稱的最大長度值。 |
HY100 |
唯一性選項類型超出範圍 | （DM） 指定了一個無效 的 Unique 值。 |
HY101 |
準確度選項類型超出範圍 | （DM） 指定了一個無效 的保留 值。 |
HY117 |
連線因交易狀態不明而中斷。 僅允許斷開與唯讀功能。 | （DM） 欲了解更多關於暫停狀態的資訊，請參閱 SQLEndTran 函式。 |
HYC00 |
未實作的可選功能 | 指定了一個目錄，但驅動程式或資料來源不支援目錄。 已經指定了結構，但驅動程式或資料來源不支援結構。 驅動程式或資料來源不支援目前 和 SQL_ATTR_CURSOR_TYPE 語句屬性SQL_ATTR_CONCURRENCY的組合。SQL_ATTR_USE_BOOKMARKS陳述屬性被設定為 SQL_UB_VARIABLE，陳述SQL_ATTR_CURSOR_TYPE符屬性設定為驅動程式不支援書籤的游標類型。 |
HYT00 |
暫停結束 | 查詢逾時期在資料來源回傳請求的結果集前已過期。 超時時間為 SQLSetStmtAttr， SQL_ATTR_QUERY_TIMEOUT。 |
HYT01 |
已超過連線逾時 | 連線逾時期在資料來源回應請求前就已結束。 連線逾時時間由 ， SQLSetConnectAttrSQL_ATTR_CONNECTION_TIMEOUT設定。 |
IM001 |
驅動程式不支援這個功能 | （DM） 與 StatementHandle 相關的驅動程式不支援該函式。 |
IM017 |
在非同步通知模式下，輪詢功能被停用 | 每當使用通知模式時，輪詢功能會被關閉。 |
IM018 |
SQLCompleteAsync 尚未被呼叫來完成之前對此柄的非同步操作。 |
如果先前對句柄的函式呼叫回傳 SQL_STILL_EXECUTING 且啟用通知模式， SQLCompleteAsync 則必須呼叫該句柄以進行後處理並完成操作。 |
評論
SQLStatistics以標準結果集形式回傳單一資料表的資訊，排序依 NON_UNIQUE、 TYPE、 INDEX_QUALIFIERINDEX_NAMEORDINAL_POSITION和 。 結果集結合了資料表的統計資訊（在 CARDINALITY 結果集的 和 PAGES 欄位中）與每個索引的資訊。 關於這些資訊如何被使用，請參閱 目錄資料的用途。
為了確定 、 、 和 欄位的TABLE_CAT實際長度，應用程式可以呼叫 SQLGetInfo 、 SQL_MAX_CATALOG_NAME_LENSQL_MAX_SCHEMA_NAME_LEN、 SQL_MAX_TABLE_NAME_LEN和 SQL_MAX_COLUMN_NAME_LEN 選項。COLUMN_NAMETABLE_NAMETABLE_SCHEM
備註
欲了解更多關於 ODBC 目錄函式的一般用途、參數及回傳資料，請參見 目錄函式。
以下欄位已更名為 ODBC 3.x。 欄位名稱的變更不會影響向下相容性，因為應用程式是以欄位編號綁定的。
| ODBC 2.0 欄位 | ODBC 3.x 欄 |
|---|---|
TABLE_QUALIFIER |
TABLE_CAT |
TABLE_OWNER |
TABLE_SCHEM |
SEQ_IN_INDEX |
ORDINAL_POSITION |
COLLATION |
ASC_OR_DESC |
下表列出結果集中的欄位。 驅動程式可定義第 13FILTER_CONDITION 欄（）之外的其他欄位。 應用程式應透過從結果集末端倒數，而非指定明確的序數位置，從而取得驅動程式專屬欄位的存取權。 欲了解更多資訊，請參閱 目錄函數回傳的資料。
| 欄位名稱 | 欄號 | 數據類型 | 評論 |
|---|---|---|---|
TABLE_CAT （ODBC 1.0） |
1 | varchar | 統計量或指數所適用的表格目錄名稱; NULL 若不適用於資料來源。 如果驅動程式支援某些資料表的目錄，但不支援其他資料表，例如當驅動從不同資料庫管理系統（DBMS）取得資料時，對於沒有目錄的資料表，則會回傳空字串（""）。 |
TABLE_SCHEM （ODBC 1.0） |
2 | varchar | 統計量或指標所適用的表格結構名稱; NULL 若不適用於資料來源。 如果驅動程式支援某些資料表的結構，但不支援其他資料表，例如當驅動從不同資料庫管理系統（DBMS）取得資料時，對於沒有結構的資料表，則會回傳空字串（""）。 |
TABLE_NAME （ODBC 1.0） |
3 |
瓦爾查 爾不 NULL |
統計量或指數所適用的表格名稱。 |
NON_UNIQUE （ODBC 1.0） |
4 | smallint | 表示索引是否允許重複值：SQL_TRUE 如果索引值可以是非唯一的。SQL_FALSE 如果索引值必須是唯一的。NULL若 是 SQL_TABLE_STAT，則TYPE返回 。 |
INDEX_QUALIFIER （ODBC 1.0） |
5 | varchar | 用於限定索引名稱DROP INDEX的識別碼，若資料來源不支援索引限定符，或TYPE若為 ，則回傳 ;NULL;若索引限定符為 SQL_TABLE_STAT。 若此欄位回傳非空值，必須用來限定語句上的 DROP INDEX 索引名稱;否則，應用 來 TABLE_SCHEM 限定索引名稱。 |
INDEX_NAME （ODBC 1.0） |
6 | varchar | 索引名稱;NULL若 是 SQL_TABLE_STAT，則TYPE返回 。 |
TYPE （ODBC 1.0） |
7 |
小小的NULL |
回傳資訊類型：SQL_TABLE_STAT表示表格中的統計量（在 or PAGES 欄位CARDINALITY）。SQL_INDEX_BTREE 表示 B 樹索引。SQL_INDEX_CLUSTERED 表示一個聚集指數。SQL_INDEX_CONTENT 表示內容索引。SQL_INDEX_HASHED 表示一個雜湊索引。SQL_INDEX_OTHER 表示另一種類型的索引。 |
ORDINAL_POSITION （ODBC 1.0） |
8 | smallint | 索引中的欄位序列號（以 1 開頭）;NULL若 是 SQL_TABLE_STAT，則TYPE返回 。 |
COLUMN_NAME （ODBC 1.0） |
9 | varchar | 資料行名稱。 若欄位基於某個表達式，例如 SALARY + BENEFITS，則回傳該表達式;若無法確定該表達式，則回傳空字串。
NULL若 是 SQL_TABLE_STAT，則TYPE返回 。 |
ASC_OR_DESC （ODBC 1.0） |
10 | char(1) | 欄位排序順序：「A」代表遞增;「D」代表下降; NULL 若資料來源不支援欄位排序序列，或 TYPE 為 ， SQL_TABLE_STAT則回傳 。 |
CARDINALITY （ODBC 1.0） |
11 | integer | 表格或索引的基數;如果 TYPE 是 SQL_TABLE_STAT，則是表格中的列數;如果 TYPE 不是 SQL_TABLE_STAT，則是索引中唯一值的數量; NULL 如果該值無法從資料來源取得，則會回傳。 |
PAGES （ODBC 1.0） |
12 | integer | 用於儲存索引或表格的頁數;如果 TYPE 是 SQL_TABLE_STAT，則為表格的頁數;如果 TYPE 不是 SQL_TABLE_STAT，則為索引的頁數; NULL 如果該值無法從資料來源取得，或若不適用於該資料來源，則回傳。 |
FILTER_CONDITION （ODBC 2.0） |
13 | varchar | 如果索引是過濾索引，這就是過濾條件，例如 SALARY > 30000;如果無法確定過濾條件，則為空字串。NULL 若索引非過濾索引，則無法判斷該索引是否為過濾索引，或 TYPE 為 SQL_TABLE_STAT。 |
若結果集中的列對應於一個表格，驅動程式則將 TYPE ， SQL_TABLE_STATNON_UNIQUEINDEX_QUALIFIER， INDEX_NAME， COLUMN_NAMEORDINAL_POSITIONASC_OR_DESC 設為 。NULL 如果CARDINALITYPAGES資料來源中沒有或沒有，驅動程式會將它們設為 NULL。
程式碼範例
類似函式的程式碼範例請參見 SQLColumns 函式。
相關功能
| 如需下列資訊 | 文章 |
|---|---|
| 將緩衝區綁定到結果集中的欄位 | SQLBindCol 函式 |
| 取消帳單處理 | SQLCancel 函式 |
| 以僅向前向的方向擷取單一列或資料區塊。 | SQLFetch 函式 |
| 擷取資料區塊或捲動結果集 | SQLFetchScroll 函式 |
| 返回外鍵欄位 | SQLForeignKeys 函式 |
| 返回主鍵的欄位 | SQLPrimaryKeys 函式 |