SQLForeignKeys() - 外部キー列のリストを取得する

SQLForeignKeys() は、指定された表の外部キーに関する情報を戻します。情報は SQL 結果セットとして戻されます。 これは、照会で生成された結果を取り出すのに使用するものと同じ関数を使用して処理することができます。

SQLForeignKeys() の ODBC 仕様

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

構文

SQLRETURN   SQLForeignKeys  (SQLHSTMT           hstmt,
                             SQLCHAR      FAR  *szPkCatalogName,
                             SQLSMALLINT       cbPkCatalogName,
                             SQLCHAR      FAR  *szPkSchemaName,
                             SQLSMALLINT       cbPkSchemaName,
                             SQLCHAR      FAR  *szPkTableName,
                             SQLSMALLINT       cbPkTableName,
                             SQLCHAR      FAR  *szFkCatalogName,
                             SQLSMALLINT       cbFkCatalogName,
                             SQLCHAR      FAR  *szFkSchemaName,
                             SQLSMALLINT       cbFkSchemaName,
                             SQLCHAR      FAR  *szFkTableName,
                             SQLSMALLINT       cbFkTableName);

関数の引数

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

表 2. SQLForeignKeys() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 結果が戻されるステートメント・ハンドルを指定します。
SQLCHAR * szPkCatalogName 入力 主キー表のカタログ修飾子を指定します。これは、NULL ポインターまたは長さゼロのストリングでなければなりません。
SQLSMALLINT cbPkCatalogName 入力 引数 szPkCatalogName の長さ (バイト) を指定します。 これは、0 に設定する必要があります。
SQLCHAR * szPkSchemaName 入力 主キー表のスキーマ修飾子を指定します。
SQLSMALLINT cbPkSchemaName 入力 引数 szPkSchemaName の長さ (バイト) を指定します。
SQLCHAR * szPkTableName 入力 主キーを含む表の名前を指定します。
SQLSMALLINT cbPkTableName 入力 引数 szPkTableName の長さ (バイト) を指定します。
SQLCHAR * szFkCatalogName 入力 外部キーを含む表のカタログ修飾子を指定します。 これは、NULL ポインターまたは長さゼロのストリングでなければなりません。
SQLSMALLINT cbFkCatalogName 入力 引数 szFkCatalogName の長さ (バイト) を指定します。 これは、0 に設定する必要があります。
SQLCHAR * szFkSchemaName 入力 外部キーを含む表のスキーマ修飾子を指定します。
SQLSMALLINT cbFkSchemaName 入力 引数 szFkSchemaName の長さ (バイト) を指定します。
SQLCHAR * szFkTableName 入力 外部キーを含む表の名前を指定します。
SQLSMALLINT cbFkTableName 入力 引数 szFkTableName の長さ (バイト) を指定します。

使用法

引数 szPkTableName に表名が含まれており、 かつ引数 szFkTableName が空ストリングの場合、SQLForeignKeys() は指定された表の主キーと その表を参照するすべての外部キー (他の表にある) を含む結果セットを戻します。

引数 szFkTableName に表名が含まれており、 かつ引数 szPkTableName が空ストリングである場合、SQLForeignKeys() は引数 szFkTableName で指定された表のすべての外部キーと それらのキーが参照する主キー (他の表にある) を含む結果セットを戻します。

引数 szPkTableName および引数 szFkTableName の 両方とも表名を含んでいる場合、SQLForeignKeys() は、引数 szFkTableName で指定した表から、 引数 szPkTableName で指定した表の主キーを参照する外部キーを戻します。 このタイプの SQLForeignKeys() 呼び出しが戻すすべての外部キーは、単一の主キーを参照します。

表名に関連したスキーマ修飾子引数を指定しない場合は、Db2® ODBC は 現行接続で現在有効なスキーマ名を使用します。

次の表は、現在、SQLForeignKeys() が戻す結果セット の列を示しています。

