SQLStatistics() - 基本表の索引および統計情報を取得する
SQLStatistics() は特定の表の索引情報を取り出します。 また、表およびその表の索引に関連したカーディナリティーとページ数も戻します。情報は、結果セットとして戻されます。 この結果セットは、 照会で生成される結果セットを処理するのと同じ関数を使用して、取り出すことができます。
SQLStatistics() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 1.0 | あり | なし |
構文
SQLRETURN SQLStatistics (SQLHSTMT hstmt,
SQLCHAR FAR *szCatalogName,
SQLSMALLINT cbCatalogName,
SQLCHAR FAR *szSchemaName,
SQLSMALLINT cbSchemaName,
SQLCHAR FAR *szTableName,
SQLSMALLINT cbTableName,
SQLUSMALLINT fUnique,
SQLUSMALLINT fAccuracy);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | hstmt | 入力 | ステートメント・ハンドル。 |
| SQLCHAR * | szCatalogName | 入力 | 3 部構成の表名のカタログ修飾子。 これは、NULL ポインターまたは長さゼロのストリングでなければなりません。 |
| SQLSMALLINT | cbCatalogName | 入力 | cbCatalogName の長さ (バイト)。これは、0 に設定する必要があります。 |
| SQLCHAR * | szSchemaName | 入力 | 指定した表のスキーマ修飾子。 |
| SQLSMALLINT | cbSchemaName | 入力 | szSchemaName の長さ (バイト)。 |
| SQLCHAR * | szTableName | 入力 | 表名。 |
| SQLSMALLINT | cbTableName | 入力 | cbTableName の長さ (バイト)。 |
| SQLUSMALLINT | fUnique | 入力 | 戻される索引情報のタイプ。
|
| SQLUSMALLINT | fAccuracy | 入力 | 結果セットの CARDINALITY および PAGES 列に、以下の最新情報を
入れるかどうかを指示します。
|
使用法
- 表の統計情報 (統計が使用可能な場合)。
- 下記の表の TYPE 列が SQL_TABLE_STAT に設定された場合は、表の中の行数と 表を保管するためのページ数。
- TYPE 列が索引を示す場合は、索引の固有の値の個数、および索引を 保管するのに使用されるページ数。
- 各索引に関する情報。各列は結果セットの 1 行で表されます。 結果セット列 は 表 3 に示してあり、その順序のとおりです。結果セット内の行 は、NON_UNIQUE、TYPE、INDEX_QUALIFIER、INDEX_NAME、 および ORDINAL_POSITION の順序になります。
多くの場合、SQLStatistics() への呼び出しは、システム・カタログに対する複雑な (したがって、コストのかかる) 照会にマップされることになるため、慎重に使用し、呼び出しを繰り返さずに、 結果を保管するようにしてください。
- SQL_MAX_CATALOG_NAME_LEN -- 接続されたデータベース管理システムがサポートする TABLE_CAT 列の長さを判別
- SQL_MAX_SCHEMA_NAME_LEN -- 接続されたデータベース管理システムがサポートする TABLE_SCHEM 列の長さを判別
- SQL_MAX_TABLE_NAME_LEN -- 接続されたデータベース管理システムがサポートする TABLE_NAME 列の長さを判別
- SQL_MAX_COLUMN_NAME_LEN -- 接続されたデータベース管理システムがサポートする COLUMN_NAME 列の長さを判別
将来のリリースでは、列が新たに追加されたり、既存の列の名前が 変更される可能性はありますが、現行の列の位置が変更になることはありま せん。次の表は、現在、SQLStatistics() が戻す結果セット の列を示しています。
| 列番号 | 列名 | データ・タイプ | 説明 |
|---|---|---|---|
| 1 | TABLE_CAT | VARCHAR(128) | これは常に NULL です。 |
| 2 | TABLE_SCHEM | VARCHAR(128) | TABLE_NAME を含むスキーマの名前。 |
| 3 | TABLE_NAME | VARCHAR(128) NOT NULL | 表の名前。 |
| 4 | NON_UNIQUE | SMALLINT | 索引で重複値が禁止されるかどうかを示します。
|
| 5 | INDEX_QUALIFIER | VARCHAR(128) | DROP INDEX ステートメントで索引名を修飾するために使用する ストリング。INDEX_NAME にピリオド (.) を付けると、索引の完全指定になります。 |
| 6 | INDEX_NAME | VARCHAR(128) | 索引の名前。 TYPE 列の値が SQL_TABLE_STAT の場合、この列の値は NULL です。 |
| 7 | TYPE | SMALLINT NOT NULL | 結果セットのこの行に含まれている情報のタイプを示します。
|
| 8 | ORDINAL_POSITION | SMALLINT | 名前が INDEX_NAME 列に示されている索引内の列の順序を表す 位置。TYPE 列の値が SQL_TABLE_STAT の場合、この列について NULL 値が戻されます。 |
| 9 | COLUMN_NAME | VARCHAR(128) | 索引内の列の名前。TYPE 列の値が SQL_TABLE_STAT の場合、この列について NULL 値が戻されます。 |
| 10 | ASC_OR_DESC | CHAR(1) | 列のソート・シーケンス (昇順の場合は A、降順の 場合は D)。TYPE 列の値が SQL_TABLE_STAT の場合、NULL 値が戻されます。 |
| 11 | CARDINALITY | INTEGER |
|
| 12 | PAGES | INTEGER |
|
| 13 | FILTER_CONDITION | VARCHAR(128) | この索引がフィルタリングされた索引の場合、この列はフィルター条件と なります。Db2 サーバーはフィルタリングされた索引をサポートしないため、常に NULL が戻されます。TYPE が SQL_TABLE_STAT である場合にも、NULL が戻されます。 |
表の統計を含む結果セット内の行の場合 (TYPE が SQL_TABLE_STAT に 設定されている場合)、NON_UNIQUE、INDEX_QUALIFIER、INDEX_NAME、 ORDINAL_POSITION、COLUMN_NAME、および ASC_OR_DESC の列の値 が NULL 設定されます。 CARDINALITY 情報または PAGES 情報を判別できない場合、これらの 列について NULL が戻されます。
重要: SQLERRD(3) および SQLERRD(4) フィールドに戻される情報の正確性は、 ステートメント内のパラメーター・マーカーや式の使用法などのさまざまな要素によって異なります。 制御できる主な要素は、データベース統計の正確性です。 つまり、統計の最終更新日時です。(例えば、Db2 for z/OS® ODBC では、 最後に RUNSTATS ユーティリティーを実行した時刻です。)
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 08S01 | 通信リンクに障害が起きました。 | 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。 |
| 24000 | カーソル状態が無効です。 | カーソルはステートメント・ハンドルでオープンしています。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
| HY010 | 関数シーケンス・エラーが発生しました。 | この関数は、実行時データの操作時に呼び出されました。(すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。) |
| HY014 | これ以上ハンドルがありません。 | Db2 ODBC は、内部リソースが少ないためにハンドルを割り振ることができません。 |
| HY090 | ストリングまたはバッファーの長さが無効です。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| HY100 | 固有性オプション・タイプが範囲外です。 | 無効な fUnique 値が指定されています。 |
| HY101 | 正確性オプション・タイプが範囲外です。 | 無効な fAccuracy 値が指定されています。 |
| HYC00 | ドライバーは使用できません。 | Db2 ODBC は、表名の修飾子として catalog はサポートしていません。 |
例
/* ... */
SQLRETURN
list_stats(SQLHDBC hdbc, SQLCHAR *schema, SQLCHAR *tablename )
{
/* ... */
rc = SQLStatistics(hstmt, NULL, 0, schema, SQL_NTS,
tablename, SQL_NTS, SQL_INDEX_UNIQUE, SQL_QUICK);
rc = SQLBindCol(hstmt, 4, SQL_C_SHORT,
&non_unique, 2, &non_unique_ind);
rc = SQLBindCol(hstmt, 6, SQL_C_CHAR,
index_name.s, 129, &index_name.ind);
rc = SQLBindCol(hstmt, 7, SQL_C_SHORT,
&type, 2, &type_ind);
rc = SQLBindCol(hstmt, 9, SQL_C_CHAR,
column_name.s, 129, &column_name.ind);
rc = SQLBindCol(hstmt, 11, SQL_C_LONG,
&cardinality, 4, &card_ind);
rc = SQLBindCol(hstmt, 12, SQL_C_LONG,
&pages, 4, &pages_ind);
printf("Statistics for
while ((rc = SQLFetch(hstmt)) == SQL_SUCCESS)
{ if (type != SQL_TABLE_STAT)
{ printf(" Column: %-18s Index Name: %-18s¥n",
column_name.s, index_name.s);
}
else
{ printf(" Table Statistics:¥n");
}
if (card_ind != SQL_NULL_DATA)
printf(" Cardinality =
else
printf(" Cardinality = (Unavailable)");
if (pages_ind != SQL_NULL_DATA)
printf(" Pages =
else
printf(" Pages = (Unavailable)¥n");
}
/* ... */