CLI の手引きおよび解説書

SQLStatistics - 基本表の索引および統計情報の入手

目的


仕様: DB2 CLI 2.1 ODBC 1.0  

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

構文

SQLRETURN   SQLStatistics    (
                SQLHSTMT          StatementHandle,   /* hstmt */
                SQLCHAR      FAR *CatalogName,       /* szCatalogName */
                SQLSMALLINT       NameLength1,       /* cbCatalogName */
                SQLCHAR      FAR *SchemaName,        /* szSchemaName */
                SQLSMALLINT       NameLength2,       /* cbSchemaName */
                SQLCHAR      FAR *TableName,         /* szTableName */
                SQLSMALLINT       NameLength3,       /* cbTableName */
                SQLUSMALLINT      Unique,            /* fUnique */
                SQLUSMALLINT      Reserved);         /* fAccuracy */

関数引き数


表 174. SQLStatistics 引き数
データ・タイプ 引き数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル。
SQLCHAR * CatalogName 入力 3 つの部分から成る表名のカタログ修飾子。これは、ヌル・ポインターまたは長さゼロのストリングでなければなりません。
SQLSMALLINT NameLength1 入力 NameLength1 の長さ。これは、0 に設定する必要があります。
SQLCHAR * SchemaName 入力 指定した表のスキーマ修飾子。
SQLSMALLINT NameLength2 入力 SchemaName の長さ。
SQLCHAR * TableName 入力 表名。
SQLSMALLINT NameLength3 入力 NameLength3 の長さ。
SQLUSMALLINT 固有 入力 戻される索引情報のタイプ。
  • SQL_INDEX_UNIQUE

    固有索引だけを戻します。

  • SQL_INDEX_ALL

    すべての索引を戻します。

SQLUSMALLINT 予約済み。 入力 結果セットの CARDINALITY および PAGES 列に、以下の最新情報を含むかどうかを示します。
  • SQL_ENSURE : この値は、今後アプリケーションが最新の統計情報を要求するときの利用のために予約されています。 新しいアプリケーションは、この値を使用してはなりません。 この値を指定する既存のアプリケーションは、SQL_QUICK と同じ結果を受け取ります。
  • SQL_QUICK : サーバーで読み取りに使用できる統計が戻されます。値は現行値でない場合があり、それらの値が最新の値であるかどうかを確認することは試行されません。

使用法

SQLStatistics() は、次の 2 つのタイプの情報を戻します。

ほとんどの場合、SQLStatistics() への呼び出しはシステム・カタログに対して複雑で、それゆえに高価な照会へとマップされるので、使用を節約する必要があります。それで、呼び出しを繰り返すよりも、結果を保管しておくほうが良いでしょう。

カタログ関数の結果セットの VARCHAR 列は、SQL92 の制限に従うように、 128 の最大長属性で宣言されています。 DB2 名は 128 文字未満なので、アプリケーションは、出力バッファー用に 128 文字 (およびヌル終止符) を常にとっておくか、あるいは、接続している DBMS がサポートしている TABLE_CAT、TABLE_SCHEM、TABLE_NAME、および COLUMN_NAME 列の実際の長さを判別するために、 SQL_MAX_CATALOG_NAME_LEN、 SQL_MAX_OWNER_SCHEMA_LEN、SQL_MAX_TABLE_NAME_LEN、および SQL_MAX_COLUMN_NAME_LEN を使用して選択的に SQLGetInfo() を呼び出すようにすることができます。

将来のリリースでは、列が新たに追加されたり、既存の列の名前が変更されたりする可能性はありますが、現行の列の位置が変更されることはありません。

SQLStatistics で戻される列

列 1 TABLE_CAT (VARCHAR(128))
これは常にヌルです。

列 2 TABLE_SCHEM (VARCHAR(128))
TABLE_NAME を含むスキーマの名前。

列 3 TABLE_NAME (VARCHAR(128) 非 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 非 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 ユニバーサル・データベースでは、RUNSTATS コマンドの最終実行時にします。)

戻りコード

診断


表 175. SQLStatistics SQLSTATE
SQLSTATE 説明 解説
24000 カーソル状態が無効です。 カーソルはすでに、ステートメント・ハンドル上にオープンされています。
40003 08S01 通信リンクに障害が起きました。 アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。
HY001 メモリーの割り振り失敗です。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY008 操作が取り消しになりました。

非同期処理が StatementHandle に対して使用可能になりました。関数が呼び出され、その実行が完了する前に、 SQLCancel()StatementHandle で呼び出されました。そして、関数が再び StatementHandle で呼び出されました。

関数が呼び出され、その実行が完了する前に、 SQLCancel() が複数スレッドのアプリケーション内の別のスレッドから、 StatementHandle で呼び出されました。

HY009 引き数値が無効です。 TableName は NULL です。
HY010 関数の順序エラーです。

実行時データ (SQLParamData()SQLPutData()) 操作中に、関数が呼び出されました。

BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。

非同期実行関数 (この関数ではない) が StatementHandle で呼び出され、この関数は、呼び出し時に依然実行中でした。

HY014 もはやハンドルはありません。 DB2 CLI は、内部資源が原因でハンドルを割り当てることができませんでした。
HY090 ストリングまたはバッファー長が無効です。 名前の長さ引き数のうちの 1 つの値は 0 より小さい値でしたが、 SQL_NTS と等しくありませんでした。

名前の長さ引き数のうちの 1 つの有効値は、そのデータ・ソースについてサポートされる最大値を超えました。 SQLGetInfo() 関数を呼び出して、サポートされる最大値を取得することができます。

HY100 固有オプション・タイプが範囲外です。 無効な Unique 値を指定しました。
HY101 正確度オプション・タイプが範囲外です。 無効な Reserved 値を指定しました。
HYC00 ドライバーが機能していません。 DB2 CLI は、表名の修飾子としてカタログ をサポートしません。
HYT00 タイムアウトになりました。 データ・ソースが結果セットを返す前に、タイムアウト期間が満了しました。タイムアウトは、 Windows 3.1 や Macintosh System 7 のようなマルチタスクではないシステム上でのみサポートされています。タイムアウト期間は、 SQLSetConnectAttr() の SQL_ATTR_QUERY_TIMEOUT 属性を使用して設定することができます。

制約

なし。

CLI サンプル tbinfo.c

(ここで完全サンプル tbinfo.c を使用することもできます 。)

/* From the CLI sample TBINFO.C */
/* ... */
    /* call SQLStatistics */
    printf("\n    Call SQLStatistics for:\n");
    printf("        tbSchema = %s\n", tbSchema);
    printf("        tbName = %s\n", tbName);
    sqlrc = SQLStatistics( hstmt, NULL, 0,
                           tbSchema, SQL_NTS,
                           tbName, SQL_NTS,
                           SQL_INDEX_UNIQUE, SQL_QUICK);
 
 

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]