SQLTables() - 表情報を取得する
SQLTables() は、接続しているデータ・ソースのシステム・カタログに保管されている表名と関連情報のリストを戻します。表名のリストが結果セットとして戻されます。この結果セットは、 照会で生成される結果セットを処理するのと同じ関数を使用して、取り出すことができます。
SQLTables() の ODBC 仕様
| 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);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | hstmt | 入力 | ステートメント・ハンドル。 |
| SQLCHAR * | szCatalogName | 入力 | 結果セットを修飾するためのパターン値 を入れることが
できるバッファー。 カタログ は、3 部構成の表名の最初の部分です。
これは、NULL ポインターまたは長さゼロのストリングでなければなりません。 |
| SQLSMALLINT | cbCatalogName | 入力 | szCatalogName の長さ (バイト)。 これは、0 に設定する必要があります。 |
| SQLCHAR * | szSchemaName | 入力 | スキーマ名で結果セットを修飾するためのパターン値 を入れることができるバッファー。 |
| SQLSMALLINT | cbSchemaName | 入力 | szSchemaName の長さ (バイト)。 |
| SQLCHAR * | szTableName | 入力 | 表名によって結果セットを修飾するパターン値 を入れることができるバッファー。 |
| SQLSMALLINT | cbTableName | 入力 | szTableName の長さ (バイト)。 |
| SQLCHAR * | szTableType | 入力 | 表タイプで結果セットを修飾するための値リスト を入
れることができるバッファー。
値のリストは、対象の表タイプに関する、コンマで区切られ、単一 引用符で囲まれた大文字の値のリストです。
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() への呼び出しは、システム・カタログに対する複雑な (したがって、 コストのかかる) 照会にマップされることになるため、慎重に使用し、呼び出しを繰り返さずに、 結果を保管するようにしてください。
- 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() が戻す結果セット の列を示しています。
| 列名 | データ・タイプ | 説明 |
|---|---|---|
| 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)![]() |
テンポラル表のタイプが含まれます。可能な値は、以下のとおりです。
初期化キーワード 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 に設定される場合にのみ、結果セットにこの列が含まれます。 ![]() |
戻りコード
- 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 が戻されます。
|
| HYC00 | ドライバーは使用できません。 | Db2 ODBC は、表名の修飾子として catalog はサポートしていません。 |
例
/* ... */
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 */
/* ... */
有効な表タイプ ID には、TABLE、VIEW、SYSTEM TABLE、ALIAS、SYNONYM、GLOBAL TEMPORARY TABLE、AUXILIARY TABLE、MATERIALIZED QUERY TABLE、または ACCEL-ONLY TABLE があります。