SQLSetEnvAttr 函式

  • 發行項

一致性
引進版本：ODBC 3.0 標準合規性：ISO 92

摘要
SQLSetEnvAttr 會設定管理環境層面的屬性。

語法

  
SQLRETURN SQLSetEnvAttr(  
     SQLHENV      EnvironmentHandle,  
     SQLINTEGER   Attribute,  
     SQLPOINTER   ValuePtr,  
     SQLINTEGER   StringLength);

引數

EnvironmentHandle
[輸入]環境控制碼。

屬性
[輸入]要設定的屬性，列在「批註」中。

ValuePtr
[輸入]要與 Attribute 相關聯 之值的指標。 根據 Attribute 的值 ，ValuePtr 會是 32 位整數值， 或指向以 Null 結尾的字元字串。

StringLength
[輸入]如果 ValuePtr 指向字元字串或二進位緩衝區，則此引數應該是 * ValuePtr 的長度。 對於字元字串資料，這個引數應該包含字串中的位元組數目。

如果 ValuePtr 是整數， 則會忽略 StringLength 。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

診斷

當 SQLSetEnvAttr 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可以使用SQL_HANDLE_ENV的 HandleType 和 EnvironmentHandle 的 HandleType 呼叫 SQLGetDiagRec 來取得相關聯的 SQLSTATE 值。 下表列出 SQLSetEnvAttr 通常傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法 「（DM）」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。 如果驅動程式不支援環境屬性，則只能在連接期間傳回錯誤。

SQLSTATE 錯誤 描述
01000 一般警告 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
01S02 選項值已變更 驅動程式不支援 ValuePtr 中指定的 值，並取代了類似的值。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
HY000 一般錯誤 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳 回的錯誤訊息描述錯誤及其原因。
HY001 記憶體配置錯誤 驅動程式無法配置支援執行或完成函式所需的記憶體。
HY009 不正確 Null 指標使用 Attribute 引數識別出需要字串值的環境屬性，而 ValuePtr 引數是 Null 指標。
HY010 函式順序錯誤 （DM） 已在 EnvironmentHandle 上 配置連接控制碼 。

（DM） SQL_ATTR_ODBC_VERSION 尚未使用 SQLSetEnvAttr 設定 ，而且 Attribute 不等於 SQL_ATTR_ODBC_VERSION 。 如果您使用 SQLAllocHandleStd ，就不需要明確設定 SQL_ATTR_ODBC_VERSION 。
HY013 記憶體管理錯誤 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。
HY024 不正確屬性值 指定了指定的 屬性值 ，ValuePtr 中 指定了不正確值。
HY090 不正確字串或緩衝區長度 StringLength 引數小於 0，但未SQL_NTS。
HY092 不正確屬性/選項識別碼 （DM） 為引數 Attribute 指定的值對驅動程式支援的 ODBC 版本無效。
HY117 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式 。
HYC00 未實作選擇性功能 為引數 Attribute 指定的值是驅動程式所支援之 ODBC 版本的有效 ODBC 環境屬性，但驅動程式不支援。

（DM） Attribute 引數SQL_ATTR_OUTPUT_NTS，而 ValuePtr 則SQL_FALSE。

註解

只有在環境中未配置任何連接控制碼時，應用程式才能呼叫 SQLSetEnvAttr 。 應用程式成功設定環境的所有環境屬性都會持續存在，直到 環境上呼叫 SQLFreeHandle 為止。 您可以在 ODBC 3.x 中同時配置多個環境控制碼。

透過 ValuePtr 設定的資訊格式取決於指定的 屬性 。 SQLSetEnvAttr 會接受兩種不同格式之一的屬性資訊：以 Null 結束的字元字串或 32 位整數值。 屬性的描述中會指出每個 格式。

沒有驅動程式特定的環境屬性。

呼叫 SQLSetEnvAttr 無法設定 連線屬性。 嘗試這樣做會傳回 SQLSTATE HY092 （不正確屬性/選項識別碼）。

屬性 ValuePtr 內容
SQL_ATTR_CONNECTION_POOLING （ODBC 3.8） 32 位 SQLUINTEGER 值，可在環境層級啟用或停用連線共用。 使用下列值：

SQL_CP_OFF = 已關閉連線共用。 這是預設值。

SQL_CP_ONE_PER_DRIVER = 每個驅動程式都支援單一連線集區。 集區中的每個連線都會與一個驅動程式相關聯。

SQL_CP_ONE_PER_HENV = 每個環境都支援單一連線集區。 集區中的每個連線都會與一個環境相關聯。

SQL_CP_DRIVER_AWARE = 如果有的話，請使用驅動程式的連接集區感知功能。 如果驅動程式不支援連線集區感知，則會忽略SQL_CP_DRIVER_AWARE，並使用SQL_CP_ONE_PER_HENV。 如需詳細資訊，請參閱驅動程式感知連接共用。 在某些驅動程式支援和某些驅動程式不支援連線集區感知的環境中，SQL_CP_DRIVER_AWARE可以在支援驅動程式的驅動程式上啟用連線集區感知功能，但相當於在不支援連線集區感知功能的驅動程式上設定為SQL_CP_ONE_PER_HENV。

連線共用是藉由呼叫 SQLSetEnvAttr 來將 SQL_ATTR_CONNECTION_POOLING 屬性設定為 SQL_CP_ONE_PER_DRIVER 或 SQL_CP_ONE_PER_HENV 來啟用。 應用程式必須先執行這項呼叫，再配置啟用連線共用的共用環境。 呼叫 SQLSetEnvAttr 的環境控制碼會設定為 null，這會使SQL_ATTR_CONNECTION_POOLING進程層級屬性。 啟用連線共用之後，應用程式接著會呼叫 SQLAllocHandle 並將 InputHandle 引數設定為 SQL_HANDLE_ENV，以配置隱含共用環境。

