SQLPrimaryKeys - 表の主キー列の入手

目的

仕様:

DB2 CLI 2.1

ODBC 1.0

SQLPrimaryKeys() は、表の主キーを構成する列名のリストを戻します。この情報は SQL 結果セットに戻されます。この結果セットは、照会で生成された結果セットの処理に使用するものと同じ関数を使用して、取り出すことができます。CatalogName、NameLength1、SchemaName、NameLength2 は無視されます。戻された結果セットの列 1、2、6 は、常に長さがゼロのストリングになります。

構文

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

関数の引き数

表 76. SQLPrimaryKeys の引き数

データ・タイプ	引き数	用途	説明
SQLHSTMT	`StatementHandle`	入力	ステートメント・ハンドル。
SQLCHAR*	`CatalogName`	入力	3 つの部分で構成される表名のカタログ修飾子。このフィールドは、DB2 Everyplace では無視されます。
SQLSMALLINT	`NameLength1`	入力	`CatalogName` の長さ。このフィールドは、DB2 Everyplace では無視されます。
SQLCHAR*	`SchemaName`	入力	表名のスキーマ修飾子。このフィールドは、DB2 Everyplace では無視されます。
SQLSMALLINT	`NameLength2`	入力	`SchemaName` の長さ。このフィールドは、DB2 Everyplace では無視されます。
SQLCHAR*	`TableName`	入力	表名。
SQLSMALLINT	`NameLength3`	入力	`TableName` の長さ。

使用法

SQLPrimaryKeys() は単一の表の主キー列を戻します。表名を指定するために、検索パターンを使用することはできません。

指定した表に主キーが含まれていない場合、空の結果セットが戻されます。

多くの場合、SQLPrimaryKeys() の呼び出しは、システム・カタログに対する複雑な (そのために高コストの) 照会にマップされます。

将来のリリースで新規の列が追加されたり、既存の列の名前が変更されても、現在の列の位置は変わりません。

結果セットには、以下の列が TABLE_NAME および ORDINAL_POSITION 順に含まれています

列 1 TABLE_CAT (VARCHAR(128)): これは常に長さゼロのストリングです。
列 2 TABLE_SCHEM (VARCHAR(128)): これは常に長さゼロのストリングです。
列 3 TABLE_NAME (VARCHAR(128) 非ヌル): 指定した表の名前。
列 4 COLUMN_NAME (VARCHAR(128) 非ヌル): 主キーの列名。
列 5 ORDINAL_POSITION (SMALLINT 非ヌル): 1 から始まる、主キー内の列シーケンス番号。
列 6 PK_NAME (VARCHAR(128)): これは常に長さゼロのストリングです。

DB2 CLI/ODBC が使用する列名は、X/Open CLI CAE 仕様のスタイルに準拠しています。

戻りコード

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

診断

表 77. SQLPrimaryKey SQLSTATE

SQLSTATE	説明	解説
24000	カーソル状態が無効。	カーソルがすでにこのステートメント・ハンドルでオープンされている。
40003 08S01	通信リンク障害。	関数の完了前に、アプリケーションとデータ・ソース間の通信リンクに障害が生じた。
HY001	メモリーの割り振りの失敗。	DB2 CLI が、関数の実行または完了のサポートに必要なメモリーを割り当てることができない。
HY010	関数のシーケンス・エラー。	実行時データ (`SQLPrepare()` または `SQLExecDirect()`) の操作中に、関数が呼び出された。
HY014	ハンドル数の限界に到達済み。	内部リソースが原因で、DB2 CLI がハンドルを割り当てることができない。
HY090	無効なストリング長またはバッファー長。	名前の長さ引き数のいずれかの値が、ゼロより小であるが、SQL_NTS と等しくない。

制約事項

SQLPrimaryKeys() の呼び出しは慎重に使用し、呼び出しを繰り返し実行するのではなく、結果を保管するようにしてください。

関連した解説