SQLForeignKeys() - 外部キー列のリストを取得する
SQLForeignKeys() は、指定された表の外部キーに関する情報を戻します。情報は SQL 結果セットとして戻されます。 これは、照会で生成された結果を取り出すのに使用するものと同じ関数を使用して処理することができます。
SQLForeignKeys() の ODBC 仕様
| 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);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| 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() が戻す結果セット の列を示しています。
| 列番号 | 列名 | データ・タイプ | 説明 |
|---|---|---|---|
| 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 データベース管理システムは、常に次のいずれかの値を戻します。
IBM 以外のリレーショナル・データベース管理システムに接続した場合は、次の UPDATE_RULE 値を検出する場合があります。
|
| 11 | DELETE_RULE | SMALLINT | SQL 操作が DELETE であるときに外部キーに適用されるアクションを示します。
以下の値は、適用されるアクションを示しています。
|
| 12 | FK_NAME | VARCHAR(128) | 外部キーの名前を含んでいます。 この列は、データ・ソースに適用できない場合は、NULL 値を含みます。 |
| 13 | PK_NAME | VARCHAR(128) | 主キーの名前を含んでいます。 この列は、データ・ソースに適用できない場合は、NULL 値を含みます。 |
| 14 | DEFERRABILITY | SMALLINT | Db2 ODBC は、常に、NULL の値を戻します。 他のデータベース管理システムは、次の値をサポートしています。
|
- FKTABLE_CAT
- FKTABLE_SCHEM
- FKTABLE_NAME
- KEY_SEQ
- PKTABLE_CAT
- PKTABLE_SCHEM
- PKTABLE_NAME
- KEY_SEQ
Db2 ODBC が使用する列名は、X/Open CLI CAE 仕様のスタイルに準拠しています。列タイプ、内容、および順序は、ODBC の SQLForeignKeys() 結果セット で定義されているものと同じです。
将来のリリースでは、列が新たに追加されたり、既存の列の名前が 変更される可能性はありますが、現行の列の位置が変更されることはありません。
Db2 for z/OS® サーバーに対して SQLForeignKeys() を出す Db2 ODBC アプリケーション は、表 3 に示された結果セットの列が当然戻るものと考えます。
- 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 列がサポートする長さを判別
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 08S01 | 通信リンクに障害が起きました。 | 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。 |
| 24000 | カーソル状態が無効です。 | ステートメント・ハンドルでカーソルがオープン状態です。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
| HY009 | NULL ポインターの使用は無効です。 | 引数 szPkTableName と szFkTableName が、 両方ともに NULL ポインターです。 |
| HY010 | 関数シーケンス・エラーが発生しました。 | この関数は、実行時データの操作時に呼び出されました。(すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。) |
| HY090 | ストリングまたはバッファーの長さが無効です。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| HYC00 | ドライバーは使用できません。 | Db2 ODBC は、表名の修飾子として 'catalog' はサポートしていません。 |
| HY014 | これ以上ハンドルがありません。 | Db2 ODBC は、内部リソースが少ないためにハンドルを割り振ることができません。 |
例
/******************************************************************/
/* 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;
}