SQLColumnPrivileges 函式
一致性
引進的版本：ODBC 1.0 標準合規性：ODBC
摘要
SQLColumnPrivileges 會傳回指定資料表的資料行和相關聯許可權清單。 驅動程式會將資訊當做指定 StatementHandle 的結果集傳回。
語法
SQLRETURN SQLColumnPrivileges(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * TableName,
SQLSMALLINT NameLength3,
SQLCHAR * ColumnName,
SQLSMALLINT NameLength4);
引數
StatementHandle
[輸入]語句控制碼。
CatalogName
[輸入]目錄名稱。 如果驅動程式支援某些目錄的名稱，但不支援其他目錄，例如當驅動程式從不同的 DBMS 擷取資料時，空字串 （「」） 表示沒有名稱的目錄。 CatalogName 不能包含字串搜尋模式。
如果 SQL_ATTR_METADATA_ID 語句屬性設定為 SQL_TRUE， 則 CatalogName 會被視為識別碼，而且其大小寫並不重要。 如果它是SQL_FALSE， CatalogName 是一般引數;它會以常值方式處理，而且其大小寫很重要。 如需詳細資訊，請參閱目錄函式中的引數。
NameLength1
[輸入]*CatalogName 的 字元長度。
SchemaName
[輸入]架構名稱。 如果驅動程式支援某些資料表的架構，但不支援其他資料表，例如當驅動程式從不同的 DBMS 擷取資料時，空字串 （「」） 表示沒有架構的資料表。 SchemaName 不能包含字串搜尋模式。
如果 SQL_ATTR_METADATA_ID 語句屬性設定為 SQL_TRUE， 則 SchemaName 會被視為識別碼。 如果它是SQL_FALSE， SchemaName 是一般引數;它會以常值方式處理，而且其大小寫很重要。
NameLength2
[輸入]*SchemaName 的 字元長度。
TableName
[輸入]資料表名稱。 這個引數不可以是 Null 指標。 TableName 不能包含字串搜尋模式。
如果SQL_ATTR_METADATA_ID語句屬性設定為 SQL_TRUE，則 TableName 會被視為識別碼， 而且其大小寫並不重要。 如果它是SQL_FALSE， TableName 是一般引數;它會以常值方式處理，而且其大小寫很重要。
NameLength3
[輸入]*TableName 的字元長度 。
ColumnName
[輸入]資料行名稱的字串搜尋模式。
如果SQL_ATTR_METADATA_ID語句屬性設定為 SQL_TRUE，ColumnName 會被視為識別碼， 而且其大小寫並不重要。 如果它是SQL_FALSE， ColumnName 是模式值引數;它會以常值方式處理，而且其大小寫很重要。
NameLength4
[輸入]*ColumnName 的 字元長度。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
當 SQLColumnPrivileges 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，透過呼叫 具有 SQL_HANDLE_STMT HandleType 和 StatementHandle Handle 的 HandleType 呼叫 SQLGetDiagRec ，即可取得相關聯的 SQLSTATE 值。 下表列出 SQLColumnPrivileges 通常傳 回的 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 指標使用 | TableName 引數是 Null 指標。 SQL_ATTR_METADATA_ID語句屬性已設定為 SQL_TRUE、 CatalogName 引數為 null 指標，而且 infoType SQL_CATALOG_NAME 會傳回支援目錄名稱。 （DM） SQL_ATTR_METADATA_ID語句屬性已設定為 SQL_TRUE， 而 SchemaName 或 ColumnName 引數為 null 指標。 |
| HY010 | 函式順序錯誤 | （DM） 已針對與 StatementHandle 相關聯的連接控制碼呼叫非同步執行函式。 呼叫此函式時，這個非同步函式仍在執行中。 （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_CONCURRENCY和SQL_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 ，才能執行後續處理並完成作業。 |
註解
SQLColumnPrivileges 會以標準結果集的形式傳回結果，依TABLE_CAT、TABLE_SCHEM、TABLE_NAME、COLUMN_NAME和 PRIVILEGE 排序。
注意
SQLColumnPrivileges 可能不會傳回所有資料行的許可權。 例如，驅動程式可能不會傳回虛擬資料行許可權的相關資訊，例如 Oracle ROWID。 無論 SQLColumnPrivileges 是否傳 回任何有效的資料行，應用程式都可以使用任何有效的資料行。
資料表中不會顯示 VARCHAR 資料行的長度;實際長度取決於資料來源。 若要判斷CATALOG_NAME、SCHEMA_NAME、TABLE_NAME和COLUMN_NAME資料行的實際長度，應用程式可以使用SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN、SQL_MAX_TABLE_NAME_LEN和SQL_MAX_COLUMN_NAME_LEN選項呼叫 SQLGetInfo 。
注意
如需 ODBC 類別目錄函式的一般使用、引數和傳回資料的詳細資訊，請參閱 目錄函式 。
下列資料行已針對 ODBC 3 重新命名。 x . 資料行名稱變更不會影響回溯相容性，因為應用程式會依資料行編號系結。
| ODBC 2.0 資料行 | ODBC 3. x 欄 |
|---|---|
| TABLE_QUALIFIER | TABLE_CAT |
| TABLE_OWNER | TABLE_SCHEM |
下表列出結果集中的資料行。 驅動程式可以定義資料行 8 以外的其他資料行（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 | 資料表識別碼。 |
| COLUMN_NAME （ODBC 1.0） | 4 | Varchar not Null | 資料行名稱。 驅動程式會針對沒有名稱的資料行傳回空字串。 |
| GRANTOR （ODBC 1.0） | 5 | Varchar | 授與許可權的使用者名稱;如果不適用於資料來源，則為 Null。 對於 GRANTEE 資料行中值為物件擁有者的所有資料列，GRANTOR 資料行將會是 「_SYSTEM」。 |
| GRANTEE （ODBC 1.0） | 6 | Varchar not Null | 授與許可權的使用者名稱。 |
| PRIVILEGE （ODBC 1.0） | 7 | Varchar not Null | 識別資料行許可權。 可能是下列其中一項（或定義實作時資料來源所支援的其他專案）： SELECT：被授與者可以擷取資料行的資料。 INSERT：被授與者可以針對插入關聯資料表之新資料列中的資料行提供資料。 UPDATE：被授與者可以更新資料行中的資料。 REFERENCES：被授與者可以參考條件約束內的資料行（例如，唯一、引用或資料表檢查條件約束）。 |
| IS_GRANTABLE （ODBC 1.0） | 8 | Varchar | 指出被授與者是否允許將許可權授與其他使用者;如果資料來源未知或不適用，則為 「YES」、「NO」 或 「Null」。 許可權可授與或不可授與，但不可同時授與。 SQLColumnPrivileges 傳 回的結果集永遠不會包含兩個數據列，除了IS_GRANTABLE資料行包含相同的值之外，所有資料行都不包含這些資料列。 |
程式碼範例
如需類似函式的程式碼範例，請參閱 SQLColumns 函式 。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 將緩衝區系結至結果集中的資料行 | SQLBindCol 函式 |
| 取消語句處理 | SQLCancel 函式 |
| 傳回資料表或資料表中的資料行 | SQLColumns 函式 |
| 擷取資料區塊或捲動結果集 | SQLFetchScroll 函式 |
| 擷取多個資料列 | SQLFetch 函式 |
| 傳回資料表或資料表的許可權 | SQLTablePrivileges 函式 |
| 傳回資料來源中的資料表清單 | SQLTables 函數 |