分享方式:


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 函式

另請參閱

ODBC API 參考
ODBC 標頭檔