Fonction SQLForeignKeys

Conformité
Version introduite : Conformité aux normes ODBC 1.0 : ODBC

Résumé
SQLForeignKeys peut retourner :

• Liste des clés étrangères dans la table spécifiée (colonnes de la table spécifiée qui font référence à des clés primaires dans d’autres tables).

• Liste des clés étrangères dans d’autres tables qui font référence à la clé primaire dans la table spécifiée.

Le pilote retourne chaque liste en tant que jeu de résultats sur l’instruction spécifiée.

Syntaxe

  
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
[Entrée] Handle d’instruction.

PKCatalogName
[Entrée] Nom du catalogue de table de clés primaires. Si un pilote prend en charge les catalogues pour certaines tables, mais pas pour d’autres, par exemple lorsque le pilote récupère des données à partir de différents SGBD, une chaîne vide (« ») désigne les tables qui n’ont pas de catalogues. PKCatalogName ne peut pas contenir un modèle de recherche de chaîne.

Si l’attribut d’instruction SQL_ATTR_METADATA_ID est défini sur SQL_TRUE, PKCatalogName est traité comme un identificateur et sa casse n’est pas significative. S’il est SQL_FALSE, PKCatalogName est un argument ordinaire ; il est traité littéralement, et son cas est significatif. Pour plus d’informations, consultez Arguments dans les fonctions de catalogue.

NameLength1
[Entrée] Longueur de *PKCatalogName, en caractères.

PKSchemaName
[Entrée] Nom du schéma de la table de clé primaire. Si un pilote prend en charge des schémas pour certaines tables, mais pas pour d’autres, par exemple quand le pilote récupère des données à partir de différents SGBD, une chaîne vide (« ») désigne les tables qui n’ont pas de schémas. PKSchemaName ne peut pas contenir un modèle de recherche de chaîne.

Si l’attribut d’instruction SQL_ATTR_METADATA_ID a la valeur SQL_TRUE, PKSchemaName est traité comme un identificateur et sa casse n’est pas significative. S’il est SQL_FALSE, PKSchemaName est un argument ordinaire ; il est traité littéralement, et son cas est significatif.

NameLength2
[Entrée] Longueur de *PKSchemaName, en caractères.

PKTableName
[Entrée] Nom de la table de clé primaire. PKTableName ne peut pas contenir un modèle de recherche de chaîne.

Si l’attribut d’instruction SQL_ATTR_METADATA_ID a la valeur SQL_TRUE, PKTableName est traité comme un identificateur et sa casse n’est pas significative. S’il est SQL_FALSE, PKTableName est un argument ordinaire ; il est traité littéralement, et son cas est significatif.

NameLength3
[Entrée] Longueur de *PKTableName, en caractères.

FKCatalogName
[Entrée] Nom du catalogue de tables de clés étrangères. Si un pilote prend en charge les catalogues pour certaines tables, mais pas pour d’autres, par exemple lorsque le pilote récupère des données à partir de différents SGBD, une chaîne vide (« ») désigne les tables qui n’ont pas de catalogues. FKCatalogName ne peut pas contenir un modèle de recherche de chaîne.

Si l’attribut d’instruction SQL_ATTR_METADATA_ID a la valeur SQL_TRUE, FKCatalogName est traité comme un identificateur et sa casse n’est pas significative. S’il est SQL_FALSE, FKCatalogName est un argument ordinaire ; il est traité littéralement, et son cas est significatif.

NameLength4
[Entrée] Longueur de *FKCatalogName, en caractères.

FKSchemaName
[Entrée] Nom du schéma de table de clés étrangères. Si un pilote prend en charge des schémas pour certaines tables, mais pas pour d’autres, par exemple quand le pilote récupère des données à partir de différents SGBD, une chaîne vide (« ») désigne les tables qui n’ont pas de schémas. FKSchemaName ne peut pas contenir un modèle de recherche de chaîne.

Si l’attribut d’instruction SQL_ATTR_METADATA_ID a la valeur SQL_TRUE, FKSchemaName est traité comme un identificateur et sa casse n’est pas significative. S’il est SQL_FALSE, FKSchemaName est un argument ordinaire ; il est traité littéralement, et son cas est significatif.

NameLength5
[Entrée] Longueur de *FKSchemaName, en caractères.

FKTableName
[Entrée] Nom de la table de clés étrangères. FKTableName ne peut pas contenir un modèle de recherche de chaîne.

Si l’attribut d’instruction SQL_ATTR_METADATA_ID a la valeur SQL_TRUE, FKTableName est traité comme un identificateur et sa casse n’est pas significative. S’il est SQL_FALSE, FKTableName est un argument ordinaire ; il est traité littéralement, et son cas est significatif.

