符合性
推出版本：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。
目錄名稱
[輸入]目錄名稱。 如果SQL_ODBC_VERSION環境屬性為 SQL_OV_ODBC3，CatalogName 參數會接受搜尋模式;如果SQL_OV_ODBC2設定，則不接受搜尋模式。 若驅動程式支援某些資料表的目錄，但其他資料表不支援，例如當驅動從不同資料庫管理系統（DBMS）取得資料時，空字串（“”）表示那些沒有目錄的資料表。
若SQL_ATTR_METADATA_ID語句屬性設為 SQL_TRUE，目錄 名稱 被視為識別碼，其大小寫不重要。 若 SQL_FALSE，CatalogName 是一個模式值參數;它被字面上處理，且其案例意義重大。 如需詳細資訊，請參閱目錄函式中的引數。
名稱長度1
[輸入]*目錄名稱的字元長度。
結構名稱
[輸入]結構名稱的字串搜尋模式。 若驅動程式支援某些資料表的結構，但不支援其他資料表，例如從不同資料庫管理系統（DBMS）取得資料時，空字串（“”）表示那些沒有結構的資料表。
若SQL_ATTR_METADATA_ID語句屬性設為 SQL_TRUE，SchemaName 被視為識別碼，其情況不重要。 若為 SQL_FALSE，SchemaName 是一個模式值參數;它被字面上處理，且其案例意義重大。
名稱長度2
[輸入]*SchemaName.
TableName
[輸入]表格名稱的字串搜尋模式。
若 SQL_ATTR_METADATA_ID 陳述句屬性設為 SQL_TRUE，TableName 被視為識別碼，其大小寫不具意義。 如果是 SQL_FALSE，TableName 是一個模式值參數;它被字面上處理，且其案例意義重大。
名稱長度3
[輸入]*TableName 字元長度。
TableType
[輸入]匹配的桌子類型清單。
請注意，SQL_ATTR_METADATA_ID 陳述屬性對 TableType 參數沒有影響。 TableType 是值清單參數，無論 Table 的設定為何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 值，並將 HandleType 為 SQL_HANDLE_STMT，Handle 為 StatementHandle 。 下表列出 SQLTables 通常回傳的 SQLSTATE 值，並在此函式的情境中說明每個值;「（DM）」符號會置於驅動程式管理器回傳的 SQLSTATE 描述前。 除非另有說明，否則與每個 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。 *MessageText 緩衝區中 SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY008 | 作業已取消 | 已針對 StatementHandle 啟用異步處理。 已呼叫函式，並在完成執行之前，在 StatementHandle 上呼叫 SQLCancel 或 SQLCancelHandle。 然後在 StatementHandle 上再次呼叫函式。 呼叫函式，並在完成執行之前，從多線程應用程式中的不同線程呼叫語句Handle 或 SQLCancelHandle。 |
| 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，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'或 TABLEVIEW。 應用程式應始終以大寫標示資料表類型;驅動程式應將資料表類型轉換為資料來源所需的案例。 若資料來源不支援指定資料表類型， 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_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 | 資料表類型名稱;以下之一：「TABLE“、”“、”VIEW系統 TABLE“、”全域臨時“、”本地臨時“、”別名“、”SYNONYM“”，或特定資料來源的類型名稱。 「ALIAS」和「SYNONYM」的意義是針對驅動程式而定的。 |
| 備註（ODBC 1.0） | 5 | Varchar | 對這張桌子的描述。 |
Example
以下範例程式碼未釋放 handles 與 connections。 請參閱 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 函式 |