SQLForeignKeys 関数

準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: ODBC

まとめ
SQLForeignKeys は次を 返すことができます。

• 指定したテーブル内の外部キーの一覧 (他のテーブルの主キーを参照する指定したテーブル内の列)。

• 指定したテーブルの主キーを参照する他のテーブルの外部キーの一覧。

ドライバーは、指定したステートメントの結果セットとして各リストを返します。

構文

  
SQLRETURN SQLForeignKeys(  
     SQLHSTMT       StatementHandle,  
     SQLCHAR *      PKCatalogName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      PKSchemaName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      PKTableName,  
     SQLSMALLINT    NameLength3,  
     SQLCHAR *      FKCatalogName,  
     SQLSMALLINT    NameLength4,  
     SQLCHAR *      FKSchemaName,  
     SQLSMALLINT    NameLength5,  
     SQLCHAR *      FKTableName,  
     SQLSMALLINT    NameLength6);  

引数

StatementHandle
[入力]ステートメント ハンドル。

PKCatalogName
[入力]主キー テーブル カタログ名。 ドライバーが一部のテーブルのカタログをサポートしているが、他のテーブルではサポートされていない場合 (ドライバーが異なる DBMS からデータを取得する場合など)、空の文字列 ("") はカタログを持たないテーブルを示します。 PKCatalogName に文字列検索パターンを含めることはできません。

SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定されている場合、 PKCatalogName は識別子として扱われ、大文字と小文字は区別されません。 SQL_FALSEの場合、 PKCatalogName は通常の引数です。これはリテラルとして扱われ、その場合は重要です。 詳細については、「 カタログ関数の引数」を参照してください。

NameLength1
[入力]*PKCatalogName の長さ (文字数)。

PKSchemaName
[入力]主キー テーブルのスキーマ名。 ドライバーが一部のテーブルのスキーマをサポートしているが、他のテーブルではサポートされていない場合 (ドライバーが異なる DBMS からデータを取得する場合など)、空の文字列 ("") はスキーマを持たないテーブルを示します。 PKSchemaName に文字列検索パターンを含めることはできません。

SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定されている場合、 PKSchemaName は識別子として扱われ、大文字と小文字は区別されません。 SQL_FALSEの場合、 PKSchemaName は通常の引数です。これはリテラルとして扱われ、その場合は重要です。

NameLength2
[入力]*PKSchemaName の長さ (文字数)。

PKTableName
[入力]主キー テーブル名。 PKTableName に文字列検索パターンを含めることはできません。

SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定されている場合、 PKTableName は識別子として扱われ、大文字と小文字は区別されません。 SQL_FALSEの場合、 PKTableName は通常の引数です。これはリテラルとして扱われ、その場合は重要です。

NameLength3
[入力]*PKTableName の長さ (文字数)。

FKCatalogName
[入力]外部キー テーブル カタログ名。 ドライバーが一部のテーブルのカタログをサポートしているが、他のテーブルではサポートされていない場合 (ドライバーが異なる DBMS からデータを取得する場合など)、空の文字列 ("") はカタログを持たないテーブルを示します。 FKCatalogName に文字列検索パターンを含めることはできません。

SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定されている場合、 FKCatalogName は識別子として扱われ、大文字と小文字は区別されません。 SQL_FALSE場合、 FKCatalogName は通常の引数です。これはリテラルとして扱われ、その場合は重要です。

NameLength4
[入力]*FKCatalogName の長さ (文字数)。

FKSchemaName
[入力]外部キー テーブルスキーマ名。 ドライバーが一部のテーブルのスキーマをサポートしているが、他のテーブルではサポートされていない場合 (ドライバーが異なる DBMS からデータを取得する場合など)、空の文字列 ("") はスキーマを持たないテーブルを示します。 FKSchemaName には文字列検索パターンを含めることはできません。

SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定されている場合、 FKSchemaName は識別子として扱われ、大文字と小文字は区別されません。 SQL_FALSEの場合、 FKSchemaName は通常の引数です。これはリテラルとして扱われ、その場合は重要です。

NameLength5
[入力]*FKSchemaName の長さ (文字数)。

FKTableName
[入力]外部キー テーブル名。 FKTableName に 文字列検索パターンを含めることはできません。

SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定されている場合、 FKTableName は識別子として扱われ、大文字と小文字は区別されません。 SQL_FALSEの場合、 FKTableName は通常の引数です。これはリテラルとして扱われ、その場合は重要です。

