SQLStatistics() - 基本表の索引および統計情報を取得する

SQLStatistics() は特定の表の索引情報を取り出します。 また、表およびその表の索引に関連したカーディナリティーとページ数も戻します。情報は、結果セットとして戻されます。 この結果セットは、 照会で生成される結果セットを処理するのと同じ関数を使用して、取り出すことができます。

SQLStatistics() の ODBC 仕様

表 1. SQLStatistics() の仕様
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);

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLStatistics() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 ステートメント・ハンドル。
SQLCHAR * szCatalogName 入力 3 部構成の表名のカタログ修飾子。 これは、NULL ポインターまたは長さゼロのストリングでなければなりません。
SQLSMALLINT cbCatalogName 入力 cbCatalogName の長さ (バイト)。これは、0 に設定する必要があります。
SQLCHAR * szSchemaName 入力 指定した表のスキーマ修飾子。
SQLSMALLINT cbSchemaName 入力 szSchemaName の長さ (バイト)。
SQLCHAR * szTableName 入力 表名。
SQLSMALLINT cbTableName 入力 cbTableName の長さ (バイト)。
SQLUSMALLINT fUnique 入力 戻される索引情報のタイプ。
  • SQL_INDEX_UNIQUE

    ユニーク索引だけが戻されます。

  • SQL_INDEX_ALL

    すべての索引が戻されます。

SQLUSMALLINT fAccuracy 入力 結果セットの CARDINALITY および PAGES 列に、以下の最新情報を 入れるかどうかを指示します。
  • SQL_ENSURE : この値は、今後アプリケーションが最新の統計情報を 要求するときに利用できるよう予約されています。 この値を指定した既存のアプリケーションは、SQL_QUICK と同じ結果を受け取ります。 推奨事項 : 新しいアプリケーションでは、この値を使用しないでください。
  • SQL_QUICK : サーバーでその時点で入手可能な統計が戻されます。この値は現行値でない可能性 がありますが、その値を必ず最新の値にするための試みは行われません。

使用法

SQLStatistics() は、以下の 2 つのタイプの情報を戻します。
  • 表の統計情報 (統計が使用可能な場合)。
    • 下記の表の TYPE 列が SQL_TABLE_STAT に設定された場合は、表の中の行数と 表を保管するためのページ数。
    • TYPE 列が索引を示す場合は、索引の固有の値の個数、および索引を 保管するのに使用されるページ数。
  • 各索引に関する情報。各列は結果セットの 1 行で表されます。 結果セット列 は 表 3 に示してあり、その順序のとおりです。結果セット内の行 は、NON_UNIQUE、TYPE、INDEX_QUALIFIER、INDEX_NAME、 および ORDINAL_POSITION の順序になります。

多くの場合、SQLStatistics() への呼び出しは、システム・カタログに対する複雑な (したがって、コストのかかる) 照会にマップされることになるため、慎重に使用し、呼び出しを繰り返さずに、 結果を保管するようにしてください。

カタログ関数の結果セットの VARCHAR 列は、128 バイトの最大長属性で宣言されて おり、ANSI/ISO SQL 規格 (1992) の制限との整合性があります。Db2® 名の長さは 128 バイトより短いため、アプリケーション では常に 128 バイト (加えて、NUL 終止符) を 出力バッファーに取っておくように選択できます。 あるいは、引数 InfoType を以下のそれぞれの値に 設定して、SQLGetInfo() を呼び出すこともできます。
  • 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() が戻す結果セット の列を示しています。

表 3. 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 索引で重複値が禁止されるかどうかを示します。
  • SQL_TRUE : 索引で重複値が許される場合。
  • SQL_FALSE : 索引値が固有でなければならない場合。
  • この行が SQL_TABLE_STAT (表自体に関する統計情報) である ことが TYPE 列に示されている場合、NULL が戻されます。
5 INDEX_QUALIFIER VARCHAR(128) DROP INDEX ステートメントで索引名を修飾するために使用する ストリング。INDEX_NAME にピリオド (.) を付けると、索引の完全指定になります。
6 INDEX_NAME VARCHAR(128) 索引の名前。 TYPE 列の値が SQL_TABLE_STAT の場合、この列の値は NULL です。
7 TYPE SMALLINT NOT NULL 結果セットのこの行に含まれている情報のタイプを示します。
  • SQL_TABLE_STAT : 表自体に関する統計情報がこの行に含まれている ことを示します。
  • SQL_INDEX_CLUSTERED : 索引に関する情報がこの行に含まれ ており、索引のタイプがクラスター索引であることを示します。
  • SQL_INDEX_HASHED : 索引に関する情報がこの行に含まれており、 索引のタイプがハッシュ索引であることを示します。
  • SQL_INDEX_OTHER : 索引に関する情報がこの行に含まれており、 索引のタイプがクラスター索引またはハッシュ索引以外であることを示します。
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
  • TYPE 列の値が SQL_TABLE_STAT の場合、この列には表の中の行数が 含まれています。
  • TYPE 列の値が SQL_TABLE_STAT でない場合、この列には索引 内の固有値の個数が含まれています。
  • データベース管理システムからの情報が使用できない場合、NULL 値が戻されます。
12 PAGES INTEGER
  • TYPE 列の値が SQL_TABLE_STAT の場合、この列には表を保管するのに 使用するページ数が含まれています。
  • TYPE 列の値が SQL_TABLE_STAT でない場合、この列には索引を保管するのに 使用するページ数が含まれています。
  • データベース管理システムからの情報が使用できない場合、NULL 値が戻されます。
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 ユーティリティーを実行した時刻です。)

戻りコード

SQLStatistics() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 4. SQLStatistics() の SQLSTATE
SQLSTATE 説明 説明
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
24000 カーソル状態が無効です。 カーソルはステートメント・ハンドルでオープンしています。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY010 関数シーケンス・エラーが発生しました。 この関数は、実行時データの操作時に呼び出されました。(すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。)
HY014 これ以上ハンドルがありません。 Db2 ODBC は、内部リソースが少ないためにハンドルを割り振ることができません。
HY090 ストリングまたはバッファーの長さが無効です。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • 名前の長さ引数のうちの 1 つの値は 0 より小さい値でしたが、SQL_NTS と 等しくありません。
  • 名前の長さ引数のうちの 1 つの値が、そのデータ・ソースで サポートされる最大値を超えました。 この最大値は、SQLGetInfo() を使って入手できます。
HY100 固有性オプション・タイプが範囲外です。 無効な fUnique 値が指定されています。
HY101 正確性オプション・タイプが範囲外です。 無効な fAccuracy 値が指定されています。
HYC00 ドライバーは使用できません。 Db2 ODBC は、表名の修飾子として catalog はサポートしていません。

例

以下の例は、表に関連したカーディナリティーと ページ数を戻すアプリケーションを示しています。このアプリケーションは、SQLStatistics() を用いてこの情報を取り出します。
図 1. 表に関するページおよびカーディナリティー情報を印刷するアプリケーション
/* ... */
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");
    }
/* ... */