符合性
版本引入了: ODBC 1.0 标准符合性: 打开组
摘要
SQLTables返回的表、 目录或架构名称和特定的数据源中存储的表类型的列表。 驱动程序返回的信息作为结果集。
语法
SQLRETURN SQLTables(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * TableName,
SQLSMALLINT NameLength3,
SQLCHAR * TableType,
SQLSMALLINT NameLength4);
参数
StatementHandle
[输入]语句句柄中检索结果。
CatalogName
[输入]目录名称。 CatalogName参数接受搜索模式,如果 SQL_ODBC_VERSION 环境属性是 SQL_OV_ODBC3; 它不接受搜索模式,如果 SQL_OV_ODBC2 设置。 如果驱动程序支持目录有关的某些表而不是其他人,例如当驱动程序检索数据从不同 Dbms,空字符串 ("") 指示没有目录的那些表。
如果 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE, CatalogName视为标识符和其大小写并不重要。 SQL_FALSE,若是CatalogName是模式值自变量; 按字面意思,处理和其大小写很重要。 有关详细信息,请参阅中目录函数的自变量。
NameLength1
[输入]以字符为单位的长度 *CatalogName。
SchemaName
[输入]架构名称的字符串搜索模式。 如果驱动程序支持架构有关的某些表而不是其他人,例如当驱动程序检索数据从不同 Dbms,空字符串 ("") 指示没有架构的那些表。
如果 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE, SchemaName视为标识符和其大小写并不重要。 SQL_FALSE,若是SchemaName是模式值自变量; 按字面意思,处理和其大小写很重要。
NameLength2
[输入]以字符为单位的长度 *SchemaName。
TableName
[输入]表名称的字符串搜索模式。
如果 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE, TableName视为标识符和其大小写并不重要。 SQL_FALSE,若是TableName是模式值自变量; 按字面意思,处理和其大小写很重要。
NameLength3
[输入]以字符为单位的长度 *TableName。
TableType
[输入]要匹配的表类型的列表。
请注意,SQL_ATTR_METADATA_ID 语句属性不起作用后TableType参数。 TableType是值列表自变量,而不考虑 SQL_ATTR_METADATA_ID 的设置。
NameLength4
[输入]以字符为单位的长度 *TableType。
返回
SQL_SUCCESS、 SQL_SUCCESS_WITH_INFO、 SQL_STILL_EXECUTING、 SQL_ERROR 或 SQL_INVALID_HANDLE。
诊断
当SQLTables返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO,关联的 SQLSTATE 值可以通过调用来获取SQLGetDiagRec与HandleType的 SQL_HANDLE_STMT 和一个处理的StatementHandle。 下表列出了通常由返回的 SQLSTATE 值SQLTables ,并解释了此函数; 每个上下文中的表示法"(数据挖掘)"之前 SQLSTATEs 返回由驱动程序管理器的说明。 与每个 SQLSTATE 值关联的返回代码是 SQL_ERROR,除非另有说明。
| SQLSTATE | 错误 | Description |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO。) |
| 08S01 | 通讯链接失败 | 该驱动程序和驱动程序已连接到数据源之间的通信链接失败之前函数已完成处理。 |
| 24000 | 游标状态无效 | 在打开游标的StatementHandle,并SQLFetch或SQLFetchScroll已调用一样。 如果此错误返回由驱动程序管理器SQLFetch或SQLFetchScroll未返回 SQL_NO_DATA 和时,返回的驱动程序SQLFetch或SQLFetchScroll已返回 sql_no_data 为止。 在打开游标的StatementHandle,但SQLFetch或SQLFetchScroll尚未调用。 |
| 40001 | 序列化失败 | 事务已回滚,由于其他事务与资源死锁。 |
| 40003 | 语句完成情况未知 | 此函数中,在执行期间失败关联的连接,无法确定事务的状态。 |
| HY000 | 常规错误 | 有关其中没有任何特定的 SQLSTATE 和为其定义任何特定于实现的 SQLSTATE 出错。 返回的错误消息SQLGetDiagRec中 *MessageText缓冲区描述错误以及其原因。 |
| HY001 | 内存分配错误 | 该驱动程序无法分配支持执行或完成该函数所需的内存。 |
| HY008 | 操作已取消 | 异步处理的已启用StatementHandle。 调用该函数,和之前执行完毕SQLCancel或SQLCancelHandle上调用了StatementHandle。 然后在再次调用该函数StatementHandle。 调用该函数,和之前执行完毕SQLCancel或SQLCancelHandle上调用了StatementHandle来自不同线程中多线程应用程序。 |
| HY009 | 使用空指针无效 | SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE, CatalogName参数为 null 指针和 SQL_CATALOG_NAME信息类型支持目录名称返回。 (DM) SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE,并SchemaName或TableName参数是空指针。 |
| HY010 | 函数序列错误 | (DM) 为与之关联的连接句柄调用以异步方式执行的函数StatementHandle。 此异步函数仍在执行调用 SQLTables 时。 (数据挖掘) SQLExecute, SQLExecDirect,或SQLMoreResults曾为StatementHandle和返回 SQL_PARAM_DATA_可用。 数据已检索到的所有经过流处理参数之前调用此函数。 (DM) 的调用以异步方式执行的函数 (不是此类似) StatementHandle和仍在执行时调用此函数。 (数据挖掘) SQLExecute, SQLExecDirect, SQLBulkOperations,或者SQLSetPos曾为StatementHandle和返回 SQL_NEED_DATA。 数据已发送的所有执行时数据参数或列之前调用此函数。 |
| HY013 | 内存管理错误 | 无法处理函数调用,因为基础内存对象无法访问,可能是由于内存不足的情况。 |
| HY090 | 字符串或缓冲区长度无效 | (DM) 之一的长度参数值小于 0 但不是等于 SQL_NTS。 名称长度参数之一的值超出相应名称的最大长度值。 |
| HY117 | 由于未知的事务状态而挂起连接。 仅断开连接,并允许使用只读的函数。 | (DM) 有关挂起状态的详细信息,请参阅SQLEndTran 函数。 |
| HYC00 | 未实现的可选功能 | 指定一个目录,并在驱动程序或数据源不支持目录。 指定了架构,并且在驱动程序或数据源不支持架构。 目录名称、 表架构或表名称为指定的字符串搜索模式和数据源不支持的一个或多个这些参数的搜索模式。 驱动程序或数据源不支持 SQL_ATTR_CONCURRENCY 和 SQL_ATTR_CURSOR_TYPE 语句属性的当前设置的组合。 SQL_ATTR_USE_BOOKMARKS 语句属性设置为 SQL_UB_VARIABLE,并且 SQL_ATTR_CURSOR_TYPE 语句属性设置为游标类型,该驱动程序不支持书签。 |
| HYT00 | 超时时间已到 | 查询超时期限过期之前请求的结果集返回的数据源。 通过设置超时期限SQLSetStmtAttr,SQL_ATTR_QUERY_TIMEOUT。 |
| HYT01 | 连接超时时间已到 | 连接超时期限过期之前的数据源响应此请求。 通过设置连接超时期SQLSetConnectAttr,SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驱动程序不支持此函数 | (DM) 驱动程序与相关联StatementHandle不支持该函数。 |
| IM017 | 轮询异步通知模式中禁用 | 只要使用通知模型,将禁用轮询。 |
| IM018 | SQLCompleteAsync尚未调用以完成此句柄上以前的异步操作。 | 如果句柄上的上一个函数调用返回 SQL_STILL_EXECUTING,如果启用通知模式,则SQLCompleteAsync必须要对其进行后期处理并完成该操作的句柄上调用。 |
注释
SQLTables列出请求的范围中的所有表。 用户可能会或可能没有对任何这些表的 SELECT 权限。 若要检查辅助功能,应用程序可以:
-
调用SQLGetInfo并检查 SQL_ACCESSIBLE_TABLES 信息类型。
-
调用SQLTablePrivileges检查每个表的特权。
否则,应用程序必须能够处理用户为其选择一个表的位置的情况下选择未授予的权限。
SchemaName并TableName参数接受搜索模式。 CatalogName参数接受搜索模式,如果 SQL_ODBC_VERSION 环境属性是 SQL_OV_ODBC3; 它不接受搜索模式,如果 SQL_OV_ODBC2 设置。 如果设置 SQL_OV_ODBC3,ODBC 3 .x驱动程序将要求中的该通配符CatalogName参数经过转义才能视为按原义。 有关有效的搜索模式的详细信息,请参阅模式值自变量。
Note:
有关常规使用、 参数以及 ODBC 目录函数返回的数据的详细信息,请参阅目录函数。
若要支持的目录、 架构和表类型枚举,以下特殊语义为上定义CatalogName, SchemaName, TableName,并且TableType的自变量SQLTables:
-
如果CatalogName为 SQL_ALL_CATALOGS 并且SchemaName和TableName都是空字符串,结果集包含的数据源的有效目录列表。 (除 TABLE_CAT 列的所有列都包含 null 值。)
-
如果SchemaName是 SQL_ALL_SCHEMAS 和CatalogName并TableName都是空字符串,结果集包含的数据源的有效架构的列表。 (除以 TABLE_SCHEM 列的所有列都包含 null 值。)
-
如果TableType是 SQL_ALL_TABLE_TYPES 和CatalogName, SchemaName,以及TableName都是空字符串,结果集包含数据源的有效的表类型的列表。 (除 TABLE_TYPE 列的所有列都包含 null 值。)
如果TableType不是空字符串,它必须包含一系列以逗号分隔的相关类型的值; 每个值括在单引号 (') 或不带引号,例如,表、 查看或表中,查看。 应用程序应始终指定表类型中大写;该驱动程序应将表类型转换为大小写所需的数据源。 如果数据源不支持指定的表类型SQLTables不返回该类型的任何结果。
SQLTables以按 TABLE_TYPE、 TABLE_CAT、 按 TABLE_SCHEM 和 TABLE_NAME 标准结果集的形式返回结果。 有关可以如何使用此信息的信息,请参阅使用的目录数据。
若要确定 TABLE_CAT、 按 TABLE_SCHEM 和 TABLE_NAME 列的实际长度,应用程序可以调用SQLGetInfo SQL_MAX_CATALOG_NAME_LEN、 SQL_MAX_SCHEMA_NAME_LEN 和 SQL_MAX_TABLE_NAME_LEN 信息类型。
以下各列已重命名为 ODBC 3 .x。 列名称更改不会影响后向兼容性,因为应用程序将绑定的列号。
| ODBC 2.0 列 | ODBC 3 .x列 |
|---|---|
| TABLE_QUALIFIER | TABLE_CAT |
| TABLE_OWNER | TABLE_SCHEM |
下表列出了在结果集中的列。 列 5 (备注) 之外的其他列可以定义由驱动程序。 应用程序应获得访问驱动程序特定列的倒计时从结果集而不是指定显式的序号位置的末尾。 有关详细信息,请参阅目录函数返回数据。
| 列名 | 列号 | 数据类型 | 注释 |
|---|---|---|---|
| TABLE_CAT (ODBC 1.0) | 1 | Varchar | 目录名称;如果不适用于数据源为 NULL。 如果驱动程序支持目录有关的某些表而不是其他人,如当驱动程序检索数据时从不同 Dbms,它返回空字符串 ("") 不具有目录这些表。 |
| 按 TABLE_SCHEM (ODBC 1.0) | 2 | Varchar | 架构名称;如果不适用于数据源为 NULL。 如果驱动程序支持架构有关的某些表而不是其他人,如当驱动程序检索数据时从不同 Dbms,它返回空字符串 ("") 不具有架构的这些表。 |
| TABLE_NAME (ODBC 1.0) | 3 | Varchar | 表名。 |
| TABLE_TYPE (ODBC 1.0) | 4 | Varchar | 表类型名称;以下项之一:"表"、"视图"、"系统表"、"全局临时"、"本地临时"、"别名"、"同义词"或数据源特定于类型名称。 "别名"和"同义词"的含义是特定于驱动程序。 |
| 备注 (ODBC 1.0) | 5 | Varchar | 表的说明。 |
示例
下面的示例代码不会释放句柄和连接。 请参阅SQLFreeHandle 函数并SQLFreeStmt 函数有关代码示例以释放句柄和语句。
// 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 );
}
相关函数
| 有关信息 | 请参阅 |
|---|---|
| 将缓冲区绑定到结果集中的列 | SQLBindCol 函数 |
| 取消语句处理 | SQLCancel 函数 |
| 返回一个或多列的权限 | SQLColumnPrivileges 函数 |
| 返回一个表或表中的列 | SQLColumns 函数 |
| 提取单个行或仅向前方向中的数据块 | SQLFetch 函数 |
| 提取的数据块或滚动浏览结果集 | SQLFetchScroll 函数 |
| 返回表统计信息和索引 | SQLStatistics 函数 |
| 返回一个表或表的权限 | SQLTablePrivileges 函数 |
请参阅
历史资料。此文对应 2018-11-30 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 MightyPen)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。
