SQLTables 函数

项目
05/23/2023

一致性
引入的版本：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
[输入]目录名称。如果SQL_OV_ODBC3 SQL_ODBC_VERSION环境属性，则 CatalogName 参数接受搜索模式;如果设置了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时，可以通过调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值，该 SQLGetDiagRec 的 HandleType 为 SQL_HANDLE_STMT，句柄为 StatementHandle。下表列出了通常由 SQLTable 返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。

SQLSTATE	错误	说明
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 关联的连接句柄调用了异步执行的函数。调用 SQLTable 时，此异步函数仍在执行。 (DM) SQLExecute、 SQLExecDirect 或 SQLMoreResults 已为 StatementHandle 调用并返回SQL_PARAM_DATA_AVAILABLE。此函数是在检索所有流式处理参数的数据之前调用的。 (DM) 为 StatementHandle 调用了异步执行的函数 (不是此函数) ，并且调用此函数时仍在执行。 (DM) 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 以检查每个表的权限。

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

SchemaName 和 TableName 参数接受搜索模式。如果SQL_OV_ODBC3 SQL_ODBC_VERSION环境属性，则 CatalogName 参数接受搜索模式;如果设置了SQL_OV_ODBC2，则不接受搜索模式。如果设置了SQL_OV_ODBC3，ODBC 3*.x* 驱动程序将要求对 CatalogName 参数中的通配符进行转义，以便按字面处理。有关有效搜索模式的详细信息，请参阅模式值参数。

注意

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

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

如果 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列之外的所有列都包含 NULLs.)

如果 TableType 不是空字符串，则它必须包含相关类型的逗号分隔值列表;每个值都可以用单引号括起来， (') 或未加引号，例如'TABLE'、'VIEW'或 TABLE，VIEW。应用程序应始终以大写形式指定表类型;驱动程序应将表类型转换为数据源所需的任何大小写。如果数据源不支持指定的表类型， 则 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_OWNER	TABLE_SCHEM

下表列出了结果集中的列。驱动程序可以定义第 5 列以外的其他列 (REMARKS) 。应用程序应通过从结果集末尾倒计时而不是指定显式序号位置来获取对特定于驱动程序的列的访问权限。有关详细信息，请参阅目录函数返回的数据。

列名称	列号	数据类型	注释
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	表类型名称;下列类型之一：“TABLE”、“VIEW”、“SYSTEM TABLE”、“GLOBAL TEMPORARY”、“LOCAL TEMPORARY”、“ALIAS”、“SYNONYM”或数据源特定的类型名称。 “ALIAS”和“SYNONYM”的含义特定于驱动程序。
备注 (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 Function（SQLFetchScroll 函数）
返回表统计信息和索引	SQLStatistics 函数
返回一个或多个表的权限	SQLTablePrivileges Function（SQLTablePrivileges 函数）

另请参阅

ODBC API 参考
 ODBC 头文件

通过

SQLTables 函数

语法

参数

返回

诊断

注释

示例

另请参阅

反馈

其他资源

通过

SQLTables 函数

语法

参数

返回

诊断

注释

示例

相关函数

另请参阅

反馈

其他资源