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