SQLAllocHandle 函式
一致性
引進版本：ODBC 3.0 標準合規性：ISO 92
摘要
SQLAllocHandle 會配置環境、連接、語句或描述項控制碼。
注意
此函式是配置控制碼的泛型函式，可取代 ODBC 2.0 函 式 SQLAllocConnect 、 SQLAllocEnv 和 SQLAllocStmt 。 允許呼叫 SQLAllocHandle 的應用程式使用 ODBC 2。 x 驅動程式，SQLAllocHandle 的 呼叫會在驅動程式管理員中對應至 SQLAllocConnect 、 SQLAllocEnv 或 SQLAllocStmt 。 如需詳細資訊，請參閱。如需 Driver Manager 在 ODBC 3 時將此函式對應至之內容的詳細資訊。 x 應用程式正在使用 ODBC 2。 x 驅動程式，請參閱 對應替代函式以取得應用程式的 回溯相容性。
語法
SQLRETURN SQLAllocHandle(
SQLSMALLINT HandleType,
SQLHANDLE InputHandle,
SQLHANDLE * OutputHandlePtr);
引數
HandleType
[輸入]要由 SQLAllocHandle 配置的 控制碼類型。 必須是下列其中一個值：
SQL_HANDLE_DBC
SQL_HANDLE_DBC_INFO_TOKEN
SQL_HANDLE_DESC
SQL_HANDLE_ENV
SQL_HANDLE_STMT
SQL_HANDLE_DBC_INFO_TOKEN控制碼只能由驅動程式管理員和驅動程式使用。 應用程式不應該使用此控制碼類型。 如需SQL_HANDLE_DBC_INFO_TOKEN的詳細資訊，請參閱 在 ODBC 驅動程式 中開發連線集區感知。
InputHandle
[輸入]要配置新控制碼內容的輸入控制碼。 如果 HandleType 是SQL_HANDLE_ENV，則會SQL_Null_HANDLE。 如果 HandleType 是SQL_HANDLE_DBC，這必須是環境控制碼，如果它是SQL_HANDLE_STMT或SQL_HANDLE_DESC，它必須是連接控制碼。
OutputHandlePtr
[輸出]要在其中將控制碼傳回至新配置之資料結構的緩衝區指標。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_INVALID_HANDLE或SQL_ERROR。
配置環境控制碼以外的控制碼時，如果 SQLAllocHandle 傳回SQL_ERROR，則會根據 HandleType 的值 ，將 OutputHandlePtr 設定 為SQL_Null_HDBC、SQL_Null_HSTMT或SQL_Null_HDESC，除非輸出引數為 null 指標。 然後，應用程式可以從 InputHandle 引數中 與控制碼相關聯的診斷資料結構取得其他資訊。
環境處理配置錯誤
環境配置同時發生在驅動程式管理員和每個驅動程式內。 SQLAllocHandle SQL_HANDLE_ENV HandleType 所 傳回的錯誤取決於發生錯誤的層級。
如果呼叫具有 SQL_HANDLE_ENV HandleType 的 SQLAllocHandle 時 ，驅動程式管理員無法配置 *OutputHandlePtr 的記憶體，或應用程式會提供 OutputHandlePtr 的 Null 指標， SQLAllocHandle 會傳回SQL_ERROR。 驅動程式管理員會將 * OutputHandlePtr 設定為SQL_Null_HENV（除非應用程式提供傳回SQL_ERROR的 Null 指標）。 沒有任何控制碼可讓其他診斷資訊產生關聯。
在應用程式呼叫 SQLConnect、 SQLBrowseConnect 或 SQLDriverConnect 之前，驅動程式管理員不會呼叫 驅動程式層級環境控制碼配置函式。 如果驅動程式層級 SQLAllocHandle 函式中發生錯誤，則 Driver Manager 層級 的 SQLConnect、 SQLBrowseConnect 或 SQLDriverConnect 函式會傳回SQL_ERROR。 診斷資料結構包含 SQLSTATE IM004（驅動程式的 SQLAllocHandle 失敗）。 錯誤會在連接控制碼上傳回。
如需驅動程式管理員與驅動程式之間函式呼叫流程的詳細資訊，請參閱 SQLConnect 函式 。
診斷
當 SQLAllocHandle 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，藉由呼叫 SQLGetDiagRec 並將適當的 HandleType 和 Handle 設定為 InputHandle 的值，即可取得相關聯的 SQLSTATE 值 。 outputHandle 引數可以傳 回SQL_SUCCESS_WITH_INFO （但無法SQL_ERROR）。 下表列出 SQLAllocHandle 通常傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法 「（DM）」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 08003 | 連線未開啟 | （DM） HandleType 引數已SQL_HANDLE_STMT或SQL_HANDLE_DESC，但 InputHandle 引數指定的 連接尚未開啟。 連接進程必須順利完成（且必須開啟連接），驅動程式才能配置語句或描述元控制碼。 |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 * MessageText 緩衝區中 SQLGetDiagRec 傳 回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | （DM） 驅動程式管理員無法為指定的控制碼配置記憶體。 驅動程式無法為指定的控制碼配置記憶體。 |
| HY009 | 不正確 Null 指標使用 | （DM） OutputHandlePtr 引數是 Null 指標。 |
| HY010 | 函式順序錯誤 | （DM） HandleType 引數已SQL_HANDLE_DBC，而且 尚未呼叫 SQLSetEnvAttr 來設定SQL_ODBC_VERSION環境屬性。 （DM） 呼叫 InputHandle 的非同步執行函 式，而且在呼叫 SQLAllocHandle 函式時 仍執行，而 HandleType 設定為 SQL_HANDLE_STMT 或 SQL_HANDLE_DESC。 |
| HY013 | 記憶體管理錯誤 | HandleType 引數是SQL_HANDLE_DBC、SQL_HANDLE_STMT或SQL_HANDLE_DESC，而且無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體狀況低。 |
| HY014 | 超過控制碼數目的限制 | 已達到 HandleType 引數所指示 之控制碼類型可配置之控制碼數目的驅動程式定義限制。 |
| HY092 | 不正確屬性/選項識別碼 | （DM） HandleType 引數不是：SQL_HANDLE_ENV、SQL_HANDLE_DBC、SQL_HANDLE_STMT或SQL_HANDLE_DESC。 |
| HY117 | 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式 。 |
| HYC00 | 未實作選擇性功能 | HandleType 引數SQL_HANDLE_DESC，而驅動程式是 ODBC 2。 x 驅動程式。 |
| HYT01 | 已超過連線逾時 | 在資料來源回應要求之前，連線逾時期限已過期。 連線逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） HandleType 引數已SQL_HANDLE_STMT，而且驅動程式不是有效的 ODBC 驅動程式。 （DM） HandleType 引數SQL_HANDLE_DESC，且驅動程式不支援配置描述元控制碼。 |
註解
SQLAllocHandle 可用來配置環境、連接、語句和描述項的控制碼，如下列各節所述。 如需控制碼的一般資訊，請參閱 控制碼 。
如果驅動程式支援多個配置，應用程式可以一次配置多個環境、連線或語句控制碼。 在 ODBC 中，不會定義任何一次可配置的環境、連接、語句或描述項控制碼數目限制。 驅動程式可能會限制一次可配置的特定控制碼類型數目;如需詳細資訊，請參閱驅動程式檔。
如果應用程式呼叫 SQLAllocHandle 並將 *OutputHandlePtr 設定為已存在的環境、連接、語句或描述元控制碼，驅動程式會覆寫與 控制碼 相關聯的資訊，除非應用程式正在使用連線共用（請參閱本節稍後的）。 驅動程式管理員不會檢查 是否已使用在 *OutputHandlePtr 中 輸入的控制碼，也不會在覆寫控制碼 之前檢查先前的內容。
注意
ODBC 應用程式程式設計不正確，使用針對 *OutputHandlePtr 定義的 相同應用程式變數來呼叫 SQLAllocHandle 兩次，而不需呼叫 SQLFreeHandle 來釋放控制碼，然後再重新配置它。 以這種方式覆寫 ODBC 控制碼可能會導致 ODBC 驅動程式的行為或錯誤不一致。
在支援多個執行緒的作業系統上，應用程式可以在不同的執行緒上使用相同的環境、連接、語句或描述項控制碼。 因此，驅動程式必須支援安全、多執行緒存取這項資訊;例如，達成此目的的其中一種方法是使用重要區段或號志。 如需執行緒的詳細資訊，請參閱 多執行緒 。
當呼叫 SQLAllocHandle 以配置環境控制碼時，SQLAllocHandle 不會設定SQL_ATTR_ODBC_VERSION環境屬性;環境屬性必須由應用程式設定，否則會在呼叫 SQLAllocHandle 以配置連接控制碼時 傳回 SQLSTATE HY010 （函數順序錯誤）。
針對符合標準的應用程式， SQLAllocHandle 會在編譯時期對應至 SQLAllocHandleStd 。 這兩個函式之間的差異在於 SQLAllocHandleStd 會在呼叫時將 SQL_ATTR_ODBC_VERSION 環境屬性設定為 SQL_OV_ODBC3，並將 HandleType 引數設定為 SQL_HANDLE_ENV。 這是因為標準相容的應用程式一律是 ODBC 3。 x 應用程式。 此外，標準不需要註冊應用程式版本。 這是這兩個函式的唯一差異：否則，它們完全相同。 SQLAllocHandleStd 會對應至 驅動程式管理員內的 SQLAllocHandle 。 因此，協力廠商驅動程式不需要實 作 SQLAllocHandleStd 。
ODBC 3.8 應用程式應該使用：
SQLAllocHandle 而非 SQLAllocHandleStd 來配置環境控制碼。
SQLSetEnvAttr 將SQL_ATTR_ODBC_VERSION環境屬性設定為 SQL_OV_ODBC3_80。
配置環境控制代碼
環境控制碼可讓您存取全域資訊，例如有效的連接控制碼和作用中的連接控制碼。 如需環境控制碼的一般資訊，請參閱 環境控制碼 。
若要要求環境控制碼，應用程式會呼叫 SQLAllocHandle ，其 HandleType 為 SQL_HANDLE_ENV，以及 SQL_Null_HANDLE 的 InputHandle 。 驅動程式會配置記憶體給環境資訊，並將相關聯控制碼的值傳回 *OutputHandlePtr 引數中。 應用程式會在需要環境控制碼引數的所有後續呼叫中傳遞 *OutputHandle 值。 如需詳細資訊，請參閱配置環境控制代碼 (機器翻譯)。
在驅動程式管理員的環境控制碼下，如果驅動程式的環境控制碼已經存在，則在 建立連接時，不會在該驅動程式中呼叫具有 handleType SQL_HANDLE_ENV 的 SQLAllocHandle ，只有 具有 handleType 為 SQL_HANDLE_DBC 的 SQLAllocHandle 。 如果驅動程式的環境控制碼不存在於驅動程式管理員的環境控制碼下，則當環境的第一個連接控制碼連接到驅動程式時，驅動程式中會呼叫 sqlAllocHandle 與 Handle SQL_HANDLE_DBC Type 為 SQL_HANDLE_ENV 的 HandleType 和 SQLAllocHandle。
當 Driver Manager 使用 SQL_HANDLE_ENV HandleType 處理 SQLAllocHandle 函式時，它會檢查 系統資訊 [ODBC] 區段中的 Trace 關鍵字。 如果設定為 1，驅動程式管理員會啟用目前應用程式的追蹤。 如果設定追蹤旗標，追蹤會在配置第一個環境控制碼時開始，並在釋放最後一個環境控制碼時結束。 如需詳細資訊，請參閱 設定資料來源 。
配置環境控制碼之後，應用程式必須在環境控制碼上呼叫 SQLSetEnvAttr ，才能設定SQL_ATTR_ODBC_VERSION環境屬性。 如果在呼叫 SQLAllocHandle 以配置環境上的連接控制碼之前 未設定此屬性，則配置連接的呼叫會傳回 SQLSTATE HY010 （函數順序錯誤）。 如需詳細資訊，請參閱 宣告應用程式的 ODBC 版本 。
配置共用共用環境的連線共用
環境可以在單一進程上的多個元件之間共用。 共用環境可以同時由多個元件使用。 當元件使用共用環境時，它可以使用集區連線，以允許它配置和使用現有的連接，而不需重新建立該連線。
在配置可用於連線共用的共用環境之前，應用程式必須呼叫 SQLSetEnvAttr ，將SQL_ATTR_CONNECTION_POOLING環境屬性設定為SQL_CP_ONE_PER_DRIVER或SQL_CP_ONE_PER_HENV。 在此案例中，會呼叫 SQLSetEnvAttr ，並將 EnvironmentHandle 設定為 null，讓屬性成為進程層級屬性。
啟用連線共用之後，應用程式會呼叫 SQLAllocHandle ，並將 HandleType 引數設定為 SQL_HANDLE_ENV。 此呼叫配置的環境會成為隱含的共用環境，因為系統已啟用連線共用。
配置共用環境時，除非 呼叫具有 SQL_HANDLE_DBC HandleType 的 SQLAllocHandle ，否則不會判斷將使用的環境。 此時，驅動程式管理員會嘗試尋找符合應用程式所要求之環境屬性的現有環境。 如果不存在這類環境，則會建立一個作為共用環境。 驅動程式管理員會維護每個共用環境的參考計數;第一次建立環境時，計數會設定為 1。 如果找到相符的環境，該環境的控制碼會傳回至應用程式，並遞增參考計數。 以這種方式配置的環境控制碼可用於接受環境控制碼做為輸入引數的任何 ODBC 函式。
配置連接控制代碼
連接控制碼可讓您存取連接上的有效語句和描述元控制碼，以及目前是否開啟交易等資訊。 如需連接控制碼的一般資訊，請參閱 連接控制碼 。
若要要求連接控制碼，應用程式會呼叫 SQLAllocHandle ，其 HandleType 為 SQL_HANDLE_DBC。 InputHandle 引數會設定為配置該控制碼的 SQLAllocHandle 呼叫 所傳回的環境控制碼。 驅動程式會配置記憶體給連接資訊，並將相關聯控制碼的值傳回 *OutputHandlePtr 。 應用程式會在需要連接控制碼的所有後續呼叫中傳遞 *OutputHandlePtr 值。 如需詳細資訊，請參閱 配置連接控制碼 。
驅動程式管理員會處理 SQLAllocHandle 函式，並在應用程式呼叫 SQLConnect、 SQLBrowseConnect 或 SQLDriverConnect 時呼叫 驅動程式的 SQLAllocHandle 函式。 （如需詳細資訊，請參閱 SQLConnect 函式 。）
如果在呼叫 SQLAllocHandle 以在環境上配置連接控制碼之前 未設定SQL_ATTR_ODBC_VERSION環境屬性，則配置連接的呼叫會傳回 SQLSTATE HY010 （函數順序錯誤）。
當應用程式呼叫 SQLAllocHandle 且 InputHandle 引數設定為 SQL_HANDLE_DBC，同時設定為共用環境控制碼時，Driver Manager 會嘗試尋找符合應用程式所設定環境屬性的現有共用環境。 如果找不到類似環境，則系統會建立一個環境，其參考計數 (由驅動程式管理員維護) 為 1。 如果找到相符的共用環境，該控制碼會傳回給應用程式，並遞增其參考計數。
在呼叫 SQLConnect 或 SQLDriverConnect 之前 ，驅動程式管理員不會決定將使用的實際連線。 驅動程式管理員會使用針對 SQLConnect 呼叫中的連線選項 (或針對 SQLDriverConnect 呼叫中的連線關鍵字)，以及配置連線後設定的連線屬性，決定應該使用集區中的哪個連線。 如需詳細資訊，請參閱 SQLConnect 函式 。
配置陳述式控制代碼
語句控制碼可讓您存取語句資訊，例如錯誤訊息、資料指標名稱和 SQL 語句處理的狀態資訊。 如需語句控制碼的一般資訊，請參閱 語句控制碼 。
若要要求語句控制碼，應用程式會連接到資料來源，然後在提交 SQL 語句之前呼叫 SQLAllocHandle 。 在此呼叫中， HandleType 應該設定為 SQL_HANDLE_STMT，而 InputHandle 應該設定為配置該控制碼的 SQLAllocHandle 呼叫 所傳回的連接控制碼。 驅動程式會為語句資訊配置記憶體、將語句控制碼與指定的連接產生關聯，並將相關聯控制碼的值傳回 *OutputHandlePtr 。 應用程式會在需要語句控制碼的所有後續呼叫中傳遞 *OutputHandlePtr 值。 如需詳細資訊，請參閱 配置語句控制碼 。
配置語句控制碼時，驅動程式會自動設定一組四個描述元，並將這些描述項的控制碼指派給SQL_ATTR_APP_ROW_DESC、SQL_ATTR_APP_PARAM_DESC、SQL_ATTR_IMP_ROW_DESC和SQL_ATTR_IMP_PARAM_DESC語句屬性。 這些稱為 隱含配置的 描述元。 若要明確配置應用程式描述元，請參閱下一節「配置描述元控制碼」。
配置描述項控制碼
當應用程式使用 handleType SQL_HANDLE_DESC 呼叫 SQLAllocHandle 時，驅動程式會配置應用程式描述元。 這些稱為 明確 配置的描述元。 應用程式會指示驅動程式使用明確配置的應用程式描述元，而不是透過使用 SQL_ATTR_APP_ROW_DESC 或 SQL_ATTR_APP_PARAM_DESC 屬性呼叫 SQLSetStmtAttr 函式，自動為指定的語句控制碼配置一個。 實作描述元無法明確配置，也無法在 SQLSetStmtAttr 函式呼叫中 指定實作描述元。
明確配置的描述元會與連接控制碼相關聯，而不是語句控制碼（如自動設定的描述項所示）。 只有當應用程式實際連線到資料庫時，描述元才會被配置。 由於明確配置的描述元與連接控制碼相關聯，因此應用程式可以將明確配置的描述元與連接內的多個語句產生關聯。 另一方面，隱含配置的應用程式描述元無法與多個語句控制碼相關聯。 （它不能與它配置給以外的任何語句控制碼相關聯。明確配置的描述元控制碼可以由應用程式明確釋放，或 呼叫 SQLFreeHandle 搭配 handleType SQL_HANDLE_DESC，或在連接關閉時以隱含方式釋放。
釋放明確配置的描述元時，隱含配置的描述元會再次與 語句相關聯。 （該語句的SQL_ATTR_APP_ROW_DESC或SQL_ATTR_APP_PARAM_DESC屬性再次設定為隱含配置的描述元控制碼。這適用于與連接上明確配置描述元相關聯的所有語句。
如需描述項的詳細資訊，請參閱描述項。
程式碼範例
請參閱 ODBC 程式 範例、 SQLBrowseConnect 函 式、 SQLConnect 函 式和 SQLSetCursorName 函式 。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 執行 SQL 語句 | SQLExecDirect 函式 |
| 執行備妥的 SQL 語句 | SQLExecute 函式 |
| 釋放環境、連接、語句或描述項控制碼 | SQLFreeHandle 函式 |
| 準備語句以供執行 | SQLPrepare 函式 |
| 設定連接屬性 | SQLSetConnectAttr 函式 |
| 設定描述元欄位 | SQLSetDescField 函式 |
| 設定環境屬性 | SQLSetEnvAttr 函式 |
| 設定語句屬性 | SQLSetStmtAttr 函式 |
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應