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。

注释

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 参数中的万用字符必须逃逸，才能字面处理。 有关有效搜索模式的更多信息，请参见 模式值参数。

为了支持目录、模式和表类型的枚举，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*。 列名的更改不会影响向后兼容，因为应用程序按列号绑定。

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

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

相关函数

另请参阅

ODBC API 参考
ODBC 头文件