SQLPrimaryKeys() - 表の主キー列を取得する

SQLPrimaryKeys() は、表の主キーを構成する列名のリストを戻します。情報は、SQL 結果セットとして戻されます。 この結果セットは、 照会で生成される結果セットを処理するのと同じ関数を使用して、取り出すことができます。

SQLPrimaryKeys() の ODBC 仕様

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

構文

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

関数の引数

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

表 2. SQLPrimaryKeys() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 ステートメント・ハンドル。
SQLCHAR * szCatalogName 入力 3 部構成の表名のカタログ修飾子。

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

SQLSMALLINT cbCatalogName 入力 szCatalogName の長さ (バイト)。
SQLCHAR * szSchemaName 入力 表名のスキーマ修飾子。
SQLSMALLINT cbSchemaName 入力 szSchemaName の長さ (バイト)。
SQLCHAR * szTableName 入力 表名。
SQLSMALLINT cbTableName 入力 szTableName の長さ (バイト)。

使用法

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

結果セットには 表 3 にリストされている列が、TABLE_CAT、 TABLE_SCHEM、TABLE_NAME、および ORDINAL_POSITION の順序で入ります。

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

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

将来のリリースでは、列が新たに追加されたり、既存の列の名前が 変更される可能性はありますが、現行の列の位置が変更になることはありま せん。次の表は、この関数が生成する結果セットの それぞれの列についてリストしています。

表 3. SQLPrimaryKeys() によって戻される列
列番号 列名 データ・タイプ 説明
1 TABLE_CAT VARCHAR(128) これは常に NULL です。
2 TABLE_SCHEM VARCHAR(128) TABLE_NAME を含むスキーマの名前。
3 TABLE_NAME VARCHAR(128) NOT NULL 指定した表の名前。
4 COLUMN_NAME VARCHAR(128) NOT NULL 主キー列の名前。
5 KEY_SEQ SMALLINT NOT NULL 1 から始まる主キー列シーケンス番号。
6 PK_NAME VARCHAR(128) 主キー ID。 データ・ソースに適用できない場合は、NULL 値を含みます。

Db2 ODBC が使用する列名は、X/Open CLI CAE 仕様のスタイルに準拠しています。列タイプ、内容、および順序は、ODBC の SQLPrimaryKeys() 結果セット で定義されているものと同じです。

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

戻りコード

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

診断

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

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

例

以下の例 は、SQLPrimaryKeys() を使用して表の主キー を見つけ、SQLColAttribute() を呼び出し、キーのデータ・タイプを見つけるアプリケーションを示しています。
図 1. 表の主キーを見つけるアプリケーション
/* ... */
#include <sqlcli1.h>
void main()
{
   SQLCHAR      rgbDesc_20];
   SQLCHAR      szTableName_20];
   SQLCHAR      szSchemaName_20];
   SQLCHAR      rgbValue_20];
   SQLINTEGER   pcbValue;
   SQLHENV      henv;
   SQLHDBC      hdbc;
   SQLHSTMT     hstmt;
   SQLSMALLINT  pscDesc;
   SQLINTEGER   pdDesc;
   SQLRETURN    rc;
   /*******************************************************************/
   /*   Initialization...                                             */
   /*******************************************************************/
   if( SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv)!= SQL_SUCCESS )
   {
       fprintf( stdout, "Error in SQLAllocHandle¥n" );
       exit(1);
   }
   if( SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc)!= SQL_SUCCESS )
   {
       fprintf( stdout, "Error in SQLAllocHandle¥n" );
       exit(1);
   }
   if( SQLConnect( hdbc,
                   NULL, SQL_NTS,
                   NULL, SQL_NTS,
                   NULL, SQL_NTS ) != SQL_SUCCESS )
   {
       fprintf( stdout, "Error in SQLConnect¥n" );
       exit(1);
   }
   if( SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt)!= SQL_SUCCESS )
   {
       fprintf( stdout, "Error in SQLAllocHandle¥n" );
       exit(1);
   }
 
   /*******************************************************************/
   /*  Get primary key for table 'myTable' by using SQLPrimaryKeys    */
   /*******************************************************************/
   rc = SQLPrimaryKeys( hstmt,
                        NULL, SQL_NTS,
                        (SQLCHAR*)szSchemaName, SQL_NTS,
                        (SQLCHAR*)szTableName, SQL_NTS );
   if( rc != SQL_SUCCESS )
   {
       goto exit;
   }
   /*
    *   Because all we need is the ordinal position, we'll bind column 5 from
    *   the result set.
    */
   rc = SQLBindCol( hstmt,
                    5,
                    SQL_C_CHAR,
                    (SQLPOINTER)rgbValue,
                    20,
                    &pcbValue );
   if( rc != SQL_SUCCESS )
   {
       goto exit;
   }
   /*
    *   Fetch data...
    */
   if( SQLFetch( hstmt ) != SQL_SUCCESS )
   {
        goto exit;
   }
   /*******************************************************************/
   /*  Get data type for that column by calling SQLColAttribute().    */
   /*******************************************************************/
   rc =  SQLColAttribute(  hstmt,
                           pcbValue,
                           SQL_COLUMN_TYPE,
                           rgbDesc,
                           20,
                           &pcbDesc,
                           &pfDesc );
   if( rc != SQL_SUCCESS )
   {
       goto exit;
   }
   /*
    *   Display the data type.
    */
   fprintf( stdout, "Data type ==> 
exit:
   /*******************************************************************/
   /* Clean up the environment...                                     */
   /*******************************************************************/
   SQLEndTran(SQL_HANDLE_DBC, hdbc, SQL_ROLLBACK);
   SQLDisconnect( hdbc );
   SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
   SQLFreeHandle(SQL_HANDLE_ENV, henv);
}