SQLForeignKeys 関数

適合 性
導入版:ODBC 1.0 規格準拠:ODBC

まとめ
SQLForeignKeys は以下の返事が可能です:

• 指定されたテーブル内の外部キーのリスト(他のテーブルの主キーを参照する列)。

• 指定されたテーブル内の主キーを参照する他のテーブルの外部キーのリスト。

ドライバーは指定された文に対して各リストの結果セットとして返します。

Syntax

  
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(PKSchemaName)
[入力]プライマリキーテーブルスキーマ名。 ドライバが一部のテーブルにはスキーマをサポートし、他のテーブルにはサポートしない場合(例えば異なるDBMSからデータを取得する場合など)、空の文字列(「」)はスキーマを持たないテーブルを示します。 PKSchemaName は文字列検索パターンを含めることはできません。

SQL_ATTR_METADATA_ID文属性がSQL_TRUEに設定されている場合、 PKSchemaName は識別子として扱われ、その大文字は有意ではありません。 もしそれがSQL_FALSEであれば、 PKSchemaName は通常の引数です。文字通りに扱われており、そのケースは重要です。

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

PKTableName(PKTableName)
[入力]プライマリキーテーブル名。 PKTableName は文字列検索パターンを含めません。

SQL_ATTR_METADATA_ID文属性がSQL_TRUEに設定されている場合、 PKTableName は識別子として扱われ、その大切なケースは重要ではありません。 もしそれがSQL_FALSEであれば、 PKTableName は通常の引数となります。文字通りに扱われており、そのケースは重要です。

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

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

SQL_ATTR_METADATA_ID文属性がSQL_TRUEに設定されている場合、 FKCatalogName は識別子として扱われ、その大文字は重要ではありません。 SQL_FALSEの場合、 FKCatalogName は通常の引数となります。文字通りに扱われており、そのケースは重要です。

名前の長さ4
[入力]*FKCatalogName(文字数)の長さ。

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

SQL_ATTR_METADATA_ID文属性がSQL_TRUEに設定されている場合、 FKSchemaName は識別子として扱われ、その大文字は重要ではありません。 もしそれがSQL_FALSEであれば、 FKSchemaName は通常の引数です。文字通りに扱われており、そのケースは重要です。

名前の長さ5
[入力]*FKSchemaName(文字数)の長さ。

FKTableName(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。

Diagnostics

SQLForeignKeysがSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、SQLGetDiagRecを呼び出し、HandleTypeをSQL_HANDLE_STMT、HandleをStatementHandleに割り当てることで、関連するSQLSTATE値を取得できます。 以下の表は 、通常SQLForeignKeysによって返されるSQLSTATE 値と、この関数の文脈でそれぞれを説明しています。「(DM)」という表記は、ドライバーマネージャーが返すSQLstateの記述の前に記載されます。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。

Comments

この関数で返される情報がどのように使われるかについては、「 カタログデータの用途」を参照してください。

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

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

*PKTableName と*FKTableName の両方にテーブル名が含まれている場合、 SQLForeignKeys は*FKTableName で指定されたテーブル内の外部キーを返し、これらは*PKTableNameで指定されたテーブルの主キーを参照します。 これはせいぜい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列(REMARKS)以降の追加列はドライバーによって定義可能です。 アプリケーションは、明示的な序数位置を指定するのではなく、結果セットの末尾からカウントダウンすることで、ドライバー固有の列にアクセスできるようにする必要があります。 詳細については、「 カタログ関数によって返されるデータ」を参照してください。

コード例

以下の表に示されているように、この例はORDERS、LINES、CUSTOMERSという3つのテーブルを使用しています。

ORDERS テーブルでは、CUSTIDが販売が行われた顧客を特定します。 これはCUSTOMERSテーブル内のCUSTIDを参照する外部キーです。

LINESテーブルでは、ORDERIDがそのラインアイテムに関連付けられた販売注文を識別します。 これはORDERSテーブル内のORDERIDを参照する外部キーです。

この例ではORDERSテーブルの主キーを取得する ためにSQLPrimaryKeys を呼び出します。 結果セットは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 ヘッダー ファイル