SQLTables() - 表情報を取得する

SQLTables() は、接続しているデータ・ソースのシステム・カタログに保管されている表名と関連情報のリストを戻します。表名のリストが結果セットとして戻されます。この結果セットは、 照会で生成される結果セットを処理するのと同じ関数を使用して、取り出すことができます。

SQLTables() の ODBC 仕様

表 1. SQLTables() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
1.0 あり なし

構文

SQLRETURN   SQLTables        (SQLHSTMT          hstmt,
                              SQLCHAR     FAR   *szCatalogName,
                              SQLSMALLINT       cbCatalogName,
                              SQLCHAR     FAR   *szSchemaName,
                              SQLSMALLINT       cbSchemaName,
                              SQLCHAR     FAR   *szTableName,
                              SQLSMALLINT       cbTableName,
                              SQLCHAR     FAR   *szTableType,
                              SQLSMALLINT       cbTableType);

関数の引数

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

表 2. SQLTables() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 ステートメント・ハンドル。
SQLCHAR * szCatalogName 入力 結果セットを修飾するためのパターン値 を入れることが できるバッファー。 カタログ は、3 部構成の表名の最初の部分です。

これは、NULL ポインターまたは長さゼロのストリングでなければなりません。

SQLSMALLINT cbCatalogName 入力 szCatalogName の長さ (バイト)。 これは、0 に設定する必要があります。
SQLCHAR * szSchemaName 入力 スキーマ名で結果セットを修飾するためのパターン値 を入れることができるバッファー。
SQLSMALLINT cbSchemaName 入力 szSchemaName の長さ (バイト)。
SQLCHAR * szTableName 入力 表名によって結果セットを修飾するパターン値 を入れることができるバッファー。
SQLSMALLINT cbTableName 入力 szTableName の長さ (バイト)。
SQLCHAR * szTableType 入力 表タイプで結果セットを修飾するための値リスト を入 れることができるバッファー。

値のリストは、対象の表タイプに関する、コンマで区切られ、単一 引用符で囲まれた大文字の値のリストです。

変更の始まり有効な表タイプ ID には、TABLE、VIEW、SYSTEM TABLE、ALIAS、SYNONYM、GLOBAL TEMPORARY TABLE、AUXILIARY TABLE、MATERIALIZED QUERY TABLE、または ACCEL-ONLY TABLE があります。変更の終わり

SYSTEM TABLE を指定すると、システム表とシステム・ビュー (存在する場合) の両方が戻されます。

SQLSMALLINT cbTableType 入力 szTableType のサイズ。

引数 szCatalogName、szSchemaName、および szTableName は 検索パターンを受け入れることに注意してください。

使用法

表の情報は、それぞれの表が結果セットの 1 行で表される結果セットとして戻されます。 アプリケーションは、リスト内の表で使用できるアクセスのタイプを判別 するために、SQLTablePrivileges() を呼び出すことができます。 それ以外の場合には、SELECT 特権が付与されていない表をユーザーが 選択した状態も、アプリケーションで扱えるようにしておく必要があります。

スキーマのリストのみの取得をサポートするには、次の ようにして、引数 szSchemaName に特別な意味構造を適用することができます。 すなわち、szSchemaName は単一のパーセント (%) 文字が入っている ストリングで、szCatalogName と szTableName が 空ストリングの場合、結果セットにはデータ・ソースで有効なスキーマの リストが入ります。

szTableType が単一のパーセント文字 (%) で あり、szCatalogName、szSchemaName、および szTableName が 空ストリングの場合、結果セットはデータ・ソースの有効な表タイプのリストを含むことになり ます。(TABLE_TYPE 列以外のすべての列に、NULL 値が含まれます。)

szTableType が空ストリングでない場合、その中には対象のタイプの、コンマで区切られた大文字の値のリストを含んでいる必要があります。 それぞれの値は単一引用符で囲んでも、単一引用符なしでも構いません。 例えば、"'TABLE','VIEW'" または "TABLE,VIEW" のようになります。 データ・ソースが指定された表タイプをサポートしていない場合、あるいは認識しない場合は、 そのタイプについては何も戻されません。

アプリケーションが引数 szSchemaName、szTableName、および szTableType の一部またはすべてに NULL ポインターを用いて SQLTables() を呼び出す場合、SQLTables() は、返される結果セットを制限しません。 大量のオブジェクトを含む一部のデータ・ソースの場合、大きな結果セットが返され、取り出し時間は非常に長くなってしまいます。 Db2® ODBC 初期化ファイルで初期化キーワード SCHEMALIST、SYSSCHEMA、または TABLETYPE を指定することにより、結果セットのサイズおよび取り出し時間を短縮することができます。 SQLTables() が szSchemaName および szTableType に NULL ポインターを提供すると、それらの初期化キーワードは、結果セットを制限します。 SQLTables() が szSchemaName または szTableType に NULL ポインターを提供しない場合、Db2 ODBC 初期化ファイルの関連付けられているキーワード仕様は使用されません。

SQLTables() から戻される結果セットには、表 3 にリストされている列がそこに示されて いる順序で含まれます。行は TABLE_TYPE、TABLE_CAT、 TABLE_SCHEM、および TABLE_NAME の順序になっています。

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

カタログ関数の結果セットの 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 列の長さを判別

