SQLTables - 表情報の取得

目的

仕様:

DB2 CLI 2.1

ODBC 1.0

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

構文

SQLRETURN   SQLTables        (
                SQLHSTMT          StatementHandle,   /* hstmt */
                SQLCHAR      FAR  *CatalogName,      /* szCatalogName */
                SQLSMALLINT       NameLength1,       /* cbCatalogName */
                SQLCHAR      FAR  *SchemaName,       /* szSchemaName */
                SQLSMALLINT       NameLength2,       /* cbSchemaName */
                SQLCHAR      FAR  *TableName,        /* szTableName */
                SQLSMALLINT       NameLength3,       /* cbTableName */
                SQLCHAR      FAR  *TableType,        /* szTableType */
                SQLSMALLINT       NameLength4);      /* cbTableType */

関数の引き数

表 89. SQLTables の引き数

データ・タイプ	引き数	用途	説明
SQLHSTMT	`StatementHandle`	入力	ステートメント・ハンドル。
SQLCHAR	`CatalogName`	入力	結果セットを修飾する `pattern-value` を入れることのできるバッファー。`Catalog` は 3 部分からなる表名の最初の部分である。このフィールドは DB2 Everyplace では無視される。
SQLSMALLINT	`NameLength1`	入力	`CatalogName` の長さ。このフィールドは DB2 Everyplace では無視される。
SQLCHAR	`SchemaName`	入力	結果セットをスキーマ名で修飾する `pattern-value` を入れることのできるバッファー。このフィールドは DB2 Everyplace では無視される。
SQLSMALLINT	`NameLength2`	入力	`SchemaName` の長さ。このフィールドは DB2 Everyplace では無視される。
SQLCHAR	`TableName`	入力	結果セットを表名で修飾する `pattern-value` を入れることのできるバッファー。
SQLSMALLINT	`NameLength3`	入力	`TableName` の長さ。
SQLCHAR	`TableType`	入力	DB2 Everyplace はタイプ TABLE のみサポートする。このフィールドは DB2 Everyplace では無視される。
SQLSMALLINT	`NameLength4`	入力	このフィールドは DB2 Everyplace では無視される。

TableName 引き数が検索パターンを受け入れることに注意してください。

使用法

表情報は結果セットに戻されますが、各表は結果セットの 1 行で表されます。

時には、戻される結果セットが制限されないよう、アプリケーションで TableName 引き数にヌル・ポインターを指定して SQLTables() を呼び出します。多数の表が入っているデータ・ソースの場合、この方法だと極めて大きな結果セットになり、検索時間が非常に長くなります。

SQLTables() で戻される結果セットには、指定された順序で表 90内にリストされた列が入ります。行は TABLE_NAME の順に配列されます。

SQLTables() の呼び出しは、多くの場合システム・カタログに対する複雑で時間のかかる照会となるため、控えめに行うようにしてください。呼び出しを繰り返さず、結果を保管するようにしてください。

カタログ関数の結果セットの VARCHAR 列は、SQL92 の制限と一貫性を持たせるために最大長の属性は 128 で宣言されています。 DB2 の名前は 128 より短いため、128 文字 (NULL 終止符を含む) を常に出力バッファー用にとっておくか、または SQL_MAX_TABLE_NAME_LEN を指定した SQLGetInfo() を呼び出して、接続されている DBMS がサポートする TABLE_NAME 列の実際の長さを判別することができます。

表 90. SQLTables が戻す列

列名	データ・タイプ	説明
TABLE_CAT	VARCHAR (128)	これは常に長さゼロのストリングです。
TABLE_SCHEM	VARCHAR (128)	これは常に長さゼロのストリングです。
TABLE_NAME	VARCHAR (128)	表の名前
TABLE_TYPE	VARCHAR (128)	TABLE_NAME 列内で名前で指定されたタイプを識別します。常にストリング値「TABLE」となります。
REMARKS	VARCHAR(254)	表についての記述情報が入ります。

戻りコード

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

診断

表 91. SQLTables の SQLSTATE

SQLSTATE 説明解説

HY001 メモリーの割り振りの失敗。 DB2 CLI が、関数を実行または完了させるのに必要なメモリーを割り当てることができない。

HY014 ハンドル数の限界に到達済み。内部リソースが原因で、DB2 CLI がハンドルを割り振ることができない。

SQLSTATE	説明	解説
HY001	メモリーの割り振りの失敗。	DB2 CLI が、関数を実行または完了させるのに必要なメモリーを割り当てることができない。
HY014	ハンドル数の限界に到達済み。	内部リソースが原因で、DB2 CLI がハンドルを割り振ることができない。
HY090	無効なストリング長またはバッファー長。	名前の長さ引き数のいずれかの値が、ゼロより小であるが、SQL_NTS と等しくない。指定された名前長さの引き数のうちの 1 つが、データ・ソースに対してサポートされている最大値を超える値を持っている。サポートされている最大値は、`SQLGetInfo()` 関数を呼び出すことで取得できる。

HY090

無効なストリング長またはバッファー長。

名前の長さ引き数のいずれかの値が、ゼロより小であるが、SQL_NTS と等しくない。

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

制約事項

なし。

関連した解説

SQLGetInfo -- 一般情報の取得