Función SQLForeignKeys

Conformidad
Versión introducida: Cumplimiento de Normas ODBC 1.0: ODBC

Resumen
SQLForeignKeys puede devolver:

• Una lista de claves foráneas en la tabla especificada (columnas en la tabla especificada que hacen referencia a claves primarias en otras tablas).

• Una lista de claves foráneas en otras tablas que se refieren a la clave primaria en la tabla especificada.

El controlador devuelve cada lista como un conjunto de resultados en la instrucción especificada.

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
[Entrada] Identificador de instrucciones.

PKCatalogName
[Entrada] Nombre del catálogo de tabla de claves primaria. Si un controlador soporta catálogos para algunas tablas pero no para otras, como cuando el controlador recupera datos de diferentes SGBD, una cadena vacía ("") denota aquellas tablas que no tienen catálogos. PKCatalogName no puede contener un patrón de búsqueda de cadenas.

Si el atributo de la sentencia SQL_ATTR_METADATA_ID se establece como SQL_TRUE, PKCatalogName se trata como un identificador y su caso no es significativo. Si es SQL_FALSE, PKCatalogName es un argumento ordinario; Se trata literalmente, y su caso es significativo. Para obtener más información, consulte Argumentos en funciones de catálogo.

NameLength1
[Entrada] Longitud de *PKCatalogName, en caracteres.

PKSchemaName
[Entrada] Nombre principal del esquema de la tabla de claves. Si un controlador soporta esquemas para algunas tablas pero no para otras, como cuando recupera datos de diferentes SGBD, una cadena vacía ("") denota aquellas tablas que no tienen esquemas. PKSchemaName no puede contener un patrón de búsqueda de cadenas.

Si el atributo de la sentencia SQL_ATTR_METADATA_ID se establece en SQL_TRUE, PKSchemaName se trata como un identificador y su caso no es significativo. Si es SQL_FALSE, PKSchemaName es un argumento ordinario; Se trata literalmente, y su caso es significativo.

NameLength2
[Entrada] Longitud de *PKSchemaName, en caracteres.

PKTableName
[Entrada] Nombre principal de la tabla de claves. PKTableName no puede contener un patrón de búsqueda de cadenas.

Si el atributo de la sentencia SQL_ATTR_METADATA_ID se establece en SQL_TRUE, PKTableName se trata como un identificador y su caso no es significativo. Si es SQL_FALSE, PKTableName es un argumento ordinario; Se trata literalmente, y su caso es significativo.

NameLength3
[Entrada] Longitud de *PKTableName, en caracteres.

FKCatalogName
[Entrada] Nombre del catálogo de tabla de llaves extranjeras. Si un controlador soporta catálogos para algunas tablas pero no para otras, como cuando el controlador recupera datos de diferentes SGBD, una cadena vacía ("") denota aquellas tablas que no tienen catálogos. FKCatalogName no puede contener un patrón de búsqueda de cadenas.

Si el atributo de la sentencia SQL_ATTR_METADATA_ID se establece en SQL_TRUE, FKCatalogName se trata como un identificador y su caso no es significativo. Si es SQL_FALSE, FKCatalogName es un argumento ordinario; Se trata literalmente, y su caso es significativo.

NombreLongitud4
[Entrada] Longitud de *FKCatalogName, en caracteres.

FKSchemaName
[Entrada] Nombre del esquema de la tabla de clave extranjera. Si un controlador soporta esquemas para algunas tablas pero no para otras, como cuando recupera datos de diferentes SGBD, una cadena vacía ("") denota aquellas tablas que no tienen esquemas. FKSchemaName no puede contener un patrón de búsqueda en cadenas.

Si el atributo de la sentencia SQL_ATTR_METADATA_ID se establece en SQL_TRUE, FKSchemaName se trata como un identificador y su caso no es significativo. Si es SQL_FALSE, FKSchemaName es un argumento ordinario; Se trata literalmente, y su caso es significativo.

NombreLongitud5
[Entrada] Longitud de *FKSchemaName, en caracteres.

FKTableName
[Entrada] Nombre de la tabla de claves extranjeras. FKTableName no puede contener un patrón de búsqueda en cadenas.

Si el atributo de la sentencia SQL_ATTR_METADATA_ID se establece como SQL_TRUE, FKTableName se trata como un identificador y su caso no es significativo. Si es SQL_FALSE, FKTableName es un argumento ordinario; Se trata literalmente, y su caso es significativo.

NombreLongitud6
[Entrada] Longitud de *FKTableName, en caracteres.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostics

Cuando SQLForeignKeys devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando a SQLGetDiagRec con un HandleType de SQL_HANDLE_STMT y un Handle de StatementHandle. La siguiente tabla enumera los valores de SQLSTATE que normalmente devuelven SQLForeignKeys y explica cada uno en el contexto de esta función; la notación "(DM)" precede a las descripciones de los SQLSTATE devueltas por el Driver Manager. El código de retorno asociado a cada valor SQLSTATE es SQL_ERROR, a menos que se indique lo contrario.

Comentarios

Para información sobre cómo podría usarse la información devuelta por esta función, véase Usos de los datos de catálogo.

Si *PKTableName contiene un nombre de tabla, SQLForeignKeys devuelve un conjunto de resultados que contiene la clave primaria de la tabla especificada y todas las claves externas que se refieren a ella. La lista de claves foráneas en otras tablas no incluye claves foráneas que apunten a restricciones únicas en la tabla especificada.

Si *FKTableName contiene un nombre de tabla, SQLForeignKeys devuelve un conjunto de resultados que contiene todas las claves externas en la tabla especificada que apuntan a claves primarias en otras tablas, y las claves primarias en las otras tablas a las que se refieren. La lista de claves foráneas en la tabla especificada no contiene claves foráneas que se refieran a restricciones únicas en otras tablas.

Si tanto *PKTableName como *FKTableName contienen nombres de tablas, SQLForeignKeys devuelve las claves externas en la tabla especificadas en *FKTableName que se refieren a la clave primaria de la tabla especificada en *PKTableName. Esto debería ser como mucho una llave.

SQLForeignKeys devuelve los resultados como un conjunto estándar de resultados. Si se solicitan las claves foráneas asociadas a una clave primaria, el conjunto de resultados se ordena por FKTABLE_CAT, FKTABLE_SCHEM, FKTABLE_NAME y KEY_SEQ. Si se solicitan las claves primarias asociadas a una clave foránea, el conjunto de resultados se ordena por PKTABLE_CAT, PKTABLE_SCHEM, PKTABLE_NAME y KEY_SEQ. En la tabla siguiente se enumeran las columnas del conjunto de resultados.

Las longitudes de las columnas VARCHAR no se muestran en la tabla; Las longitudes reales dependen de la fuente de datos. Para determinar la longitud real de las columnas PKTABLE_CAT o FKTABLE_CAT, PKTABLE_SCHEM o FKTABLE_SCHEM, PKTABLE_NAME o FKTABLE_NAME, y PKCOLUMN_NAME o FKCOLUMN_NAME columnas, una aplicación puede llamar a SQLGetInfo con las opciones SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_TABLE_NAME_LEN y SQL_MAX_COLUMN_NAME_LEN.

Las siguientes columnas han sido renombradas como ODBC 3*.x.* Los cambios en el nombre de las columnas no afectan la compatibilidad hacia atrás porque las aplicaciones se vinculan por número de columna.

En la tabla siguiente se enumeran las columnas del conjunto de resultados. El conductor puede definir columnas adicionales más allá de la columna 14 (OBSERVACIONES). Una aplicación debe obtener acceso a columnas específicas del controlador contando desde el final del conjunto de resultados en lugar de especificar una posición ordinal explícita. Para obtener más información, vea Datos devueltos por funciones de catálogo.

Ejemplo de código

Como se ilustra en la siguiente tabla, este ejemplo utiliza tres tablas, denominadas ORDERS, LINES y CUSTOMERS.

En la tabla de PEDIDOS, CUSTID identifica al cliente al que se ha realizado la venta. Es una clave externa que se refiere a CUSTID en la tabla CLIENTES.

En la tabla LINES, ORDERID identifica la orden de venta con la que está asociada la partida. Es una clave externa que se refiere a ORDERID en la tabla ORDERS.

Este ejemplo llama a SQLPrimaryKeys para obtener la clave primaria de la tabla ORDERS. El conjunto de resultados tendrá una fila; Las columnas significativas se muestran en la siguiente tabla.

A continuación, el ejemplo llama a SQLForeignKeys para obtener las claves externas en otras tablas que hacen referencia a la clave primaria de la tabla ORDERS. El conjunto de resultados tendrá una fila; Las columnas significativas se muestran en la siguiente tabla.

Finalmente, el ejemplo llama a SQLForeignKeys para obtener las claves externas en la tabla ORDERS que se refieren a las claves primarias de otras tablas. El conjunto de resultados tendrá una fila; Las columnas significativas se muestran en la siguiente tabla.

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

Funciones relacionadas

Véase también

Referencia de la API ODBC
Archivos de encabezado de ODBC