表 3. SQLForeignKeys() で戻される列
列番号 列名 データ・タイプ 説明
1 PKTABLE_CAT VARCHAR(128) これは常に NULL です。
2 PKTABLE_SCHEM VARCHAR(128) PKTABLE_NAME の表が属するスキーマ名を含んでいます。
3 PKTABLE_NAME VARCHAR(128) NOT NULL 主キーが定義される表の名前を含んでいます。
4 PKCOLUMN_NAME VARCHAR(128) NOT NULL 主キーが定義される列の名前を含んでいます。
5 FKTABLE_CAT VARCHAR(128) これは常に NULL です。
6 FKTABLE_SCHEM VARCHAR(128) FKTABLE_NAME の表が属するスキーマ名を含んでいます。
7 FKTABLE_NAME VARCHAR(128) NOT NULL 外部キーが定義される表の名前を含んでいます。
8 FKCOLUMN_NAME VARCHAR(128) NOT NULL 外部キーが定義される列の名前を含んでいます。
9 KEY_SEQ SMALLINT NOT NULL キーの列の順位を含んでいます。 最初の位置は 1 です。
10 UPDATE_RULE SMALLINT SQL 操作が UPDATE であるときに外部キーに適用されるアクションを示します。
IBM® Db2 データベース管理システムは、常に次のいずれかの値を戻します。
  • SQL_RESTRICT
  • SQL_NO_ACTION
上記のいずれの値が戻った場合も、外部キーが参照する主キー行を除去した場合、 あるいは主キーには現れない外部キーに値を追加した場合は、 更新はリジェクトされることを示しています。
IBM 以外のリレーショナル・データベース管理システムに接続した場合は、次の UPDATE_RULE 値を検出する場合があります。
  • SQL_CASCADE
  • SQL_SET_NULL
11 DELETE_RULE SMALLINT SQL 操作が DELETE であるときに外部キーに適用されるアクションを示します。
以下の値は、適用されるアクションを示しています。
  • SQL_CASCADE: 主キー値が削除された場合、関連した外部キーにあるその値も削除されます。
  • SQL_NO_ACTION: 外部キーが参照する主キーから値を除去した場合は、削除はリジェクトされます。
  • SQL_RESTRICT: 外部キーが参照する主キーから値を除去した場合は、削除はリジェクトされます。
  • SQL_SET_DEFAULT: 主キー値が削除された場合、その値は関連した外部キーのデフォルト値と 置き換えられます。
  • SQL_SET_NULL: 主キー値が削除された場合、その値は関連した外部キーの NULL 値と 置き換えられます。
12 FK_NAME VARCHAR(128) 外部キーの名前を含んでいます。 この列は、データ・ソースに適用できない場合は、NULL 値を含みます。
13 PK_NAME VARCHAR(128) 主キーの名前を含んでいます。 この列は、データ・ソースに適用できない場合は、NULL 値を含みます。
14 DEFERRABILITY SMALLINT Db2 ODBC は、常に、NULL の値を戻します。
他のデータベース管理システムは、次の値をサポートしています。
  • SQL_INITIALLY_DEFERRED
  • SQL_INITIALLY_IMMEDIATE
  • SQL_NOT_DEFERRABLE
主キーに関連した外部キーを要求すると、結果セットに戻された行は、 以下の列が含む値によってソートされます。
  1. FKTABLE_CAT
  2. FKTABLE_SCHEM
  3. FKTABLE_NAME
  4. KEY_SEQ
外部キーに関連した主キーを要求すると、結果セットに戻された行は、 以下の列が含む値によってソートされます。
  1. PKTABLE_CAT
  2. PKTABLE_SCHEM
  3. PKTABLE_NAME
  4. KEY_SEQ

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

将来のリリースでは、列が新たに追加されたり、既存の列の名前が 変更される可能性はありますが、現行の列の位置が変更されることはありません。

Db2 for z/OS® サーバーに対して SQLForeignKeys() を出す Db2 ODBC アプリケーション は、表 3 に示された結果セットの列が当然戻るものと考えます。

ANSI/ISO SQL 規格 (1992) の制限との整合性を維持するために、結果セットの VARCHAR 列は最大長さ属性 が 128 バイトで宣言されています。Db2 の名前は 128 文字より短いため、常に、128 文字 (NUL 終止符を プラス) の出力バッファーを使用して、表名を扱うことができます。 以下の各属性を指定して SQLGetInfo() を呼び出し、 別のデータベース管理システムへの接続時に割り振る必要のある実際のスペース量を判別します。
  • SQL_MAX_CATALOG_NAME_LEN -- PKTABLE_CAT 列および FKTABLE_CAT 列がサポートする長さを判別
  • SQL_MAX_SCHEMA_NAME_LEN -- PKTABLE_SCHEM 列および FKTABLE_SCHEM 列がサポートする長さを判別
  • SQL_MAX_TABLE_NAME_LEN -- PKTABLE_NAME 列および FKTABLE_NAME 列がサポートする長さを判別
  • SQL_MAX_COLUMN_NAME_LEN -- PKCOLUMN_NAME 列および FKCOLUMN_NAME 列がサポートする長さを判別

