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.
| 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 );
}
Funciones relacionadas
| 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
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de