Funzione SQLForeignKeys

Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ODBC

Riepilogo
SQLForeignKeys può restituire:

• Elenco di chiavi esterne nella tabella specificata (colonne nella tabella specificata che fanno riferimento alle chiavi primarie in altre tabelle).

• Elenco di chiavi esterne in altre tabelle che fanno riferimento alla chiave primaria nella tabella specificata.

Il driver restituisce ogni elenco come set di risultati nell'istruzione specificata.

Sintassi

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

Argomenti

StatementHandle
[Input] Handle di istruzione.

PKCatalogName
[Input] Nome del catalogo della tabella chiave primaria. Se un driver supporta cataloghi per alcune tabelle ma non per altri, ad esempio quando il driver recupera i dati da diversi DBMS, una stringa vuota ("") indica le tabelle che non dispongono di cataloghi. PKCatalogName non può contenere un criterio di ricerca di stringhe.

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, PKCatalogName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, PKCatalogName è un argomento ordinario; viene trattato letteralmente e il relativo case è significativo. Per altre informazioni, vedere Argomenti in Funzioni del catalogo.

NameLength1
[Input] Lunghezza di *PKCatalogName, in caratteri.

PKSchemaName
[Input] Nome dello schema della tabella della chiave primaria. Se un driver supporta gli schemi per alcune tabelle ma non per altri, ad esempio quando il driver recupera i dati da diversi DBMS, una stringa vuota ("") indica le tabelle che non dispongono di schemi. PKSchemaName non può contenere un criterio di ricerca di stringhe.

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, PKSchemaName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, PKSchemaName è un argomento ordinario; viene trattato letteralmente e il relativo caso è significativo.

NameLength2
[Input] Lunghezza di *PKSchemaName, in caratteri.

PKTableName
[Input] Nome tabella chiave primaria. PKTableName non può contenere un criterio di ricerca di stringhe.

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, PKTableName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, PKTableName è un argomento ordinario; viene trattato letteralmente e il relativo case è significativo.

NameLength3
[Input] Lunghezza di *PKTableName, in caratteri.

FKCatalogName
[Input] Nome del catalogo della tabella di chiavi esterne. Se un driver supporta cataloghi per alcune tabelle ma non per altri, ad esempio quando il driver recupera i dati da diversi DBMS, una stringa vuota ("") indica le tabelle che non dispongono di cataloghi. FKCatalogName non può contenere un criterio di ricerca di stringhe.

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, FKCatalogName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, FKCatalogName è un argomento comune; viene trattato letteralmente e il relativo caso è significativo.

NameLength4
[Input] Lunghezza di *FKCatalogName, in caratteri.

FKSchemaName
[Input] Nome dello schema della tabella della chiave esterna. Se un driver supporta gli schemi per alcune tabelle ma non per altri, ad esempio quando il driver recupera i dati da diversi DBMS, una stringa vuota ("") indica le tabelle che non dispongono di schemi. FKSchemaName non può contenere un criterio di ricerca di stringhe.

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, FKSchemaName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, FKSchemaName è un argomento ordinario; viene trattato letteralmente e il relativo caso è significativo.

NameLength5
[Input] Lunghezza di *FKSchemaName, in caratteri.

FKTableName
[Input] Nome tabella chiave esterna. FKTableName non può contenere un criterio di ricerca di stringhe.

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, FKTableName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, FKTableName è un argomento ordinario; viene trattato letteralmente e il relativo caso è significativo.

NameLength6
[Input] Lunghezza di *FKTableName, in caratteri.

Resi

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLForeignKeys restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleTypedi SQL_HANDLE_STMT e handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE restituiti in genere da SQLForeignKeys e spiega ognuno nel contesto di questa funzione. La notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

Commenti

Per informazioni su come usare le informazioni restituite da questa funzione, vedere Uses of Catalog Data.For information about how the information returned by this function might be used, see Uses of Catalog Data.