戻りコード

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

診断

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

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

例

以下の例 は、SQLForeignKeys() を使用して、 表に関する外部キー情報を取り出すアプリケーションを示しています。
図 1. 表に関する外部キー情報を取り出すアプリケーション
/******************************************************************/
 /*  Invoke SQLForeignKeys against PARENT Table. Find all          */
 /*  tables that contain foreign keys on PARENT.                   */
 /******************************************************************/
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <sqlca.h>
#include "cli.h"
#include "sqlcli1.h"
#include "sqlcli1.h"
int main( )
{
   SQLHENV         hEnv    = SQL_NULL_HENV;
   SQLHDBC         hDbc    = SQL_NULL_HDBC;
   SQLHSTMT        hStmt   = SQL_NULL_HSTMT;
   SQLRETURN       rc      = SQL_SUCCESS;
   SQLINTEGER      RETCODE = 0;
   char            pTable [200];
   char            *pDSN = "STLEC1";
   SQLSMALLINT     update_rule;
   SQLSMALLINT     delete_rule;
   SQLINTEGER      update_rule_ind;
   SQLINTEGER      delete_rule_ind;
   char            update [25];
   char            delet  [25];   
   typedef struct varchar    // define VARCHAR type
   {
     SQLSMALLINT  length;
     SQLCHAR      name [128];
     SQLINTEGER   ind;
   } VARCHAR;
   VARCHAR pktable_schem;
   VARCHAR pktable_name;
   VARCHAR pkcolumn_name;
   VARCHAR fktable_schem;
   VARCHAR fktable_name;
   VARCHAR fkcolumn_name;
   (void) printf ("**** Entering CLIP02.¥n¥n");
  /*****************************************************************/
  /* Allocate environment handle                                   */
  /*****************************************************************/
   RETCODE = SQLAllocHandle( SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hEnv);
   if (RETCODE != SQL_SUCCESS)
     goto dberror;
  /*****************************************************************/
  /* Allocate connection handle to DSN                             */
  /*****************************************************************/
   RETCODE = SQLAllocHandle( SQL_HANDLE_DBC, hEnv, &hDbc);
   if( RETCODE != SQL_SUCCESS )      // Could not get a connect handle
     goto dberror;
  /*****************************************************************/
  /* CONNECT TO data source (STLEC1)                               */
  /*****************************************************************/
   RETCODE = SQLConnect(hDbc,        // Connect handle
                        (SQLCHAR *) pDSN, // DSN
                        SQL_NTS,     // DSN is nul-terminated
                        NULL,        // Null UID
                        0   ,
                        NULL,        // Null Auth string
                        0);
   if( RETCODE != SQL_SUCCESS )      // Connect failed
     goto dberror;
  /*****************************************************************/
  /* Allocate statement handle                                     */
  /*****************************************************************/
  rc = SQLAllocHandle( SQL_HANDLE_STMT, hDbc, &hStmt);
  if (rc != SQL_SUCCESS)
    goto exit;
  /*****************************************************************/
  /* Invoke SQLForeignKeys against PARENT Table, specifying NULL   */
  /* for table with foreign key.                                   */
  /*****************************************************************/
  rc = SQLForeignKeys (hStmt,
                       NULL,
                       0,
                       (SQLCHAR *) "ADMF001",
                       SQL_NTS,
                       (SQLCHAR *) "PARENT",
                       SQL_NTS,
                       NULL,
                       0,
                       NULL,
                       SQL_NTS,
                       NULL,
                       SQL_NTS);
  if (rc != SQL_SUCCESS)
  {
    (void) printf ("**** SQLForeignKeys Failed.¥n");
    goto dberror;
  }
  /*****************************************************************/
  /* Bind following columns of answer set:                         */
  /*                                                               */
  /*   2) pktable_schem                                            */
  /*   3) pktable_name                                             */
  /*   4) pkcolumn_name                                            */
  /*   6) fktable_schem                                            */
  /*   7) fktable_name                                             */
  /*   8) fkcolumn_name                                            */
  /*  10) update_rule                                              */
  /*  11) delete_rule                                              */
  /*                                                               */
  /*****************************************************************/
  rc = SQLBindCol (hStmt,           // bind pktable_schem
                   2,
                   SQL_C_CHAR,
                   (SQLPOINTER) pktable_schem.name,
                   128,
                   &pktable_schem.ind);
  rc = SQLBindCol (hStmt,           // bind pktable_name
                   3,
                   SQL_C_CHAR,
                   (SQLPOINTER) pktable_name.name,
                   128,
                   &pktable_name.ind);
  rc = SQLBindCol (hStmt,           // bind pkcolumn_name
                   4,
                   SQL_C_CHAR,
                   (SQLPOINTER) pkcolumn_name.name,
                   128,
                   &pkcolumn_name.ind);
  rc = SQLBindCol (hStmt,           // bind fktable_schem
                   6,
                   SQL_C_CHAR,
                   (SQLPOINTER) fktable_schem.name,
                   128,
                   &fktable_schem.ind);
  rc = SQLBindCol (hStmt,           // bind fktable_name
                   7,
                   SQL_C_CHAR,
                   (SQLPOINTER) fktable_name.name,
                   128,
                   &fktable_name.ind);
  rc = SQLBindCol (hStmt,           // bind fkcolumn_name
                   8,
                   SQL_C_CHAR,
                   (SQLPOINTER) fkcolumn_name.name,
                   128,
                   &fkcolumn_name.ind);
  rc = SQLBindCol (hStmt,           // bind update_rule
                   10,
                   SQL_C_SHORT,
                   (SQLPOINTER) &update_rule;
                   0,
                   &update_rule_ind);
 rc = SQLBindCol (hStmt,           // bind delete_rule
                   11,
                   SQL_C_SHORT,
                   (SQLPOINTER) &delete_rule,
                   0,
                   &delete_rule_ind);
  /*****************************************************************/
  /* Retrieve all tables with foreign keys defined on PARENT       */
  /*****************************************************************/
  while ((rc = SQLFetch (hStmt)) == SQL_SUCCESS)
  {
    (void) printf ("**** Primary Table Schema is %s. Primary Table Name is %s.¥n",
                   pktable_schem.name, pktable_name.name);
    (void) printf ("**** Primary Table Key Column is %s.¥n",
                   pkcolumn_name.name);
    (void) printf ("**** Foreign Table Schema is %s. Foreign Table Name is %s.¥n",
                   fktable_schem.name, fktable_name.name);
    (void) printf ("**** Foreign Table Key Column is %s.¥n",
                   fkcolumn_name.name);
    if (update_rule == SQL_RESTRICT)     // isolate update rule
      strcpy (update, "RESTRICT");
    else
    if (update_rule == SQL_CASCADE)
      strcpy (update, "CASCADE");
    else
      strcpy (update, "SET NULL");
    if (delete_rule == SQL_RESTRICT)     // isolate delete rule
      strcpy (delet, "RESTRICT");
    else
    if (delete_rule == SQL_CASCADE)
      strcpy (delet, "CASCADE");
    else
    if (delete_rule == SQL_NO_ACTION)
      strcpy (delet, "NO ACTION");
    else
      strcpy (delet, "SET NULL");
    (void) printf ("**** Update Rule is %s. Delete Rule is %s.¥n",
                   update, delet);
  }
  /*****************************************************************/
  /* Deallocate statement handle                                   */
  /*****************************************************************/
  rc = SQLFreeHandle (SQL_HANDLE_STMT, hStmt);
  /*****************************************************************/
  /* DISCONNECT from data source                                   */
  /*****************************************************************/
   RETCODE = SQLDisconnect(hDbc);
   if (RETCODE != SQL_SUCCESS)
     goto dberror;
  /*****************************************************************/
  /* Deallocate connection handle                                  */
  /*****************************************************************/
   RETCODE = SQLFreeHandle (SQL_HANDLE_DBC, hDbc);
   if (RETCODE != SQL_SUCCESS)
     goto dberror;
  /*****************************************************************/
  /* Free environment handle                                       */
  /*****************************************************************/
   RETCODE = SQLFreeHandle (SQL_HANDLE_ENV, hEnv);
   if (RETCODE == SQL_SUCCESS)
     goto exit;
   dberror:
   RETCODE=12;
   exit:
   (void) printf ("**** Exiting  CLIP02.¥n¥n");
   return RETCODE;
}