Función SQLTables

Artículo
05/23/2023

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.

SQLSTATE	Error	Descripción
01000	Advertencia general	Mensaje informativo específico del controlador. (Function devuelve SQL_SUCCESS_WITH_INFO).
08S01	Error de vínculo de comunicación	Se produjo un error en el vínculo de comunicación entre el controlador y el origen de datos al que se conectó el controlador antes de que la función completara el procesamiento.
24000	Estado de cursor no válido	Se ha abierto un cursor en StatementHandle y se ha llamado a SQLFetch o SQLFetchScroll . El Administrador de controladores devuelve este error si SQLFetch o SQLFetchScroll no ha devuelto SQL_NO_DATA y el controlador devuelve si SQLFetch o SQLFetchScroll ha devuelto SQL_NO_DATA. Se ha abierto un cursor en StatementHandle, pero no se ha llamado a SQLFetch o SQLFetchScroll .
40001	Error de serialización	La transacción se revierte debido a un interbloqueo de recursos con otra transacción.
40003	Finalización de instrucciones desconocida	Error en la conexión asociada durante la ejecución de esta función y no se puede determinar el estado de la transacción.
HY000	Error general	Se produjo un error para el que no había ningún SQLSTATE específico y para el que no se definió SQLSTATE específico de la implementación. El mensaje de error devuelto por SQLGetDiagRec en el búfer *MessageText describe el error y su causa.
HY001	Error de asignación de memoria	El controlador no pudo asignar memoria necesaria para admitir la ejecución o finalización de la función.
HY008	Operación cancelada	El procesamiento asincrónico se ha habilitado para StatementHandle. Se llamó a la función y antes de completar la ejecución, se llamó a SQLCancel o SQLCancelHandle en statementHandle. A continuación, se llamó a la función de nuevo en StatementHandle. Se llamó a la función y antes de completar la ejecución, se llamó a SQLCancel o SQLCancelHandle en statementHandle desde un subproceso diferente en una aplicación multiproceso.
HY009	Uso no válido del puntero nulo	El atributo de instrucción SQL_ATTR_METADATA_ID se estableció en SQL_TRUE, el argumento CatalogName era un puntero nulo y el SQL_CATALOG_NAME InfoType devuelve que se admiten nombres de catálogo. (DM) El atributo de instrucción SQL_ATTR_METADATA_ID se estableció en SQL_TRUE y el argumento SchemaName o TableName era un puntero nulo.
HY010	Error de secuencia de función	(DM) Se llamó a una función de ejecución asincrónica para el identificador de conexión asociado a StatementHandle. Esta función asincrónica todavía se estaba ejecutando cuando se llamó a SQLTables. (DM) SE llamó a SQLExecute, SQLExecDirect o SQLMoreResults para la instrucciónHandle y devolvió SQL_PARAM_DATA_AVAILABLE. Se llamó a esta función antes de recuperar los datos para todos los parámetros transmitidos. (DM) Se llamó a una función de ejecución asincrónica (no esta) para statementHandle y todavía se estaba ejecutando cuando se llamó a esta función. (DM) SE llamó a SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos para la instrucciónHandle y devolvió SQL_NEED_DATA. Se llamó a esta función antes de enviar datos para todos los parámetros o columnas de datos en ejecución.
HY013	Error de administración de memoria	No se pudo procesar la llamada de función porque no se pudo acceder a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja.
HY090	Longitud de búfer o cadena no válida	(DM) El valor de uno de los argumentos de longitud era menor que 0, pero no igual a SQL_NTS. El valor de uno de los argumentos de longitud de nombre superó el valor de longitud máxima para el nombre correspondiente.
HY117	La conexión se suspende debido a un estado de transacción desconocido. Solo se permiten funciones de desconexión y de solo lectura.	(DM) Para obtener más información sobre el estado suspendido, vea Función SQLEndTran.
HYC00	Característica opcional no implementada	Se especificó un catálogo y el controlador o el origen de datos no admite catálogos. Se especificó un esquema y el controlador o el origen de datos no admite esquemas. Se especificó un patrón de búsqueda de cadenas para el nombre del catálogo, el esquema de tabla o el nombre de tabla, y el origen de datos no admite patrones de búsqueda para uno o varios de esos argumentos. La combinación de la configuración actual del SQL_ATTR_CONCURRENCY y los atributos de instrucción SQL_ATTR_CURSOR_TYPE no se admiten en el controlador o el origen de datos. El atributo de instrucción SQL_ATTR_USE_BOOKMARKS se estableció en SQL_UB_VARIABLE y el atributo de instrucción SQL_ATTR_CURSOR_TYPE se estableció en un tipo de cursor para el que el controlador no admite marcadores.
HYT00	Tiempo de espera agotado	El período de tiempo de espera de la consulta expiró antes de que el origen de datos devolva el conjunto de resultados solicitado. El período de tiempo de espera se establece a través de SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01	Se ha agotado el tiempo de espera de la conexión.	El período de tiempo de espera de conexión expiró antes de que el origen de datos respondiera a la solicitud. El período de tiempo de espera de conexión se establece a través de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	El controlador no admite esta función	(DM) El controlador asociado a StatementHandle no admite la función .
IM017	El sondeo está deshabilitado en modo de notificación asincrónica	Cada vez que se usa el modelo de notificación, el sondeo está deshabilitado.
IM018	No se ha llamado a SQLCompleteAsync para completar la operación asincrónica anterior en este identificador.	Si la llamada de función anterior en el identificador devuelve SQL_STILL_EXECUTING y si el modo de notificación está habilitado, se debe llamar a SQLCompleteAsync en el identificador para realizar el procesamiento posterior y completar la operación.

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.

