Función SQLTables

Conformidad
Versión introducida: Cumplimiento de los estándares ODBC 1.0: Open Group

Resumen
SQLTables devuelve la lista de nombres de tablas, catálogos o esquemas, y tipos de tablas, almacenados en una fuente de datos específica. El controlador devuelve la información como un conjunto de resultados.

Syntax

  
SQLRETURN SQLTables(  
     SQLHSTMT       StatementHandle,  
     SQLCHAR *      CatalogName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      SchemaName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      TableName,  
     SQLSMALLINT    NameLength3,  
     SQLCHAR *      TableType,  
     SQLSMALLINT    NameLength4);  

Arguments

StatementHandle
[Entrada] Handle de sentencia para los resultados recuperados.

CatalogName
[Entrada] Nombre del catálogo. El argumento Nombre del Catálogo acepta patrones de búsqueda si el atributo de SQL_ODBC_VERSION entorno es SQL_OV_ODBC3; No acepta patrones de búsqueda si SQL_OV_ODBC2 está activado. Si un controlador soporta catálogos para algunas tablas pero no para otras, como cuando un controlador recupera datos de diferentes SGBD, una cadena vacía ("") indica aquellas tablas que no tienen catálogos.

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

NameLength1
[Entrada] Longitud en caracteres de *NombreDeCatálogo.

SchemaName
[Entrada] Patrón de búsqueda de cadenas para nombres de esquemas. Si un controlador soporta esquemas para algunas tablas pero no para otras, como cuando recupera datos de diferentes SGBD, una cadena vacía ("") indica aquellas tablas que no tienen esquemas.

Si el atributo de la sentencia SQL_ATTR_METADATA_ID se establece en SQL_TRUE, SchemaName se trata como un identificador y su caso no es significativo. Si es SQL_FALSE, Nombre de Esquema es un argumento de valor de patrón; Se trata literalmente, y su caso es significativo.

NameLength2
[Entrada] Longitud en caracteres de *NombreEsquema.

TableName
[Entrada] Patrón de búsqueda de cadenas para nombres de tablas.

Si el atributo de la sentencia SQL_ATTR_METADATA_ID se establece en SQL_TRUE, TableName se considera un identificador y su caso no es significativo. Si es SQL_FALSE, TableName es un argumento de valor de patrón; Se trata literalmente, y su caso es significativo.

NameLength3
[Entrada] Longitud en caracteres de *NombreDeTabla.

TableType
[Entrada] Lista de tipos de tablas para coincidir.

Observa que el atributo de SQL_ATTR_METADATA_ID sentencia no tiene efecto sobre el argumento TableType . TableType es un argumento de lista de valores, independientemente de la configuración de SQL_ATTR_METADATA_ID.

NombreLongitud4
[Entrada] Longitud en caracteres de *TableType.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostics

Cuando SQLTables 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 SQLTables 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

SQLTables lista todas las tablas dentro del rango solicitado. Un usuario puede o no tener privilegios SELECT en cualquiera de estas tablas. Para comprobar la accesibilidad, una aplicación puede:

• Llama a SQLGetInfo y comprueba el tipo de información SQL_ACCESSIBLE_TABLES.

• Llama a SQLTablePrivileges para comprobar los privilegios de cada tabla.

De lo contrario, la aplicación debe ser capaz de manejar una situación en la que el usuario seleccione una tabla para la que no se concedan privilegios SELECT .

Los argumentos SchemaName y TableName aceptan patrones de búsqueda. El argumento Nombre del Catálogo acepta patrones de búsqueda si el atributo de SQL_ODBC_VERSION entorno es SQL_OV_ODBC3; No acepta patrones de búsqueda si SQL_OV_ODBC2 está activado. Si SQL_OV_ODBC3 está activado, un controlador ODBC 3*.x* requerirá que se evadan caracteres comodines en el argumento Nombre del Catálogo para ser tratados literalmente. Para más información sobre patrones de búsqueda válidos, véase Argumentos de Valor de Patrón.

Para soportar la enumeración de catálogos, esquemas y tipos de tabla, se definen las siguientes semánticas especiales para los argumentos CatalogName, SchemaName, TableName y TableType de SQLTables:

• Si CatalogName es SQL_ALL_CATALOGS y SchemaName y TableName son cadenas vacías, el conjunto de resultados contiene una lista de catálogos válidos para la fuente de datos. (Todas las columnas excepto la TABLE_CAT contienen NULLs.)

• Si SchemaName es SQL_ALL_SCHEMAS y CatalogName y TableName son cadenas vacías, el conjunto de resultados contiene una lista de esquemas válidos para la fuente de datos. (Todas las columnas excepto la TABLE_SCHEM contienen NULLs.)

• Si TableType es SQL_ALL_TABLE_TYPES y CatalogName, SchemaName y TableName son cadenas vacías, el conjunto de resultados contiene una lista de tipos de tabla válidos para la fuente de datos. (Todas las columnas excepto la columna TABLE_TYPE contienen NULLs.)

