SQLTables 函數

發行項
08/21/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_ODBC_VERSION環境屬性已SQL_OV_ODBC3，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 搭配 SQL_HANDLE_STMT的 HandleType 和 StatementHandle 控制碼 ，即可取得相關聯的 SQLSTATE 值。下表列出 SQLTable 通常會傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法「（DM）」在驅動程式管理員傳回的 SQLSTATE 描述之前。除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

SQLSTATE	錯誤	描述
01000	一般警告	驅動程式特定的資訊訊息。（函式會傳回SQL_SUCCESS_WITH_INFO。）
08S01	通訊連結失敗	驅動程式與驅動程式連線的資料來源之間的通訊連結在函式完成處理之前失敗。
24000	不正確資料指標狀態	已開啟 StatementHandle 上的資料指標，並已呼叫 SQLFetch 或 SQLFetchScroll 。如果 SQLFetch 或 SQLFetchScroll 尚未傳回SQL_NO_DATA，而且如果 SQLFetch 或 SQLFetchScroll 傳回SQL_NO_DATA，驅動程式就會傳回此錯誤。語句上已開啟資料指標，但未呼叫 SQLFetch* 或 SQLFetchScroll 。*
40001	序列化失敗	交易因為與另一個交易發生資源死結而回復。
40003	語句完成未知	此函式執行期間相關聯的連接失敗，且無法判斷交易的狀態。
HY000	一般錯誤	發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 MessageText 緩衝區中* SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。
HY001	記憶體配置錯誤	驅動程式無法配置支援執行或完成函式所需的記憶體。
HY008	作業已取消	已針對 StatementHandle 啟用非同步處理。已呼叫函式，並在完成執行之前，在 StatementHandle 上呼叫 SQLCancel 或 SQLCancelHandle 。然後在 StatementHandle 上再次呼叫函式。呼叫函式，並在完成執行之前，從多執行緒應用程式中的不同執行緒呼叫語句Handle 或 SQLCancelHandle 。
HY009	不正確 Null 指標使用	SQL_ATTR_METADATA_ID語句屬性已設定為 SQL_TRUE、 CatalogName 引數為 null 指標，而且 infoType SQL_CATALOG_NAME 會傳回支援目錄名稱。（DM） SQL_ATTR_METADATA_ID語句屬性設定為 SQL_TRUE，而 SchemaName 或 TableName 引數為 null 指標。
HY010	函式順序錯誤	（DM）已針對與 StatementHandle 相關聯的連接控制碼呼叫非同步執行函式。呼叫 SQLTable 時，這個非同步函式仍在執行中。（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，CatalogName 引數會接受搜尋模式;如果已設定SQL_OV_ODBC2，則不接受搜尋模式。如果已設定SQL_OV_ODBC3，ODBC 3*.x* 驅動程式會要求逸出 CatalogName 引數中的 萬用字元，才能以常值方式處理。如需有效搜尋模式的詳細資訊，請參閱模式值引數。

注意

如需 ODBC 類別目錄函式的一般使用、引數和傳回資料的詳細資訊，請參閱目錄函式。

為了支援目錄、架構和資料表類型的列舉，SQLTables 的 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欄以外的所有資料行都包含 Null。）

如果 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）。應用程式應該從結果集結尾倒數，而不是指定明確的序數位置，來存取驅動程式特定的資料行。如需詳細資訊，請參閱目錄函式傳回的資料。

資料行名稱	Column number	資料類型	註解
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 函式
傳回資料表統計資料和索引	SQLStatistics 函式
傳回資料表或資料表的許可權	SQLTablePrivileges 函式

另請參閱

ODBC API 參考
 ODBC 標頭檔

共用方式為

SQLTables 函數

語法

引數

傳回

診斷

註解

範例

另請參閱

意見反應

其他資源

共用方式為

SQLTables 函數

語法

引數

傳回

診斷

註解

範例

相關函數

另請參閱

意見反應

其他資源