NameLength6
[入力]*FKTableName の長さ (文字数)。

戻り値

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR、またはSQL_INVALID_HANDLE。

診断

SQLForeignKeys がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられた SQLSTATE 値を取得するには、HandleType が SQL_HANDLE_STMT で、Handle of StatementHandle を使用して SQLGetDiagRec を呼び出します。 次の表に、 SQLForeignKeys によって通常返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられた戻りコードはSQL_ERRORされます。

説明

この関数によって返される情報の使用方法については、「 カタログ データの使用」を参照してください。

*PKTableName に テーブル名が含まれている場合、 SQLForeignKeys は、指定されたテーブルの主キーと、それを参照するすべての外部キーを含む結果セットを返します。 他のテーブルの外部キーの一覧には、指定されたテーブル内の一意の制約を指す外部キーは含まれません。

*FKTableName に テーブル名が含まれている場合、 SQLForeignKeys は、他のテーブルの主キーと、参照先の他のテーブルの主キーを指す、指定されたテーブル内のすべての外部キーを含む結果セットを返します。 指定したテーブル内の外部キーの一覧には、他のテーブルの一意の制約を参照する外部キーが含まれていません。

*PKTableName と *FKTableName の両方にテーブル名が含まれている場合、SQLForeignKeys は*PKTableName で指定されたテーブルの主キーを参照する *FKTableName で指定されたテーブルの外部キーを返します。 これは、最大で 1 つのキーである必要があります。

SQLForeignKeys は、 標準の結果セットとして結果を返します。 主キーに関連付けられている外部キーが要求された場合、結果セットは、FKTABLE_CAT、FKTABLE_SCHEM、FKTABLE_NAME、KEY_SEQ順に並べ替えられます。 外部キーに関連付けられている主キーが要求された場合、結果セットは、PKTABLE_CAT、PKTABLE_SCHEM、PKTABLE_NAME、およびKEY_SEQ順に並べ替えられます。 次の表に、結果セットの列を示します。

VARCHAR 列の長さは表に示されていません。実際の長さはデータ ソースによって異なります。 アプリケーションは、PKTABLE_CATまたはFKTABLE_CAT、PKTABLE_SCHEMまたはFKTABLE_SCHEM、PKTABLE_NAMEまたはFKTABLE_NAME、PKCOLUMN_NAME列またはFKCOLUMN_NAME列の実際の長さを判断するために、SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN、SQL_MAX_TABLE_NAME_LEN、およびSQL_MAX_COLUMN_NAME_LENオプションを使用して SQLGetInfo を呼び出すことができます。

ODBC 3*.x に対して次の列の名前が変更されました。* アプリケーションは列番号でバインドされるため、列名の変更は下位互換性に影響しません。

次の表に、結果セットの列を示します。 列 14 (解説) を超える追加の列は、ドライバーによって定義できます。 アプリケーションは、明示的な序数位置を指定する代わりに、結果セットの末尾からカウントダウンすることで、ドライバー固有の列にアクセスする必要があります。 詳細については、「 カタログ関数によって返されるデータ」を参照してください。

コード例

次の表に示すように、この例では ORDERS、LINES、CUSTOMERS という名前の 3 つのテーブルを使用します。

ORDERS テーブルでは、CUSTID は販売先の顧客を識別します。 これは、CUSTOMERS テーブルの CUSTID を参照する外部キーです。

LINES テーブルの ORDERID は、明細が関連付けられている販売注文を識別します。 これは、ORDERS テーブル内の ORDERID を参照する外部キーです。

この例では 、SQLPrimaryKeys を 呼び出して ORDERS テーブルの主キーを取得します。 結果セットには 1 つの行があります。重要な列を次の表に示します。

次に、この例では SQLForeignKeys を 呼び出して、ORDERS テーブルの主キーを参照する他のテーブルの外部キーを取得します。 結果セットには 1 つの行があります。重要な列を次の表に示します。

最後に、 SQLForeignKeys を呼び出して、他のテーブルの主キーを参照する ORDERS テーブル内の外部キーを取得します。 結果セットには 1 つの行があります。重要な列を次の表に示します。

#define TAB_LEN SQL_MAX_TABLE_NAME_LEN + 1  
#define COL_LEN SQL_MAX_COLUMN_NAME_LEN + 1  
  
LPSTR   szTable;              /* Table to display */  
  
