SQLTables 函数

一致性
推出版本：ODBC 1.0 标准合规性：开放组

总结
SQLTables 返回存储在特定数据源中的表、目录或模式名称及表类型列表。 驱动程序以结果集的形式返回信息。

Syntax

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

Arguments

StatementHandle
[输入]检索结果的语句handle。

CatalogName
[输入]目录名称。 如果SQL_ODBC_VERSION环境属性为SQL_OV_ODBC3，目录 名 参数接受搜索模式;如果SQL_OV_ODBC2设置，它不接受搜索模式。 如果驱动程序支持某些表的目录，而其他表不支持，例如驱动程序从不同数据库管理系统检索数据时，空字符串（“”）表示没有目录的表。

如果SQL_ATTR_METADATA_ID语句属性设置为SQL_TRUE，目录 名 被视为标识符，其大小写不重要。 如果是SQL_FALSE，目录 名 是一个模式值参数;它被字面处理，且其案例意义重大。 有关详细信息，请参阅目录函数中的参数。

NameLength1
[输入]*目录名称字符长度。

SchemaName
[输入]模式名称的字符串搜索模式。 如果驱动程序支持某些表的模式，但不支持其他表，例如当驱动程序从不同数据库管理系统检索数据时，空字符串（“”）表示那些没有模式的表。

如果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. 的字符长度。

Returns

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。

Diagnostics

当 SQLTables 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用 SQLGetDiagRec 获得关联的 SQLSTATE 值，Handle（Handle）为 SQL_HANDLE_STMT，Handle（Handle）为 StatementHandle。 下表列出了 SQLTables 通常返回的SQLSTATE值，并在此函数的上下文中解释了每个值;“（DM）” 符号位于驱动程序管理器返回的 SQLSTATE 描述之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。

SQLSTATE	Error	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。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。
HY001	内存分配错误	驱动程序无法分配支持执行或完成函数所需的内存。
HY008	操作已取消	为 StatementHandle 启用了异步处理。 调用了该函数，在完成执行之前，对 StatementHandle 调用了 SQLCancel 或 SQLCancelHandle。 然后，在 StatementHandle 上再次调用该函数。 调用了函数，在完成执行之前，SQLCancel 或 SQLCancelHandle 从多线程应用程序中的不同线程调用 StatementHandle。
HY009	无效使用 null 指针	SQL_ATTR_METADATA_ID语句属性被设置为 SQL_TRUE，CatalogName 参数是空指针，SQL_CATALOG_NAME InfoType 返回支持目录名称。 （DM） SQL_ATTR_METADATA_ID语句属性被设置为 SQL_TRUE，SchemaName 或 TableName 参数是空指针。
HY010	函数序列错误	（DM） 为与 StatementHandle 关联的连接句柄调用异步执行函数。 当调用SQLTables时，这个异步函数仍在运行。 （DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect 或 SQLMoreResults，并返回了SQL_PARAM_DATA_AVAILABLE。 在检索所有流式处理参数的数据之前调用此函数。 （DM） 为 StatementHandle 调用异步执行函数（而不是此函数），并在调用此函数时仍在执行。 （DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，并返回了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 检查每个表的权限。

否则，应用程序必须能够处理用户选择未授予 SELECT 权限的表的情况。

SchemaName 和 TableName 参数接受搜索模式。 如果SQL_ODBC_VERSION环境属性为SQL_OV_ODBC3，目录 名 参数接受搜索模式;如果SQL_OV_ODBC2设置，它不接受搜索模式。 如果设置了 SQL_OV_ODBC3，ODBC 3*.x* 驱动将要求 CatalogName 参数中的万用字符必须逃逸，才能字面处理。 有关有效搜索模式的更多信息，请参见 模式值参数。

注释

有关 ODBC 目录函数的常规用途、参数和返回数据的详细信息，请参阅 目录函数。

为了支持目录、模式和表类型的枚举，SQLTables 的 CatalogName、SchemaName、TableName 和 TableType 参数定义了以下特殊语义：

• 如果 CatalogName 是 SQL_ALL_CATALOGS，SchemaName 和 TableName 是空字符串，结果集包含该数据源的有效目录列表。 （除TABLE_CAT列外，所有列均包含NULLs。）

• 如果 SchemaName 是 SQL_ALL_SCHEMAS，CatalogName 和 TableName 是空字符串，结果集包含该数据源的有效模式列表。 （除TABLE_SCHEM列外，所有列均包含NULLs。）

• 如果 TableType 是 SQL_ALL_TABLE_TYPES，且 CatalogName、 SchemaName 和 TableName 是空字符串，结果集包含该数据源的有效表类型列表。 （除TABLE_TYPE列外，所有列均包含NULLs。）

如果 TableType 不是空字符串，它必须包含一个逗号分隔的兴趣类型值列表;每个值可以用单引号（'）或不引号包裹，例如，'TABLE'、'VIEW'TABLEVIEW或，。 应用程序应始终用大写字母指定表类型;驱动程序应将表类型转换为数据源所需的具体情况。 如果数据源不支持指定的表类型， SQLTables 不会返回该类型的任何结果。

SQLTables 以标准结果集的形式返回，按TABLE_TYPE、TABLE_CAT、TABLE_SCHEM和TABLE_NAME排序。 有关如何使用此信息的信息，请参阅 目录数据的用法。

为了确定TABLE_CAT、TABLE_SCHEM和TABLE_NAME列的实际长度，应用程序可以调用带有SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN和SQL_MAX_TABLE_NAME_LEN信息类型的 SQLGetInfo 。

以下列已更名为ODBC 3*.x*。 列名的更改不会影响向后兼容，因为应用程序按列号绑定。

ODBC 2.0 列	ODBC 3*.x* 列
TABLE_QUALIFIER (表格限定符)	TABLE_CAT
表所有者	TABLE_SCHEM

下表列出了结果集中的列。 驾驶员还可以定义第5列以外的额外列（注释）。 应用程序应从结果集的末尾倒计时，而不是指定显式序号位置来访问特定于驱动程序的列。 有关详细信息，请参阅 目录函数返回的数据。

列名称	列号	数据类型	注释
TABLE_CAT（ODBC 1.0）	1	Varchar	目录名称;如果不适用于数据源，则使用NULL。 如果驱动程序支持某些表的目录，但不支持其他表，例如当驱动程序从不同数据库管理系统检索数据时，对于没有目录的表，驱动程序会返回一个空字符串（“”）。
TABLE_SCHEM（ODBC 1.0）	2	Varchar	模式名称;如果不适用于数据源，则使用NULL。 如果驱动程序支持某些表的模式，而不支持其他表，例如当驱动程序从不同数据库管理系统检索数据时，对于没有模式的表，驱动程序会返回一个空字符串（“”）。
TABLE_NAME（ODBC 1.0）	3	Varchar	表名。
TABLE_TYPE（ODBC 1.0）	4	Varchar	表类型名称;以下之一：“TABLE”、“”、“系统VIEW”、“全局临时”、“本地临时”、“别名”、“TABLE”“或特定数据SYNONYM源类型名称。 “ALIAS”和“SYNONYM”“的含义因驱动而异。
备注（ODBC 1.0）	5	Varchar	对这张桌子的描述。

Example

以下示例代码不释放句柄和连接。 请参阅 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 函数

相关内容

• ODBC API 参考
• ODBC 头文件