将来のリリースでは、列が新たに追加されたり、既存の列の名前が 変更される可能性はありますが、現行の列の位置が変更されることはありま せん。次の表は、現在、SQLTables() が戻す結果セット の列を示しています。

表 3. SQLTables() によって戻される列
列名 データ・タイプ 説明
TABLE_CAT VARCHAR(128) TABLE_SCHEM を含むカタログの名前。この列には、NULL 値が含まれます。
TABLE_SCHEM VARCHAR(128) TABLE_NAME を含むスキーマの名前。
TABLE_NAME VARCHAR(128) 表、ビュー、別名、同義語のいずれかの名前。
TABLE_TYPE VARCHAR(128) TABLE_NAME 列のオブジェクトのタイプを識別します。 変更の始まりTABLE_TYPE は、ストリング値 'TABLE'、'VIEW'、'INOPERATIVE VIEW'、'SYSTEM TABLE'、'ALIAS'、'SYNONYM'、'GLOBAL TEMPORARY TABLE'、'AUXILIARY TABLE'、 'MATERIALIZED QUERY TABLE'、または 'ACCEL-ONLY TABLE' です。'ACCEL-ONLY TABLE' は拡張表タイプであり、初期化キーワード EXTENDEDTABLEINFO が 1 に設定されている場合にのみ返されます。 変更の終わり
REMARKS VARCHAR(762) 表に関する記述情報が含まれています。
変更の始まりTEMPORAL_TABLE_TYPE変更の終わり 変更の始まりVARCHAR(11)変更の終わり 変更の始まりテンポラル表のタイプが含まれます。可能な値は、以下のとおりです。
SYSTEM
システム期間テンポラル表。
APPLICATION
アプリケーション期間テンポラル表。
BITEMPORAL
バイテンポラル表。
空ストリング
テンポラル表ではありません。

初期化キーワード EXTENDEDTABLEINFO が 1 に設定される場合にのみ、結果セットにこの列が含まれます。

変更の終わり
変更の始まりIS_ACCELERATED変更の終わり 変更の始まりVARCHAR(3)変更の終わり 変更の始まり表が加速表であるかどうかを示します。可能な値は YES または NO です。

初期化キーワード EXTENDEDTABLEINFO が 1 に設定される場合にのみ、結果セットにこの列が含まれます。

変更の終わり
変更の始まりACCEL_ARCHIVE_STATUS変更の終わり 変更の始まりCHAR(1)変更の終わり 変更の始まりアクセラレーター・データベースの表のアーカイブ状況が含まれます。可能な値とその意味については、SYSACCEL.SYSACCELERATEDTABLES 表の ARCHIVE 列の記述を参照してください。

初期化キーワード EXTENDEDTABLEINFO が 1 に設定される場合にのみ、結果セットにこの列が含まれます。

変更の終わり
変更の始まりIS_ARCHIVE_ENABLED変更の終わり 変更の始まりVARCHAR(3)変更の終わり 変更の始まり表がアーカイブ使用可能表であるかどうかを示します。可能な値は YES または NO です。

初期化キーワード EXTENDEDTABLEINFO が 1 に設定される場合にのみ、結果セットにこの列が含まれます。

変更の終わり

戻りコード

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

診断

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

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

例

以下の例は、SQLTables() を使用して、検索パターンに一致する 表名情報の結果セットを生成するアプリケーションを示しています。その他の例については、『環境情報およびデータ・ソース情報を照会するための関数』を参照してください。
図 1. 表名情報の結果セットを戻すアプリケーション
/* ... */
SQLRETURN init_tables(SQLHDBC hdbc )
{
    SQLHSTMT        hstmt;
    SQLRETURN       rc;
    SQLUSMALLINT     rowstat[MAX_TABLES];
    SQLUINTEGER      pcrow;
    rc = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
    /* SQL_ROWSET_SIZE sets the max number of result rows to fetch each time */
    rc = SQLSetStmtAttr(hstmt, SQL_ATTR_ROWSET_SIZE, (void*)MAX_TABLES, 0);
    /* Set size of one row, used for row-wise binding only */
    rc = SQLSetStmtAttr(hstmt, SQL_ATTR_BIND_TYPE, 
                        (void *)sizeof(table) / MAX_TABLES, 0);
    printf("Enter Search Pattern for Table Schema Name:¥n");
    gets(table->schem);
    printf("Enter Search Pattern for Table Name:¥n");
    gets(table->name);
    rc = SQLTables(hstmt, NULL, 0, table->schem, SQL_NTS,
                   table->name, SQL_NTS, NULL, 0);
    rc = SQLBindCol(hstmt, 2, SQL_C_CHAR, (SQLPOINTER) &table->schem, 129,
                    &table->schem_l);
    rc = SQLBindCol(hstmt, 3, SQL_C_CHAR, (SQLPOINTER) &table->name, 129,
                    &table->name_l);
    rc = SQLBindCol(hstmt, 4, SQL_C_CHAR, (SQLPOINTER) &table->type, 129,
                    &table->type_l);
    rc = SQLBindCol(hstmt, 5, SQL_C_CHAR, (SQLPOINTER) &table->remarks, 255,
                    &table->remarks_l);
    /* Now fetch the result set */
/* ... */