SQLGetEnvAttr 函式
一致性
引進版本:ODBC 3.0 標準合規性:ISO 92
摘要
SQLGetEnvAttr 會傳回環境屬性的目前設定。
語法
SQLRETURN SQLGetEnvAttr(
SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
引數
EnvironmentHandle
[輸入]環境控制碼。
屬性
[輸入]要擷取的屬性。
ValuePtr
[輸出]緩衝區的指標,其中要傳回 Attribute 所 指定之屬性的目前值。
如果 ValuePtr 為 Null, StringLengthPtr 仍會傳回可供 ValuePtr 指向 的緩衝區中傳回的位元組總數(不包括字元資料的 Null 終止字元)。
BufferLength
[輸入]如果 ValuePtr 指向字元字串,這個引數應該是 * ValuePtr 的長度。 如果 * ValuePtr 是整數, 則會忽略 BufferLength 。 如果 *ValuePtr 是 Unicode 字串(呼叫 SQLGetEnvAttrW 時), BufferLength 引數必須是偶數。 如果屬性值不是字元字串, 則 BufferLength 未使用。
StringLengthPtr
[輸出]緩衝區的指標,用來傳回 *ValuePtr 中 傳回的位元組總數(不包括 Null 終止字元)。 如果屬性值是字元字串,而且可傳回的位元組數目大於或等於 BufferLength,則 * ValuePtr 中的資料會截斷為 BufferLength 減去 Null 終止字元的長度,而且由驅動程式以 Null 終止。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
當 SQLGetEnvAttr 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時 ,可以藉由呼叫 SQLGetDiagRec 搭配 SQL_HANDLE_ENV HandleType 和 EnvironmentHandle 的 HandleHandle 來取得相關聯的 SQLSTATE 值。 下表列出 SQLGetEnvAttr 通常傳 回的 SQLSTATE 值,並說明此函式內容中的每個值;標記法 「(DM)」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明,否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
SQLSTATE | 錯誤 | 描述 |
---|---|---|
01000 | 一般警告 | 驅動程式特定的資訊訊息。 (函式會傳回SQL_SUCCESS_WITH_INFO。) |
01004 | 字串資料,右截斷 | * ValuePtr 中傳回的資料已截斷為 BufferLength 減去 Null 終止字元。 未建構字串值的長度會在 * StringLengthPtr 中 傳回。 (函式會傳回SQL_SUCCESS_WITH_INFO。) |
HY000 | 一般錯誤 | 發生錯誤,其中沒有特定的 SQLSTATE,也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳 回的錯誤訊息描述錯誤及其原因。 |
HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
HY010 | 函式順序錯誤 | (DM) SQL_ATTR_ODBC_VERSION 尚未透過 SQLSetEnvAttr 設定。 如果您使用 SQLAllocHandleStd ,就不需要明確設定 SQL_ATTR_ODBC_VERSION 。 |
HY013 | 記憶體管理錯誤 | 無法處理函式呼叫,因為基礎記憶體物件無法存取,可能是因為記憶體不足的情況。 |
HY092 | 不正確屬性/選項識別碼 | 針對引數 Attribute 指定的值對驅動程式支援的 ODBC 版本無效。 |
HY117 | 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | (DM) 如需暫停狀態的詳細資訊,請參閱 SQLEndTran 函式 。 |
HYC00 | 未實作選擇性功能 | 為引數 Attribute 指定的值是驅動程式所支援之 ODBC 版本的有效 ODBC 環境屬性,但驅動程式不支援。 |
IM001 | 驅動程式不支援此函式 | (DM) 對應至 EnvironmentHandle 的 驅動程式不支援 函式。 |
註解
如需屬性清單,請參閱 SQLSetEnvAttr 。 沒有驅動程式特定的環境屬性。 如果 Attribute 指定傳回字串的屬性, ValuePtr 必須是要在其中傳回字串之緩衝區的指標。 字串的最大長度,包括 Null 終止位元組,將是 BufferLength 位元組。
您可以隨時在配置與釋放環境控制碼之間呼叫 SQLGetEnvAttr 。 應用程式成功設定環境的所有環境屬性都會保存,直到 使用 handleType SQL_HANDLE_ENV 在 EnvironmentHandle 上 呼叫 SQLFreeHandle 為止。 您可以在 ODBC 3*.x* 中同時配置多個環境控制碼。 配置另一個環境時,某個環境上的環境屬性不會受到影響。
注意
符合標準的應用程式支援SQL_ATTR_OUTPUT_NTS環境屬性。 呼叫 SQLGetEnvAttr 時 ,ODBC 3*.x* 驅動程式管理員一律會傳回此屬性的SQL_TRUE。 SQL_ATTR_OUTPUT_NTS只能透過對 SQLSetEnvAttr 的 呼叫來設定為 SQL_TRUE。
相關函數
如需下列資訊 | 請參閱 |
---|---|
傳回連接屬性的設定 | SQLGetConnectAttr 函式 |
傳回語句屬性的設定 | SQLGetStmtAttr 函式 |
設定連接屬性 | SQLSetConnectAttr 函式 |
設定環境屬性 | SQLSetEnvAttr 函式 |
設定語句屬性 | SQLSetStmtAttr 函式 |