符合性
推出版本：ODBC 3.0 標準合規：ISO 92
總結
SQLSetEnvAttr 設定了控制環境面向的屬性。
Syntax
SQLRETURN SQLSetEnvAttr(
SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
論點
環境控制
[輸入]環境控制。
Attribute
[輸入]歸屬於「留言」中。
ValuePtr
[輸入]指向要與 屬性相關聯的值。 根據 屬性值， ValuePtr 會是 32 位元整數值，或指向一個空終止字串。
StringLength
[輸入]如果 ValuePtr 指向字串或二進位緩衝區，這個參數應該是 *ValuePtr 的長度。 對於字串資料，這個參數應該包含字串中的位元組數。
若 ValuePtr 為整數，則忽略 字串長度 。
Returns
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。
Diagnostics
當 SQLSetEnvAttr 回傳 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 時，可透過呼叫 SQLGetDiagRec 取得對應的 SQLSTATE 值，HandleType 為 SQL_HANDLE_ENV，Handle 為 environmentHandle 。 下表列出 SQLSetEnvAttr 通常回傳的 SQLSTATE 值，並在此函式的情境中解釋每個值;「（DM）」符號會置於驅動程式管理器回傳的 SQLSTATE 描述前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。 若驅動程式不支援環境屬性，錯誤只能在連線時回傳。
| SQLSTATE | 錯誤 | Description |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01S02 | 選項值已變更 | 驅動程式不支援 ValuePtr 中指定的值，並替換成了相似的值。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| HY000 | 一般誤差 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY009 | 無效的 Null 指標使用 | Attribute 參數識別需要字串值的環境屬性，而 ValuePtr 參數則是空指標。 |
| HY010 | 函式順序錯誤 | （DM） EnvironmentHandle 上已分配一個連接句柄。 （DM） SQL_ATTR_ODBC_VERSION 並未用 SQLSetEnvAttr 設定 ，屬性不 等於 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） 屬性 論證是SQL_ATTR_OUTPUT_NTS的，而 價值Ptr 則SQL_FALSE。 |
評論
應用程式只有在環境中未分配連線句柄時，才能呼叫 SQLSetEnvAttr 。 應用程式成功設定的所有環境屬性會持續存在，直到環境呼叫 SQLFreeHandle 為止。 在 ODBC 3.x 中，可以同時分配多個環境句柄。
透過 ValuePtr 所設定的資訊格式取決於指定的 屬性。 SQLSetEnvAttr 可接受兩種不同格式之一的屬性資訊：空終端字串或 32 位元整數值。 屬性的描述中會指出每個 格式。
沒有驅動程式專屬的環境屬性。
連線屬性無法透過呼叫 SQLSetEnvattr 來設定。 嘗試這樣做會回傳 SQLSTATE HY092（無效屬性/選項識別碼）。
| Attribute | 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無法重置該環境，因為設定此屬性時會以空環境代碼呼叫 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 代碼。 - 呼叫 SQLTables 時的 CatalogName 參數可接受搜尋模式。 - 驅動程式管理器支援 C 語言資料型別擴充性。 欲了解更多關於 C 資料型態擴充性的資訊，請參閱 ODBC 中的 C 資料型態。 欲了解更多資訊，請參閱 ODBC 3.8 的新內容。 SQL_OV_ODBC3 = 驅動程式管理器與驅動程式展現以下 ODBC 3.x 行為： - 驅動程式返回並期望收到 ODBC 3.x 的日期、時間及時間戳碼。 - 當呼叫 SQLError、SQLGetDiagField 或 SQLGetDiagRec 時，驅動程式會回傳 ODBC 3.x 的 SQLSTATE 代碼。 - 呼叫 SQLTables 時的 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，驅動程式回傳字串資料為空終端。 若SQL_FALSE，驅動程式不會回傳空終端字串資料。 此屬性預設為SQL_TRUE。 呼叫 SQLSetEnvAttr 設定為 SQL_TRUE 會回傳 SQL_SUCCESS。 呼叫 SQLSetEnvAttr 設定為 SQL_FALSE 會回傳 SQL_ERROR 和 SQLSTATE HYC00（未實作的可選功能）。 |
相關函數
| 如需相關信息 | 看！ |
|---|---|
| 分配帳柄 | SQLAllocHandle 函式 |
| 回傳環境屬性的設定 | SQLGetEnvAttr Function |