Si TableType no es una cadena vacía, debe contener una lista de valores separados por comas para los tipos de interés; Cada valor puede estar entre comillas (') o sin comillas, por ejemplo, 'TABLE', 'VIEW' o TABLE, VIEW. Una aplicación siempre debe especificar el tipo de tabla en mayúsculas; El controlador debe convertir el tipo de tabla a la mayúscula que necesite la fuente de datos. Si la fuente de datos no soporta un tipo de tabla especificado, SQLTables no devuelve ningún resultado para ese tipo.

SQLTables devuelve los resultados como un conjunto estándar, ordenado por TABLE_TYPE, TABLE_CAT, TABLE_SCHEM y TABLE_NAME. Para obtener información sobre cómo se puede usar esta información, vea Usos de datos de catálogo.

Para determinar la longitud real de las columnas de TABLE_CAT, TABLE_SCHEM y TABLE_NAME, una aplicación puede llamar a SQLGetInfo con los tipos de información SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN y SQL_MAX_TABLE_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 controlador puede definir columnas adicionales más allá de la columna 5 (REMARKS). 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.

Example

El siguiente código de ejemplo no libera manejadores ni conexiones. Consulta SQLFreeHandle Function y SQLFreeStmt Function para ejemplos de código de freehandles e instrucciones.

// SQLTables.cpp  
// compile with: user32.lib odbc32.lib  
#include <windows.h>  
#include <sqlext.h>  
#include <strsafe.h>  
  
// simple helper functions  
int MySQLSuccess(SQLRETURN rc) {  
   return (rc == SQL_SUCCESS || rc == SQL_SUCCESS_WITH_INFO);  
}  
  
struct DataBinding {  
   SQLSMALLINT TargetType;  
   SQLPOINTER TargetValuePtr;  
   SQLINTEGER BufferLength;  
   SQLLEN StrLen_or_Ind;  
};  
  
void printCatalog(const struct DataBinding* catalogResult) {  
   if (catalogResult[0].StrLen_or_Ind != SQL_NULL_DATA)   
      printf("Catalog Name = %s\n", (char *)catalogResult[0].TargetValuePtr);  
}  
  
// remember to disconnect and free memory, and free statements and handles  
int main() {  
   int bufferSize = 1024, i, numCols = 5;  
   struct DataBinding* catalogResult = (struct DataBinding*) malloc( numCols * sizeof(struct DataBinding) );  
   wchar_t* dbName = (wchar_t *)malloc( sizeof(wchar_t)*bufferSize );  
   wchar_t* userName = (wchar_t *)malloc( sizeof(wchar_t)*bufferSize );  
  
   // declare and initialize the environment, connection, statement handles  
   SQLHENV henv = NULL;   // Environment     
   SQLHDBC hdbc = NULL;   // Connection handle  
   SQLHSTMT hstmt = NULL;   // Statement handle  
  
   SQLRETURN retCode;  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
   SQLWCHAR connStrbuffer[1024];  
   SQLSMALLINT connStrBufferLen;  
  
   retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, -1);  
   retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
   retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);  
   retCode = SQLDriverConnect(hdbc, desktopHandle, (SQLCHAR*)"Driver={SQL Server}", SQL_NTS, (SQLCHAR*)connStrbuffer, 1024 + 1, &connStrBufferLen, SQL_DRIVER_PROMPT);  
   retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
   retCode = SQLGetInfo(hdbc, SQL_DATABASE_NAME, dbName, (SQLSMALLINT)bufferSize, (SQLSMALLINT *)&bufferSize);  
   retCode = SQLGetInfo(hdbc, SQL_USER_NAME, userName, (SQLSMALLINT)bufferSize, (SQLSMALLINT *)&bufferSize);  
  
   bufferSize = 1024;  
  
   // allocate memory for the binding  
   // free this memory when done  
   for ( i = 0 ; i < numCols ; i++ ) {  
      catalogResult[i].TargetType = SQL_C_CHAR;  
      catalogResult[i].BufferLength = (bufferSize + 1);  
      catalogResult[i].TargetValuePtr = malloc( sizeof(unsigned char)*catalogResult[i].BufferLength );  
   }  
  
   // setup the binding (can be used even if the statement is closed by closeStatementHandle)  
   for ( i = 0 ; i < numCols ; i++ )  
      retCode = SQLBindCol(hstmt, (SQLUSMALLINT)i + 1, catalogResult[i].TargetType, catalogResult[i].TargetValuePtr, catalogResult[i].BufferLength, &(catalogResult[i].StrLen_or_Ind));  
  
   // all catalogs query  
   printf( "A list of names of all catalogs\n" );  
   retCode = SQLTables( hstmt, (SQLCHAR*)SQL_ALL_CATALOGS, SQL_NTS, (SQLCHAR*)"", SQL_NTS, (SQLCHAR*)"", SQL_NTS, (SQLCHAR*)"", SQL_NTS );  
   for ( retCode = SQLFetch(hstmt) ;  MySQLSuccess(retCode) ; retCode = SQLFetch(hstmt) )  
      printCatalog( catalogResult );  
}  

Funciones relacionadas

Véase también

Referencia de la API ODBC
Archivos de encabezado de ODBC