Función SQLTables

Conformidad
Versión introducida: Cumplimiento de estándares odbc 1.0: grupo abierto

Resumen
SQLTables devuelve la lista de nombres de tabla, catálogo o esquema y tipos de tabla, almacenados en un origen de datos específico. El controlador devuelve la información como un conjunto de resultados.

Sintaxis

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

Argumentos

StatementHandle
[Entrada] Identificador de instrucción para los resultados recuperados.

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

Si el atributo de instrucción 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, CatalogName es un argumento de valor de patrón; se trata literalmente y su caso es significativo. Para obtener más información, vea Argumentos en funciones de catálogo.

NameLength1
[Entrada] Longitud en caracteres de *CatalogName.

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

Si el atributo de instrucción 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, SchemaName es un argumento de valor de patrón; se trata literalmente y su caso es significativo.

NameLength2
[Entrada] Longitud en caracteres de *SchemaName.

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

Si el atributo de instrucción SQL_ATTR_METADATA_ID se establece en SQL_TRUE, TableName se trata como 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 *TableName.

TableType
[Entrada] Lista de tipos de tabla que deben coincidir.

Observe que el atributo de instrucción SQL_ATTR_METADATA_ID no tiene ningún efecto en el argumento TableType . TableType es un argumento de lista de valores, independientemente de la configuración de SQL_ATTR_METADATA_ID.

NameLength4
[Entrada] Longitud en caracteres de *TableType.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnóstico

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 identificador de StatementHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLTables y se explica cada uno en el contexto de esta función; la notación "(DM)" precede a las descripciones de SQLSTATEs devueltas por el Administrador de controladores. El código de retorno asociado a cada valor SQLSTATE es SQL_ERROR, a menos que se indique lo contrario.

Comentarios

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

• Llame a SQLGetInfo y compruebe el tipo de información SQL_ACCESSIBLE_TABLES.

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

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

Los argumentos SchemaName y TableName aceptan patrones de búsqueda. El argumento CatalogName acepta patrones de búsqueda si el atributo de entorno SQL_ODBC_VERSION es SQL_OV_ODBC3; no acepta patrones de búsqueda si se establece SQL_OV_ODBC2. Si se establece SQL_OV_ODBC3, un controlador ODBC 3*.x* requerirá que los caracteres comodín del argumento CatalogName se escapen para tratarse literalmente. Para obtener más información sobre los patrones de búsqueda válidos, vea Argumentos de valor de patrón.

Para admitir 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 el origen de datos. (Todas las columnas excepto la columna TABLE_CAT contienen VALORES NULL).

• 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 el origen de datos. (Todas las columnas excepto la columna TABLE_SCHEM contienen VALORES NULL).

• 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 el origen de datos. (Todas las columnas excepto la columna TABLE_TYPE contienen VALORES NUL).

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 se puede incluir entre comillas simples (') 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 en cualquier caso que necesite el origen de datos. Si el origen de datos no admite un tipo de tabla especificado, SQLTables no devuelve ningún resultado para ese tipo.

SQLTables devuelve los resultados como un conjunto de resultados 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 las longitudes reales 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.

Se ha cambiado el nombre de las columnas siguientes para ODBC 3*.x*. Los cambios en el nombre de columna no afectan a la compatibilidad con versiones anteriores porque las aplicaciones se enlazan 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 (COMENTARIOS). 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

El código de ejemplo siguiente no libera identificadores ni conexiones. Vea Función SQLFreeHandle y Función SQLFreeStmt para obtener ejemplos de código para liberar identificadores 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

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC