SQLForeignKeys 函数

一致性
推出版本：ODBC 1.0 标准合规：ODBC

总结
SQLForeignKey 可以返回：

• 指定表中外键的列表（指定表中指向其他表中主键的列）。

• 指代指定表中主键的其他表中的外键列表。

驱动程序将每个列表作为指定语句的结果集返回。

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);  

Arguments

StatementHandle
[输入]语句句柄。

PKCatalogName
[输入]主键表目录名称。 如果驱动程序支持某些表的目录，但不支持其他表，例如当驱动程序从不同的数据库管理系统检索数据时，空字符串（“”）表示那些没有目录的表。 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
[输入]外键表目录名称。 如果驱动程序支持某些表的目录，但不支持其他表，例如当驱动程序从不同的数据库管理系统检索数据时，空字符串（“”）表示那些没有目录的表。 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 的字元长度。

Returns

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。

Diagnostics

当 SQLForeignKeys 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用 SQLGetDiagRec 获得关联的 SQLSTATE 值，Handle 为 SQL_HANDLE_STMT，Handle 为 StatementHandle。 下表列出了 SQLForeignKeys 通常返回的SQLSTATE值，并在该函数的上下文中解释了每个值;“（DM）” 符号位于驱动程序管理器返回的 SQLSTATE 描述之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。

注释

有关该函数返回信息如何被使用的信息，请参见 目录数据的用途。

如果 *PKTableName 包含表名， SQLForeignKeys 返回一个结果集，包含指定表的主键和所有引用该表的外键。 其他表中的外键列表不包括指向指定表中唯一约束的外键。

如果 *FKTableName 包含表名， SQLForeignKeys 返回一个结果集，包含指定表中指向其他表主键的所有外键，以及它们所引用的其他表中的主键。 指定表中的外键列表不包含指向其他表中唯一约束的外键。

如果 *PKTableName 和 *FKTableName 都包含表名， SQLForeignKeys 返回表中指定的外键，这些外 键指向 *PKTableName 指定表的主键。 这最多应该是一键。

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。

在订单表中，CUSTID标识了销售对象的客户。 这是一个外键，在 CUSTOMERS 表中指向 CUSTID。

在LINES表中，ORDERID标识该条目关联的销售订单。 它是一个外键，在 ORDERS 表中指向 ORDERID。

本示例调用 SQLPrimaryKeys 获取 ORDERS 表的主键。 结果集将有一行;有效列如下表所示。

接下来，示例调用 SQLForeignKeys 获取其他表中引用 ORDERS 表主键的外键。 结果集将有一行;有效列如下表所示。

最后，示例调用 SQLForeignKeys 获取 ORDERS 表中指向其他表主键的外键。 结果集将有一行;有效列如下表所示。

#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 头文件