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 標頭檔