Функция 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);  

Arguments

ОператорHandle
[Входные данные] Дескриптор инструкции.

PKCatalogName
[Ввод] Название каталога таблицы первичных ключей. Если драйвер поддерживает каталоги для одних таблиц, но не для других, например, когда драйвер получает данные из разных СУБД, пустая строка («») обозначает те таблицы, в которых нет каталогов. PKCatalogName не может содержать шаблон поиска по строкам.

Если атрибут оператора SQL_ATTR_METADATA_ID установлен в SQL_TRUE, PKCatalogName рассматривается как идентификатор, и его падеж не является значимым. Если это SQL_FALSE, то PKCatalogName — это обычный аргумент; Это воспринимается буквально, и его дело значимо. Дополнительные сведения см. в разделе "Аргументы" в функциях каталога.

NameLength1
[Ввод] Длина *PKCatalogName, в символах.

PKSchemaName
[Ввод] Название схемы таблицы первичных ключей. Если драйвер поддерживает схемы для одних таблиц, но не для других, например, когда драйвер получает данные из разных СУБД, пустая строка ("") обозначает таблицы без схем. 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 — это обычный аргумент; Это воспринимается буквально, и его дело значимо.

НазваниеДлина4
[Ввод] Длина *FKCatalogName, в символах.

FKSchemaName
[Ввод] Название схемы таблицы внешних ключей. Если драйвер поддерживает схемы для одних таблиц, но не для других, например, когда драйвер получает данные из разных СУБД, пустая строка ("") обозначает таблицы без схем. FKSchemaName не может содержать шаблон поиска по строкам.

Если атрибут оператора SQL_ATTR_METADATA_ID установлен в SQL_TRUE, FKSchemaName рассматривается как идентификатор, и его падеж не является значимым. Если это SQL_FALSE, то FKSchemaName — это обычный аргумент; Это воспринимается буквально, и его дело значимо.

НазваниеДлина5
[Ввод] Длина *FKSchemaName, в символах.

FKTableName
[Ввод] Название таблицы внешних ключей. FKTableName не может содержать шаблон поиска по строкам.

Если атрибут оператора SQL_ATTR_METADATA_ID установлен в SQL_TRUE, FKTableName рассматривается как идентификатор, и его падеж не является значимым. Если это SQL_FALSE, то FKTableName — это обычный аргумент; Это воспринимается буквально, и его дело значимо.

НазваниеДлина6
[Ввод] Длина *FKTableName, в символах.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR или SQL_INVALID_HANDLE.

Diagnostics

Когда SQLForeignKeys возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, соответствующее значение SQLSTATE можно получить, вызвав SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и HandleType of StatementHandle. В следующей таблице перечислены значения SQLSTATE, обычно возвращаемые SQLForeignKeys , и каждое из них объясняется в контексте этой функции; обозначение «(DM)» предшествует описаниям SQLSTATE, возвращаемым менеджером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.

Comments

Для информации о том, как может использоваться информация, возвращаемая этой функцией, см. раздел Использование каталоговых данных.

Если *PKTableName содержит имя таблицы, SQLForeignKeys возвращает набор результатов, содержащий первичный ключ указанной таблицы и все внешние ключи, которые к нему ссылаются. Список внешних ключей в других таблицах не включает внешние ключи, указывающие на уникальные ограничения в указанной таблице.

Если *FKTableName содержит имя таблицы, SQLForeignKeys возвращает набор результатов, содержащий все внешние ключи указанной таблицы, указывающие на первичные ключи в других таблицах, а также первичные ключи в других таблицах, к которым они относятся. Список внешних ключей в указанной таблице не содержит внешних ключей, отсылающих к уникальным ограничениям в других таблицах.

Если и *PKTableName , и *FKTableName содержат имена таблиц, SQLForeignKeys возвращает внешние ключи в таблице, указанной в *FKTableName , которые относятся к первичному ключу таблицы, указанной в *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 столбцов, приложение может вызвать SQLGetInfo с помощью опций SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_TABLE_NAME_LEN и SQL_MAX_COLUMN_NAME_LEN.

Следующие столбцы были переименованы для ODBC 3*.x.*. Изменение названий столбцов не влияет на обратную совместимость, поскольку приложения зависят от номера столбцов.

В следующей таблице перечислены столбцы в результирующем наборе. Драйвер может определить дополнительные столбцы после столбца 14 (ПРИМЕЧАНИЯ). Приложение должно получить доступ к столбцам для конкретного драйвера, отсчитывая от конца результирующего набора вместо указания явной порядковой позиции. Дополнительные сведения см. в разделе "Данные, возвращаемые функциями каталога".

Пример кода

Как показано в следующей таблице, в этом примере используются три таблицы, названные ORDERS, LINES и CUSTOMERS.

В таблице ORDERS CUSTID указывает клиента, которому была совершена сделка. Это внешний ключ, который ссылается на CUSTID в таблице CUSTOMERS.

В таблице LINES ORDERID обозначает заказ на продажу, с которым связан этот элемент. Это внешний ключ, который ссылается на ORDERID в таблице ORDERS.

В этом примере вызывается SQLPrimaryKeys для получения первичного ключа таблицы ORDERS. Набор результатов будет состоять из одной строки; Значимые столбцы показаны в следующей таблице.

Далее пример вызывает SQLForeignKeys для получения внешних ключей в других таблицах, которые ссылаются на первичный ключ таблицы ORDERS. Набор результатов будет состоять из одной строки; Значимые столбцы показаны в следующей таблице.

Наконец, в примере используется SQLForeignKeys , чтобы получить внешние ключи в таблице ORDER, которые ссылаются на первичные ключи других таблиц. Набор результатов будет состоять из одной строки; Значимые столбцы показаны в следующей таблице.

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

Связанные функции

См. также

Справочник по API ODBC
Файлы заголовков ODBC