SQLTablePrivileges 函式
一致性
引進的版本：ODBC 1.0 標準合規性：ODBC
摘要
SQLTablePrivileges 會傳回資料表清單，以及與每個資料表相關聯的許可權。 驅動程式會將資訊當做指定語句的結果集傳回。
語法
SQLRETURN SQLTablePrivileges(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * TableName,
SQLSMALLINT NameLength3);
引數
StatementHandle
[輸入]語句控制碼。
CatalogName
[輸入]資料表目錄。 如果驅動程式支援某些資料表的目錄，但不支援其他資料表，例如當驅動程式從不同的 DBMS 擷取資料時，空字串 （「」） 表示沒有目錄的資料表。 CatalogName 不能包含字串搜尋模式。
如果 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 的字元長度 。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
當 SQLTablePrivileges 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可以使用SQL_HANDLE_STMT的 HandleType 和 StatementHandle 控制碼 呼叫 SQLGetDiagRec 來取得相關聯的 SQLSTATE 值。 下表列出 SQLTablePrivileges 通常傳 回的 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 啟用非同步處理。 已呼叫 SQLTablePrivileges 函式，並在完成執行之前， 在 StatementHandle 上 呼叫 SQLCancel 或 SQLCancelHandle 。 然後，在 StatementHandle 上 再次呼叫 SQLTablePrivileges 函式 。 呼叫 SQLTablePrivileges 函式，並在完成執行之前， 從多執行緒應用程式中的不同執行緒呼叫 SQLCancel 或 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 相關聯的連接控制碼呼叫非同步執行函式。 呼叫 SQLTablePrivileges 函 式時 ，這個非同步函式仍在執行中。 （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 ，才能執行後續處理並完成作業。 |
註解
SchemaName 和 TableName 引數接受搜尋模式。 如需有效搜尋模式的詳細資訊，請參閱 模式值引數 。
SQLTablePrivileges 會以標準結果集的形式傳回結果，依TABLE_CAT、TABLE_SCHEM、TABLE_NAME、PRIVILEGE 和 GRANTEE 排序。
若要判斷TABLE_CAT、TABLE_SCHEM和TABLE_NAME資料行的實際長度，應用程式可以使用SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN和SQL_MAX_TABLE_NAME_LEN選項呼叫 SQLGetInfo 。
注意
如需 ODBC 類別目錄函式的一般使用、引數和傳回資料的詳細資訊，請參閱 目錄函式 。
下列資料行已針對 ODBC 3.x 重新命名。 資料行名稱變更不會影響回溯相容性，因為應用程式會依資料行編號系結。
| ODBC 2.0 資料行 | ODBC 3.x 資料行 |
|---|---|
| TABLE_QUALIFIER | TABLE_CAT |
| TABLE_OWNER | TABLE_SCHEM |
下表列出結果集中的資料行。 驅動程式可以定義資料行 7 以外的其他資料行（IS_GRANTABLE）。 應用程式應該從結果集結尾倒數，而不是指定明確的序數位置，以存取驅動程式特定的資料行。 如需詳細資訊，請參閱 目錄函 式傳回的資料。
| 資料行名稱 | 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 not Null | 資料表名稱。 |
| GRANTOR （ODBC 1.0） | 4 | Varchar | 授與許可權的使用者名稱;如果不適用於資料來源，則為 Null。 對於 GRANTEE 資料行中值為物件擁有者的所有資料列，GRANTOR 資料行將會是 「_SYSTEM」。 |
| GRANTEE （ODBC 1.0） | 5 | Varchar not Null | 授與許可權的使用者名稱。 |
| PRIVILEGE （ODBC 1.0） | 6 | Varchar not Null | 資料表許可權。 可能是下列其中一項或資料來源特定的許可權。 SELECT：被授與者可以擷取資料表一或多個資料行的資料。 INSERT：被授與者可以插入包含一或多個資料行之資料的新資料列到資料表中。 UPDATE：被授與者可以更新資料表的一或多個資料行中的資料。 DELETE：被授與者可以刪除資料表中的資料列。 REFERENCES：被授與者可以參考條件約束內資料表的一或多個資料行（例如，唯一、引用或資料表檢查條件約束）。 指定資料表許可權所允許被授與者的行動範圍取決於資料來源。 例如，UPDATE 許可權可能允許被授與者在一個資料來源上更新資料表中的所有資料行，而且只有被授與者在另一個資料來源上具有 UPDATE 許可權的資料行。 |
| IS_GRANTABLE （ODBC 1.0） | 7 | Varchar | 指出被授與者是否允許將許可權授與其他使用者;如果資料來源未知或不適用，則為 「YES」、「NO」 或 Null。 許可權是可授與或不可授與，但不能同時授與。 SQLColumnPrivileges 傳 回的結果集永遠不會包含兩個數據列，除了IS_GRANTABLE資料行包含相同的值之外，所有資料行都不包含這些資料列。 |
程式碼範例
如需類似函式的程式碼範例，請參閱 SQLColumns 。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 將緩衝區系結至結果集中的資料行 | SQLBindCol 函式 |
| 取消語句處理 | SQLCancel 函式 |
| 傳回資料行或資料行的許可權 | SQLColumnPrivileges 函式 |
| 傳回資料表或資料表中的資料行 | SQLColumns 函式 |
| 以正向方向擷取單一資料列或資料區塊 | SQLFetch 函式 |
| 擷取資料區塊或捲動結果集 | SQLFetchScroll 函式 |
| 傳回資料表統計資料和索引 | SQLStatistics 函式 |
| 傳回資料來源中的資料表清單 | SQLTables 函數 |