UCHAR szPkTable[TAB_LEN];   /* Primary key table name */  
UCHAR szFkTable[TAB_LEN];   /* Foreign key table name */  
UCHAR szPkCol[COL_LEN];     /* Primary key column */  
UCHAR szFkCol[COL_LEN];     /* Foreign key column */  
  
SQLHSTMT      hstmt;  
SQLINTEGER    cbPkTable, cbPkCol, cbFkTable, cbFkCol, cbKeySeq;  
SQLSMALLINT   iKeySeq;  
SQLRETURN     retcode;  
  
// Bind the columns that describe the primary and foreign keys.  
// Ignore the table schema, name, and catalog for this example.  
  
SQLBindCol(hstmt, 3, SQL_C_CHAR, szPkTable, TAB_LEN, &cbPkTable);  
SQLBindCol(hstmt, 4, SQL_C_CHAR, szPkCol, COL_LEN, &cbPkCol);  
SQLBindCol(hstmt, 5, SQL_C_SSHORT, &iKeySeq, TAB_LEN, &cbKeySeq);  
SQLBindCol(hstmt, 7, SQL_C_CHAR, szFkTable, TAB_LEN, &cbFkTable);  
SQLBindCol(hstmt, 8, SQL_C_CHAR, szFkCol, COL_LEN, &cbFkCol);  
  
strcpy_s(szTable, sizeof(szTable), "ORDERS");  
  
/* Get the names of the columns in the primary key. */  
  
retcode = SQLPrimaryKeys(hstmt,  
         NULL, 0,             /* Catalog name */  
         NULL, 0,             /* Schema name */  
         szTable, SQL_NTS);   /* Table name */  
  
while ((retcode == SQL_SUCCESS) || (retcode == SQL SUCCESS_WITH_INFO)) {  
  
   /* Fetch and display the result set. This will be a list of the */  
   /* columns in the primary key of the ORDERS table. */  
  
   retcode = SQLFetch(hstmt);  
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)  
      fprintf(out, "Table: %s Column: %s Key Seq: %hd \n", szPkTable, szPkCol,  
      iKeySeq);  
}  
  
/* Close the cursor (the hstmt is still allocated). */  
  
SQLFreeStmt(hstmt, SQL_CLOSE);  
  
/* Get all the foreign keys that refer to ORDERS primary key.*/   
  
retcode = SQLForeignKeys(hstmt,  
         NULL, 0,            /* Primary catalog */  
         NULL, 0,            /* Primary schema */  
         szTable, SQL_NTS,   /* Primary table */  
         NULL, 0,            /* Foreign catalog */  
         NULL, 0,            /* Foreign schema */  
         NULL, 0);           /* Foreign table */  
  
while ((retcode == SQL_SUCCESS) || (retcode == SQL_SUCCESS_WITH_INFO)) {  
  
/* Fetch and display the result set. This will be all of the */  
/* foreign keys in other tables that refer to the ORDERS */  
/* primary key. */  
  
   retcode = SQLFetch(hstmt);  
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)  
      fprintf(out, "%-s ( %-s ) <-- %-s ( %-s )\n", szPkTable,  
               szPkCol, szFkTable, szFkCol);  
}  
  
/* Close the cursor (the hstmt is still allocated). */  
  
SQLFreeStmt(hstmt, SQL_CLOSE);  
  
/* Get all the foreign keys in the ORDERS table. */  
  
retcode = SQLForeignKeys(hstmt,  
         NULL, 0,             /* Primary catalog */  
         NULL, 0,             /* Primary schema */  
         NULL, 0,             /* Primary table */  
         NULL, 0,             /* Foreign catalog */  
         NULL, 0,             /* Foreign schema */  
         szTable, SQL_NTS);   /* Foreign table */  
  
while ((retcode == SQL_SUCCESS) || (retcode == SQL_SUCCESS_WITH_INFO)) {  
  
/* Fetch and display the result set. This will be all of the */  
/* primary keys in other tables that are referred to by foreign */  
/* keys in the ORDERS table. */  
  
   retcode = SQLFetch(hstmt);  
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)  
      fprintf(out, "%-s ( %-s )--> %-s ( %-s )\n", szFkTable, szFkCol, szPkTable, szPkCol);  
}  
  
/* Free the hstmt. */  
SQLFreeStmt(hstmt, SQL_DROP);  

関連する関数

参照

ODBC API リファレンス
ODBC ヘッダー ファイル