NameLength6
[Entrée] Longueur de *FKTableName, en caractères.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLForeignKeys retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec un HandleType de SQL_HANDLE_STMT et un handled’instructionHandle. Le tableau suivant répertorie les valeurs SQLSTATE généralement retournées par SQLForeignKeys et explique chacune d’elles dans le contexte de cette fonction ; La notation « (DM) » précède les descriptions de SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.

Commentaires

Pour plus d’informations sur la façon dont les informations retournées par cette fonction peuvent être utilisées, consultez Utilisations des données de catalogue.

Si *PKTableName contient un nom de table, SQLForeignKeys retourne un jeu de résultats qui contient la clé primaire de la table spécifiée et toutes les clés étrangères qui y font référence. La liste des clés étrangères dans d’autres tables n’inclut pas les clés étrangères qui pointent vers des contraintes uniques dans la table spécifiée.

Si *FKTableName contient un nom de table, SQLForeignKeys retourne un jeu de résultats qui contient toutes les clés étrangères de la table spécifiée qui pointent vers des clés primaires dans d’autres tables, ainsi que les clés primaires dans les autres tables auxquelles elles font référence. La liste des clés étrangères dans la table spécifiée ne contient pas de clés étrangères qui font référence à des contraintes uniques dans d’autres tables.

Si *PKTableName et *FKTableName contiennent des noms de table, SQLForeignKeys retourne les clés étrangères dans la table spécifiée dans *FKTableName qui font référence à la clé primaire de la table spécifiée dans *PKTableName. Il devrait s’agir d’une clé au maximum.

SQLForeignKeys retourne les résultats sous la forme d’un jeu de résultats standard. Si les clés étrangères associées à une clé primaire sont demandées, le jeu de résultats est classé par FKTABLE_CAT, FKTABLE_SCHEM, FKTABLE_NAME et KEY_SEQ. Si les clés primaires associées à une clé étrangère sont demandées, le jeu de résultats est classé par PKTABLE_CAT, PKTABLE_SCHEM, PKTABLE_NAME et KEY_SEQ. Le tableau suivant répertorie les colonnes du jeu de résultats.

Les longueurs des colonnes VARCHAR ne sont pas affichées dans la table ; les longueurs réelles dépendent de la source de données. Pour déterminer la longueur réelle des colonnes PKTABLE_CAT ou FKTABLE_CAT, PKTABLE_SCHEM ou FKTABLE_SCHEM, PKTABLE_NAME ou FKTABLE_NAME et PKCOLUMN_NAME ou FKCOLUMN_NAME colonnes, une application peut appeler SQLGetInfo avec les options SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_TABLE_NAME_LEN et SQL_MAX_COLUMN_NAME_LEN.

Les colonnes suivantes ont été renommées pour ODBC 3*.x.* Les changements de nom de colonne n’affectent pas la compatibilité descendante, car les applications sont liées par numéro de colonne.

Le tableau suivant répertorie les colonnes du jeu de résultats. Des colonnes supplémentaires au-delà de la colonne 14 (REMARQUES) peuvent être définies par le pilote. Une application doit accéder à des colonnes spécifiques au pilote en comptant à partir de la fin du jeu de résultats au lieu de spécifier une position ordinale explicite. Pour plus d’informations, consultez Données retournées par les fonctions de catalogue.

Exemple de code

Comme illustré dans le tableau suivant, cet exemple utilise trois tables, nommées ORDERS, LINES et CUSTOMERS.

Dans la table ORDERS, CUSTID identifie le client auquel la vente a été effectuée. Il s’agit d’une clé étrangère qui fait référence à CUSTID dans la table CUSTOMERS.

Dans la table LIGNES, ORDERID identifie la commande client à laquelle l’élément de ligne est associé. Il s’agit d’une clé étrangère qui fait référence à ORDERID dans la table ORDERS.

Cet exemple appelle SQLPrimaryKeys pour obtenir la clé primaire de la table ORDERS. Le jeu de résultats aura une ligne ; les colonnes significatives sont indiquées dans le tableau suivant.

Ensuite, l’exemple appelle SQLForeignKeys pour obtenir les clés étrangères dans d’autres tables qui référencent la clé primaire de la table ORDERS. Le jeu de résultats aura une ligne ; les colonnes significatives sont indiquées dans le tableau suivant.

Enfin, l’exemple appelle SQLForeignKeys pour obtenir les clés étrangères dans la table ORDERS qui font référence aux clés primaires d’autres tables. Le jeu de résultats aura une ligne ; les colonnes significatives sont indiquées dans le tableau suivant.

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

Fonctions connexes

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC