仕様: | 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 */
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
SQLCHAR * | CatalogName | 入力 | 結果セットを修飾するためのパターン値を入れられるバッファー。
カタログ は、3 部分から成る表名の最初の部分です。
これは、NULL ポインターまたは長さゼロのストリングでなければなりません。 |
SQLSMALLINT | NameLength1 | 入力 | CatalogName の長さ。これは、0 に設定する必要があります。 |
SQLCHAR * | SchemaName | 入力 | スキーマ名で結果セットを修飾するためのパターン値を入れられるバッファー。 |
SQLSMALLINT | NameLength2 | 入力 | SchemaName の長さ。 |
SQLCHAR * | TableName | 入力 | 表名で結果セットを修飾するためのパターン値を入れられるバッファー。 |
SQLSMALLINT | NameLength3 | 入力 | TableName の長さ。 |
SQLCHAR * | TableType | 入力 | 表タイプで結果セットを修飾する場合の値リスト を入れるバッファー。
値のリストは、対象のタイプに関するコンマで区切られた単一引用符値 (大文字) のリストです。有効な表タイプ識別子には TABLE、VIEW、SYSTEM TABLE、 ALIAS、SYNONYM があります。 TableType 引き数が NULL ポインターであるか、長さゼロのストリングの場合、これは、表タイプ識別子のすべての可能性を指定することに等しくなります。
SYSTEM TABLE を指定すると、システム表とシステム視点 (存在する場合) の両方が戻されます。 |
SQLSMALLINT | NameLength4 | 入力 | NameLength4 のサイズ。 |
CatalogName、SchemaName、および TableName 引き数は、検索パターンを受け入れることに留意してください。有効な検索パターンの詳細については、カタログ関数での入力引き数を参照してください。
使用法
表の情報は、各表が結果セットの 1 行で表される結果セット内に戻されます。アプリケーションは SQLTablePrivileges() を呼び出して、リスト内の表で使用できるアクセスのタイプを判別することができます。そうでない場合には、SELECT 特権が付与されていない表をユーザーが選択する状況を、アプリケーションがハンドルすることができる必要があります。
スキーマのリストだけの入手をサポートするには、以下の SchemaName 引き数用の特殊な方法を適用します。 SchemaName が 1 つのパーセント文字 (%) を含むストリングで、 CatalogName および TableName が空ストリングの場合、結果セットには、データ・ソースの有効スキーマのリストが入ります。
TableType が 1 つのパーセント文字 (%) で、 CatalogName、SchemaName、および TableName が空ストリングの場合、結果セットには、データ・ソースの有効表タイプのリストが入ります。 (TABLE_TYPE 列以外のすべての列には、NULL が含まれています。)
TableType が空ストリングでない場合、大文字のリストが含まれていなければなりませんが、これは、対象となるタイプに対するコンマで区切った値となります。それぞれの値は単一の引用符でくくるか、あるいはくくらないでおきます。たとえば、"'TABLE','VIEW'" または "TABLE,VIEW" となります。データ・ソースが指定された表タイプをサポートまたは認識しない場合、そのタイプについては何も戻されません。
アプリケーションは、NULL ポインターの SQLTables() を、SchemaName、TableName、および TableType 引き数の一部または全部について呼び出すことがありますが、その場合、結果セットの戻りを制限するような試行はなされません。大量の表、視点、別名などを含むいくつかのデータ・ソースの場合、このシナリオでは非常に大きな結果セットにマップし、非常に長い取り出し時間がかかります。エンド・ユーザーが長い検索時間を短縮できるように、3 つのメカニズムが導入されています。 3 つのキーワード (SCHEMALIST、SYSCHEMA、TABLETYPE) を CLI 初期設定ファイルに設定することにより、アプリケーションが SchemaName と TableType の一方または両方に NULL ポインターを与えた場合に、結果セットを制限することができます。これらのキーワードと使用法については、構成キーワードで詳細に説明しています。アプリケーションが SchemaName や TableType に NULL ポインターを指定しなかった場合、 CLI 初期設定ファイルの関連キーワード指定は無視されます。
SQLTables() から戻された結果セットには、所定の順序で表 179 にリストされている列が含まれています。これらの行は TABLE_TYPE、 TABLE_CAT、TABLE_SCHEM、そして TABLE_NAME の順序になっています。
ほとんどの場合、SQLTables() への呼び出しはシステム・カタログに対して複雑で、それゆえに高価な照会へとマップされるので、使用を節約する必要があります。それで、呼び出しを繰り返すよりも、結果を保管しておくほうが良いでしょう。
カタログ関数の結果セットの 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() を呼び出すようにすることができます。
将来のリリースでは、列が新たに追加されたり、既存の列の名前が変更されたりする可能性はありますが、現行の列の位置が変更されることはありません。
列名 | データ・タイプ | 説明 |
---|---|---|
TABLE_CAT | VARCHAR(128) | TABLE_SCHEM を含むカタログの名前。この列には、NULL 値が含まれています。 |
TABLE_SCHEM | VARCHAR(128) | TABLE_NAME を含むスキーマの名前。 |
TABLE_NAME | VARCHAR(128) | 表、視点、別名、同義語のどれかの名前。 |
TABLE_TYPE | VARCHAR(128) | TABLE_NAME 列内の名前で指定されたタイプを識別します。そのタイプは、ストリング値 'TABLE'、'VIEW'、'INOPERATIVE VIEW'、 'SYSTEM TABLE'、'ALIAS'、または 'SYNONYM' です。 |
REMARKS | VARCHAR(254) | 表に関する記述情報が含まれています。 |
戻りコード
診断
SQLSTATE | 説明 | 解説 |
---|---|---|
24000 | カーソル状態が無効です。 | カーソルはすでに、ステートメント・ハンドル上にオープンされています。 |
40003 08S01 | 通信リンクに障害が起きました。 | アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
HY008 | 操作が取り消しになりました。 |
非同期処理が StatementHandle に対して使用可能になりました。関数が呼び出され、その実行が完了する前に、 SQLCancel() が StatementHandle で呼び出されました。そして、関数が再び StatementHandle で呼び出されました。 関数が呼び出され、その実行が完了する前に、
SQLCancel() が複数スレッドのアプリケーション内の別のスレッドから、
StatementHandle で呼び出されました。
|
HY009 | 引き数値が無効です。 | TableName はヌルです。 |
HY010 | 関数の順序エラーです。 |
実行時データ (SQLParamData()、SQLPutData()) 操作中に、関数が呼び出されました。 BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。 非同期実行関数 (この関数ではない) が StatementHandle で呼び出され、この関数は、呼び出し時に依然実行中でした。
|
HY014 | もはやハンドルはありません。 | DB2 CLI は、内部資源が原因でハンドルを割り当てることができませんでした。 |
HY090 | ストリングまたはバッファー長が無効です。 | 名前の長さ引き数のうちの 1 つの値は 0 より小さい値でしたが、
SQL_NTS と等しくありませんでした。
名前の長さ引き数のうちの 1 つの有効値は、そのデータ・ソースについてサポートされる最大値を超えました。 SQLGetInfo() 関数を呼び出して、サポートされる最大値を取得することができます。 |
HYC00 | ドライバーが機能していません。 | DB2 CLI は、表名の修飾子としてカタログ をサポートしません。 |
HYT00 | タイムアウトになりました。 | データ・ソースが結果セットを返す前に、タイムアウト期間が満了しました。タイムアウトは、 Windows 3.1 や Macintosh System 7 のようなマルチタスクではないシステム上でのみサポートされています。タイムアウト期間は、 SQLSetConnectAttr() の SQL_ATTR_QUERY_TIMEOUT 属性を使用して設定することができます。 |
制約
なし。
環境情報の照会の例も参照してください。
(ここで完全サンプル tbread.c を使用することもできます 。)
/* From the CLI sample TBREAD.C */ /* ... */ /* call SQLTables */ printf("\n Call SQLTables.\n"); sqlrc = SQLTables( hstmt, NULL, 0, tbSchemaPattern, SQL_NTS, tbNamePattern, SQL_NTS, NULL, 0); STMT_HANDLE_CHECK( hstmt, sqlrc);
参照