Se *PKTableName contiene un nome di tabella, SQLForeignKeys restituisce un set di risultati contenente la chiave primaria della tabella specificata e tutte le chiavi esterne che vi fanno riferimento. L'elenco di chiavi esterne in altre tabelle non include chiavi esterne che puntano a vincoli univoci nella tabella specificata.

Se *FKTableName contiene un nome di tabella, SQLForeignKeys restituisce un set di risultati contenente tutte le chiavi esterne nella tabella specificata che puntano alle chiavi primarie in altre tabelle e le chiavi primarie nelle altre tabelle a cui fanno riferimento. L'elenco di chiavi esterne nella tabella specificata non contiene chiavi esterne che fanno riferimento a vincoli univoci in altre tabelle.

Se *PKTableName e *FKTableName contengono nomi di tabella, SQLForeignKeys restituisce le chiavi esterne nella tabella specificata in *FKTableName che fanno riferimento alla chiave primaria della tabella specificata in *PKTableName. Dovrebbe trattarsi di una chiave al massimo.

SQLForeignKeys restituisce i risultati come set di risultati standard. Se vengono richieste le chiavi esterne associate a una chiave primaria, il set di risultati viene ordinato in base a FKTABLE_CAT, FKTABLE_SCHEM, FKTABLE_NAME e KEY_SEQ. Se vengono richieste le chiavi primarie associate a una chiave esterna, il set di risultati viene ordinato in base a PKTABLE_CAT, PKTABLE_SCHEM, PKTABLE_NAME e KEY_SEQ. Nella tabella seguente sono elencate le colonne nel set di risultati.

Le lunghezze delle colonne VARCHAR non vengono visualizzate nella tabella; le lunghezze effettive dipendono dall'origine dati. Per determinare le lunghezze effettive delle colonne PKTABLE_CAT o FKTABLE_CAT, PKTABLE_SCHEM o FKTABLE_SCHEM, PKTABLE_NAME o FKTABLE_NAME e PKCOLUMN_NAME o FKCOLUMN_NAME, un'applicazione può chiamare SQLGetInfo con le opzioni di SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_TABLE_NAME_LEN e SQL_MAX_COLUMN_NAME_LEN.

Le colonne seguenti sono state rinominate per ODBC 3*.x.* Le modifiche apportate al nome della colonna non influiscono sulla compatibilità con le versioni precedenti perché le applicazioni si associano in base al numero di colonna.

Nella tabella seguente sono elencate le colonne nel set di risultati. Le colonne aggiuntive successive alla colonna 14 (REMARKS) possono essere definite dal driver. Un'applicazione deve ottenere l'accesso alle colonne specifiche del driver con il conteggio dalla fine del set di risultati invece di specificare una posizione ordinale esplicita. Per altre informazioni, vedere Dati restituiti dalle funzioni del catalogo.

Esempio di codice

Come illustrato nella tabella seguente, questo esempio usa tre tabelle, denominate ORDERS, LINES e CUSTOMERS.

Nella tabella ORDERS CUSTID identifica il cliente a cui è stata effettuata la vendita. Si tratta di una chiave esterna che fa riferimento a CUSTID nella tabella CUSTOMERS.

Nella tabella LINES ORDERID identifica l'ordine di vendita a cui è associato l'elemento della riga. Si tratta di una chiave esterna che fa riferimento a ORDERID nella tabella ORDERS.

Questo esempio chiama SQLPrimaryKeys per ottenere la chiave primaria della tabella ORDERS. Il set di risultati avrà una riga; Le colonne significative sono illustrate nella tabella seguente.

L'esempio chiama quindi SQLForeignKeys per ottenere le chiavi esterne in altre tabelle che fanno riferimento alla chiave primaria della tabella ORDERS. Il set di risultati avrà una riga; Le colonne significative sono illustrate nella tabella seguente.

Infine, l'esempio chiama SQLForeignKeys per ottenere le chiavi esterne nella tabella ORDERS che fanno riferimento alle chiavi primarie di altre tabelle. Il set di risultati avrà una riga; Le colonne significative sono illustrate nella tabella seguente.

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

Funzioni correlate

Vedi anche

Riferimento API ODBC
File di intestazione ODBC