啟用連線共用且已為應用程式選取共用環境之後，就無法針對該環境重設SQL_ATTR_CONNECTION_POOLING，因為 設定此屬性時會使用 Null 環境控制碼呼叫 SQLSetEnvAttr 。 如果在共用環境上已啟用連線共用時設定這個屬性，則此屬性只會影響後續配置的共用環境。

您也可以在環境中啟用連線共用。 請注意下列環境連線共用的相關資訊：

- 在 Null 控制碼上啟用連線共用是進程層級屬性。 後續配置的環境將會是共用環境，並將繼承進程層級連線共用設定。
- 配置環境之後，應用程式仍然可以變更其連線集區設定。
- 如果已啟用環境連線共用，且連線的驅動程式使用驅動程式共用，則環境共用會採用喜好設定。

SQL_ATTR_CONNECTION_POOLING會在驅動程式管理員內實作。 驅動程式不需要實作SQL_ATTR_CONNECTION_POOLING。 ODBC 2.0 和 3.0 應用程式可以設定這個環境屬性。

如需詳細資訊，請參閱 ODBC 連接共用。
SQL_ATTR_CP_MATCH （ODBC 3.0） 32 位 SQLUINTEGER 值，決定如何從連接集區選擇連線。 呼叫 SQLConnect 或 SQLDriverConnect 時 ，驅動程式管理員會決定從集區重複使用哪一個連線。 驅動程式管理員會嘗試比對呼叫中的連接選項，以及應用程式所設定的連接屬性與集區中連線的關鍵字和連接屬性。 這個屬性的值會決定比對準則的有效位數層級。

下列值可用來設定此屬性的值：

SQL_CP_STRICT_MATCH = 只會重複使用完全符合呼叫中的連接選項，以及應用程式所設定的連接屬性。 這是預設值。

SQL_CP_RELAXED_MATCH = 可以使用具有相符連接字串關鍵字的連線。 關鍵字必須相符，但並非所有連接屬性都必須相符。

如需驅動程式管理員在連線到集區連線時如何執行比對的詳細資訊，請參閱 SQLConnect 。 如需連線共用的詳細資訊，請參閱 ODBC 連線共用。
SQL_ATTR_ODBC_VERSION （ODBC 3.0） 32 位整數，決定某些功能是否表現出 ODBC 2.x 行為或 ODBC 3.x 行為。 下列值可用來設定此屬性的值：

SQL_OV_ODBC3_80 = 驅動程式管理員和驅動程式會展示下列 ODBC 3.8 行為：

- 驅動程式會傳回並預期 ODBC 3.x 代碼的日期、時間和時間戳記。
- 呼叫 SQLError 、 SQLGetDiagField 或 SQLGetDiagRec 時 ，驅動程式會傳回 ODBC 3.x SQLSTATE 程式碼。
- 呼叫 SQLTable 中的 CatalogName 引數會接受搜尋模式。
- 驅動程式管理員支援 C 資料類型擴充性。 如需 C 資料類型擴充性的詳細資訊，請參閱 ODBC 中的 C 資料類型。

如需詳細資訊，請參閱 ODBC 3.8 的新功能。

SQL_OV_ODBC3 = 驅動程式管理員和驅動程式會展示下列 ODBC 3.x 行為：

- 驅動程式會傳回並預期 ODBC 3.x 代碼的日期、時間和時間戳記。
- 呼叫 SQLError 、 SQLGetDiagField 或 SQLGetDiagRec 時 ，驅動程式會傳回 ODBC 3.x SQLSTATE 程式碼。
- 呼叫 SQLTable 中的 CatalogName 引數會接受搜尋模式。
- 驅動程式管理員不支援 C 資料類型擴充性。

SQL_OV_ODBC2 = 驅動程式管理員和驅動程式會展示下列 ODBC 2.x 行為。 這特別適用于使用 ODBC 3.x 驅動程式的 ODBC 2.x 應用程式。

- 驅動程式會傳回並預期 ODBC 2.x 代碼的日期、時間和時間戳記。
- 呼叫 SQLError 、 SQLGetDiagField 或 SQLGetDiagRec 時 ，驅動程式會傳回 ODBC 2.x SQLSTATE 代碼。
- 呼叫 SQLTables 中的 CatalogName 引數不接受搜尋模式。
- 驅動程式管理員不支援 C 資料類型擴充性。

應用程式必須先設定此環境屬性，才能呼叫任何具有 SQLHENV 引數的函式，否則呼叫會傳回 SQLSTATE HY010 （函數順序錯誤）。 這是驅動程式特定的，這些環境旗標是否有其他行為存在。

- 如需詳細資訊，請參閱 宣告應用程式的 ODBC 版本 和 行為變更 。
SQL_ATTR_OUTPUT_NTS （ODBC 3.0） 32 位整數，決定驅動程式如何傳回字串資料。 如果SQL_TRUE，驅動程式會傳回字串資料 null 終止。 如果SQL_FALSE，驅動程式不會傳回字串資料 null 終止。

此屬性預設為 SQL_TRUE。 呼叫 SQLSetEnvAttr 以將它設定為SQL_TRUE會傳回SQL_SUCCESS。 呼叫 SQLSetEnvAttr 以將它設定為SQL_FALSE會傳回SQL_ERROR和 SQLSTATE HYC00（未實作選擇性功能）。
如需下列資訊 請參閱
配置控制碼 SQLAllocHandle 函式
傳回環境屬性的設定 SQLGetEnvAttr 函式

另請參閱

ODBC API 參考
ODBC 標頭檔
ODBC 3.8 的新功能