SQLStatistics 函式
一致性
引進版本：ODBC 1.0 標準合規性：ISO 92
摘要
SQLStatistics 會擷取單一資料表和與資料表相關聯之索引的統計資料清單。 驅動程式會將資訊當作結果集傳回。
語法
SQLRETURN SQLStatistics(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * TableName,
SQLSMALLINT NameLength3,
SQLUSMALLINT Unique,
SQLUSMALLINT Reserved);
引數
StatementHandle
[輸入]語句控制碼。
CatalogName
[輸入]目錄名稱。 如果驅動程式支援某些資料表的目錄，但不支援其他資料表，例如當驅動程式從不同的 DBMS 擷取資料時，空字串 （「」） 表示沒有目錄的資料表。 CatalogName 不能包含字串搜尋模式。
如果 SQL_ATTR_METADATA_ID 語句屬性設定為 SQL_TRUE， 則 CatalogName 會被視為識別碼，而且其大小寫並不重要。 如果它是SQL_FALSE， CatalogName 是一般引數;它會以常值方式處理，而且其大小寫很重要。 如需詳細資訊，請參閱目錄函式中的引數。
NameLength1
[輸入]*CatalogName 的 字元長度。
SchemaName
[輸入]架構名稱。 如果驅動程式支援某些資料表的架構，但不支援其他資料表，例如當驅動程式從不同的 DBMS 擷取資料時，空字串 （「」） 表示沒有架構的資料表。 SchemaName 不能包含字串搜尋模式。
如果 SQL_ATTR_METADATA_ID 語句屬性設定為 SQL_TRUE，則 SchemaName 會被視為識別碼， 而且其大小寫並不重要。 如果它是SQL_FALSE， SchemaName 是一般引數;它會以常值方式處理，而且其大小寫很重要。
NameLength2
[輸入]*SchemaName 的 字元長度。
TableName
[輸入]資料表名稱。 這個引數不可以是 Null 指標。 SchemaName 不能包含字串搜尋模式。
如果SQL_ATTR_METADATA_ID語句屬性設定為 SQL_TRUE，則 TableName 會被視為識別碼， 而且其大小寫並不重要。 如果它是SQL_FALSE， TableName 是一般引數;它會以常值方式處理，而且其大小寫很重要。
NameLength3
[輸入]*TableName 的字元長度 。
唯一
[輸入]索引的類型：SQL_INDEX_UNIQUE或SQL_INDEX_ALL。
已保留
[輸入]指出結果集中 CARDINALITY 和 PAGES 資料行的重要性。 下列選項只會影響 CARDINALITY 和 PAGES 資料行的傳回;即使未傳回 CARDINALITY 和 PAGES，也會傳回索引資訊。
SQL_ENSURE要求驅動程式無條件擷取統計資料。 （僅符合開放群組標準的驅動程式，且不支援 ODBC 延伸模組將無法支援SQL_ENSURE。
SQL_QUICK要求驅動程式只有在可從伺服器取得時，才擷取 CARDINALITY 和 PAGES。 在此情況下，驅動程式不會確保值是目前的。 （寫入開放群組標準的應用程式一律會從 ODBC 取得SQL_QUICK行為3.x 相容驅動程式。）
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
當 SQLStatistics 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時 ，藉由呼叫 SQLGetDiagRec 與 handletype 為 SQL_HANDLE_STMT 和 StatementHandle 的 HandleHandle ，即可取得相關聯的 SQLSTATE 值。 下表列出 SQLStatistics 通常傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法 「（DM）」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 08S01 | 通訊連結失敗 | 驅動程式與驅動程式連線的資料來源之間的通訊連結在函式完成處理之前失敗。 |
| 24000 | 不正確資料指標狀態 | 已開啟 StatementHandle 上的 資料指標，並 已呼叫 SQLFetch 或 SQLFetchScroll 。 如果 SQLFetch 或 SQLFetchScroll 尚未傳回SQL_NO_DATA，而且如果 SQLFetch 或 SQLFetchScroll 傳回SQL_NO_DATA，驅動程式就會傳回此錯誤。 語句上已開啟 資料指標，但 未呼叫 SQLFetch 或 SQLFetchScroll 。 |
| 40001 | 序列化失敗 | 交易因為與另一個交易發生資源死結而回復。 |
| 40003 | 語句完成未知 | 此函式執行期間相關聯的連接失敗，且無法判斷交易的狀態。 |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳 回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY008 | 作業已取消 | 已針對 StatementHandle 啟用非同步處理。 已呼叫函式，並在完成執行之前， 在 StatementHandle 上 呼叫 SQLCancel 或 SQLCancelHandle ，然後在 StatementHandle 上 再次呼叫函式。 呼叫函式，並在完成執行之前， 從多執行緒應用程式中的不同執行緒呼叫 語句Handle 或 SQLCancelHandle 。 |
| HY009 | 不正確 Null 指標使用 | TableName 引數是 Null 指標。 SQL_ATTR_METADATA_ID語句屬性已設定為 SQL_TRUE、 CatalogName 引數為 null 指標，而且 infoType SQL_CATALOG_NAME 會傳回支援目錄名稱。 （DM） SQL_ATTR_METADATA_ID 語句屬性設定為 SQL_TRUE， 而 SchemaName 引數為 null 指標。 |
| HY010 | 函式順序錯誤 | （DM） 已針對與 StatementHandle 相關聯的連接控制碼呼叫非同步執行函式。 呼叫 SQLStatistics 函式時 ，這個非同步函 式仍在執行中。 （DM） 已針對 StatementHandle 呼叫 SQLExecute 、 SQLExecDirect 或 SQLMoreResults ，並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有資料流程參數的資料之前，會呼叫此函式。 （DM） 呼叫 StatementHandle 的非同步執行函式（而非此函式），並在呼叫此函式時仍在執行中。 （DM） 已針對 StatementHandle 呼叫 SQLExecute 、 SQLExecDirect 、 SQLBulkOperations 或 SQLSetPos ，並傳回SQL_NEED_DATA。 在針對所有資料執行中參數或資料行傳送資料之前，會呼叫此函式。 |
| HY013 | 記憶體管理錯誤 | 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY090 | 不正確字串或緩衝區長度 | （DM） 其中一個名稱長度引數的值小於 0，但不等於SQL_NTS。 其中一個名稱長度引數的值超過對應名稱的最大長度值。 |
| HY100 | 超出範圍的唯一性選項類型 | （DM） 指定了無效 的唯 一值。 |
| HY101 | 精確度選項類型超出範圍 | （DM） 指定了無效 的保留 值。 |
| HY117 | 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式 。 |
| HYC00 | 未實作選擇性功能 | 指定了目錄，而且驅動程式或資料來源不支援目錄。 已指定架構，且驅動程式或資料來源不支援架構。 驅動程式或資料來源不支援SQL_ATTR_CONCURRENCY和SQL_ATTR_CURSOR_TYPE語句屬性的目前設定組合。 SQL_ATTR_USE_BOOKMARKS語句屬性已設定為 SQL_UB_VARIABLE，且SQL_ATTR_CURSOR_TYPE語句屬性已設定為驅動程式不支援書簽的資料指標類型。 |
| HYT00 | 逾時已超過 | 在資料來源傳回要求的結果集之前，查詢逾時期限已過期。 逾時期間是透過 SQLSetStmtAttr 來設定，SQL_ATTR_QUERY_TIMEOUT。 |
| HYT01 | 已超過連線逾時 | 在資料來源回應要求之前，連線逾時期限已過期。 連線逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） 與 StatementHandle 相關聯的驅動程式不支援 函式。 |
| IM017 | 在非同步通知模式中停用輪詢 | 每當使用通知模型時，輪詢就會停用。 |
| IM018 | 尚未呼叫 SQLCompleteAsync ，以完成此控制碼上的先前非同步作業。 | 如果控制碼上的上一個函式呼叫傳回SQL_STILL_EXECUTING且啟用通知模式， 則必須在控制碼上呼叫 SQLCompleteAsync ，才能執行後續處理並完成作業。 |
註解
SQLStatistics 會以標準結果集的形式傳回單一資料表的相關資訊，依NON_UNIQUE、TYPE、INDEX_QUALIFIER、INDEX_NAME和ORDINAL_POSITION排序。 結果集會結合資料表的統計資料資訊（在結果集的 CARDINALITY 和 PAGES 資料行中），以及每個索引的相關資訊。 如需如何使用這項資訊的資訊，請參閱 目錄資料的 使用方式。
若要判斷TABLE_CAT、TABLE_SCHEM、TABLE_NAME和COLUMN_NAME資料行的實際長度，應用程式可以使用SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN、SQL_MAX_TABLE_NAME_LEN和SQL_MAX_COLUMN_NAME_LEN選項呼叫 SQLGetInfo 。
注意
如需 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 |
下表列出結果集中的資料行。 驅動程式可以定義資料行 13 以外的其他資料行（FILTER_CONDITION）。 應用程式應該從結果集結尾倒數，而不是指定明確的序數位置，來存取驅動程式特定的資料行。 如需詳細資訊，請參閱 目錄函 式傳回的資料。
| 資料行名稱 | Column number | 資料類型 | 註解 |
|---|---|---|---|
| TABLE_CAT （ODBC 1.0） | 1 | Varchar | 要套用統計資料或索引之資料表的目錄名稱;如果不適用於資料來源，則為 Null。 如果驅動程式支援某些資料表的目錄，但不支援其他資料表，例如當驅動程式從不同的 DBMS 擷取資料時，它會針對沒有目錄的資料表傳回空字串 （「」）。 |
| TABLE_SCHEM （ODBC 1.0） | 2 | Varchar | 要套用統計資料或索引之資料表的架構名稱;如果不適用於資料來源，則為 Null。 如果驅動程式支援某些資料表的架構，但不支援其他資料表，例如當驅動程式從不同的 DBMS 擷取資料時，它會針對沒有架構的資料表傳回空字串 （「」）。 |
| TABLE_NAME （ODBC 1.0） | 3 | Varchar not Null | 要套用統計資料或索引之資料表的資料表名稱。 |
| NON_UNIQUE （ODBC 1.0） | 4 | Smallint | 指出索引是否不允許重複的值： 如果索引值可以是非統一值，SQL_TRUE。 如果索引值必須是唯一的，SQL_FALSE。 如果 TYPE 為SQL_TABLE_STAT，則會傳回 Null。 |
| INDEX_QUALIFIER （ODBC 1.0） | 5 | Varchar | 用來限定執行 DROP INDEX 之索引名稱的 識別碼;如果資料來源不支援索引限定詞，或 TYPE 為SQL_TABLE_STAT，則會傳回 Null。 如果此資料行中傳回非 Null 值，則必須用來限定 DROP INDEX 語句上的 索引名稱，否則應該使用TABLE_SCHEM來限定索引名稱。 |
| INDEX_NAME （ODBC 1.0） | 6 | Varchar | 索引名稱;如果 TYPE 為SQL_TABLE_STAT，則會傳回 Null。 |
| TYPE （ODBC 1.0） | 7 | Smallint not Null | 傳回的資訊類型： SQL_TABLE_STAT表示資料表的統計資料（在 CARDINALITY 或 PAGES 資料行中）。 SQL_INDEX_BTREE表示 B 型樹狀結構索引。 SQL_INDEX_CLUSTERED表示叢集索引。 SQL_INDEX_CONTENT表示內容索引。 SQL_INDEX_HASHED表示雜湊索引。 SQL_INDEX_OTHER表示另一種類型的索引。 |
| ORDINAL_POSITION （ODBC 1.0） | 8 | Smallint | 索引中的資料行序號（從 1 開始）：如果 TYPE 為SQL_TABLE_STAT，則會傳回 Null。 |
| COLUMN_NAME （ODBC 1.0） | 9 | Varchar | 資料行名稱。 如果資料行是以運算式為基礎，例如 SALARY + BENEFITS，則會傳回運算式;如果無法判斷運算式，則會傳回空字串。 如果 TYPE 為SQL_TABLE_STAT，則會傳回 Null。 |
| ASC_OR_DESC （ODBC 1.0） | 10 | Char(1) | 資料行的排序次序：「A」 表示遞增;「D」 表示遞減;如果資料來源不支援資料行排序次序，或 TYPE 為SQL_TABLE_STAT，則會傳回 Null。 |
| 基數 （ODBC 1.0） | 11 | 整數 | 資料表或索引的基數;如果 TYPE 為 SQL_TABLE_STAT，則為數據表中的資料列數目;如果 TYPE 不是SQL_TABLE_STAT，索引中的唯一值數目;如果資料來源中沒有值，則會傳回 Null。 |
| PAGES （ODBC 1.0） | 12 | 整數 | 用來儲存索引或資料表的頁面數目;如果 TYPE 為 SQL_TABLE_STAT，則為數據表的頁數;如果 TYPE 不是SQL_TABLE_STAT，則為索引的頁數;如果資料來源無法使用值，或不適用於資料來源，則會傳回 Null。 |
| FILTER_CONDITION （ODBC 2.0） | 13 | Varchar | 如果索引是篩選的索引，這是篩選準則，例如 SALARY > 30000;如果無法判斷篩選準則，這是空字串。 如果索引不是篩選的索引，則無法判斷索引是否為篩選索引，或 TYPE 是SQL_TABLE_STAT。 |
如果結果集中的資料列對應至資料表，驅動程式會將 TYPE 設定為 SQL_TABLE_STAT，並將 NON_UNIQUE、INDEX_QUALIFIER、INDEX_NAME、ORDINAL_POSITION、COLUMN_NAME 和 ASC_OR_DESC 設定為 Null。 如果資料來源無法使用 CARDINALITY 或 PAGES，驅動程式會將它們設定為 Null。
程式碼範例
如需類似函式的程式碼範例，請參閱 SQLColumns 。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 將緩衝區系結至結果集中的資料行 | SQLBindCol 函式 |
| 取消語句處理 | SQLCancel 函式 |
| 以正向方向擷取單一資料列或資料區塊。 | SQLFetch 函式 |
| 擷取資料區塊或捲動結果集 | SQLFetchScroll 函式 |
| 傳回外鍵的資料行 | SQLForeignKeys 函式 |
| 傳回主鍵的資料行 | SQLPrimaryKeys 函式 |
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應