Nota

Para obtener más información sobre el uso general, los argumentos y los datos devueltos de las funciones de catálogo ODBC, vea Funciones de catálogo.

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.

Columna ODBC 2.0	Columna ODBC 3.x
TABLE_QUALIFIER	TABLE_CAT
TABLE_OWNER	TABLE_SCHEM

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.

Nombre de la columna	Número de columna	Tipo de datos	Comentarios
TABLE_CAT (ODBC 1.0)	1	Varchar	Nombre del catálogo; NULL si no es aplicable al origen de datos. Si un controlador admite catálogos para algunas tablas, pero no para otras, como cuando el controlador recupera datos de diferentes DBMS, devuelve una cadena vacía ("") para las tablas que no tienen catálogos.
TABLE_SCHEM (ODBC 1.0)	2	Varchar	Nombre del esquema; NULL si no es aplicable al origen de datos. Si un controlador admite esquemas para algunas tablas, pero no para otras, como cuando el controlador recupera datos de diferentes DBMS, devuelve una cadena vacía ("") para esas tablas que no tienen esquemas.
TABLE_NAME (ODBC 1.0)	3	Varchar	Nombre de la tabla.
TABLE_TYPE (ODBC 1.0)	4	Varchar	Nombre del tipo de tabla; uno de los siguientes: "TABLE", "VIEW", "SYSTEM TABLE", "GLOBAL TEMPORARY", "LOCAL TEMPORARY", "ALIAS", "SYNONYM" o un nombre de tipo específico del origen de datos. Los significados de "ALIAS" y "SYNONYM" son específicos del controlador.
COMENTARIOS (ODBC 1.0)	5	Varchar	Descripción de la tabla.

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

Para información acerca de	Vea
Enlace de un búfer a una columna de un conjunto de resultados	SQLBindCol (función)
Cancelación del procesamiento de instrucciones	Función SQLCancel
Devolver privilegios para una columna o columnas	Función SQLColumnPrivileges
Devolver las columnas de una tabla o tablas	Función SQLColumns
Capturar una sola fila o un bloque de datos en una dirección de solo avance	Función SQLFetch
Capturar un bloque de datos o desplazarse por un conjunto de resultados	Función SQLFetchScroll
Devolver estadísticas e índices de tabla	Función SQLStatistics
Devolver privilegios para una tabla o tablas	Función SQLTablePrivileges

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC

Compartir a través de

Función SQLTables

Sintaxis

Argumentos

Devoluciones

Diagnóstico

Comentarios

Ejemplo

Consulte también

Comentarios

Recursos adicionales

Compartir a través de

Función SQLTables

Sintaxis

Argumentos

Devoluciones

Diagnóstico

Comentarios

Ejemplo

Funciones relacionadas

Consulte también

Comentarios

Recursos adicionales