SQLPoolConnect 函式

  • 發行項

一致性
引進的版本：ODBC 3.8 標準合規性：ODBC

摘要
如果沒有可重複使用集區中的連線，SQLPoolConnect 會用來建立新的連線。

語法

  
SQLRETURN  SQLPoolConnect(  
                SQLHDBC              hDbc,  
                SQLHDBC_INFO_TOKEN   hDbcInfoToken,  
                WCHAR *              wszOutConnectString,  
                SQLSMALLINT          cchConnectStringBuffer,  
                SQLSMALLINT *        cchConnectStringLen );

引數

hDbc
[輸入]連接控制碼。

hDbcInfoToken
[輸入]新應用程式連接要求的權杖控制碼。

wszOutConnectString
[輸出]已完成連接字串之緩衝區的指標。 成功連線至目標資料來源時，此緩衝區會包含已完成的連接字串。 應用程式應該為此緩衝區至少配置 1，024 個字元。

如果 wszOutConnectString 為 Null， cchConnectStringLen 仍會傳回字元總數（不包括字元資料的 Null 終止字元），以在 wszOutConnectString 所指向 的緩衝區中傳回。

cchConnectStringBuffer
[輸入]* wszOutConnectString 緩衝區的長度，以字元為單位。

cchConnectStringLen
[輸出]緩衝區的指標，用來傳回 * wszOutConnectString 中傳回的字元總數（不包括 Null 終止字元）。 如果可用傳回的字元數大於或等於 cchConnectStringBuffer，則 * wszOutConnectString 中已完成的連接字串會截斷為 cchConnectStringBuffer 減去 Null 終止字元的長度。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。

診斷

與 SQLDriverConnect 類似的輸入驗證錯誤，不同之處在于 Driver Manager 會使用 SQL_HANDLE_DBC_INFO_TOKEN 的 HandleType 和 hDbcInfoToken 的 HandleType 。

備註

驅動程式管理員保證 hDbc 和 hDbcInfoToken 的 父 HENV 控制碼相同。

不同于 SQLDriverConnect ，沒有 DriverCompletion 引數可提示使用者輸入連線資訊。 共用案例中不允許出現提示對話方塊。

應用程式不應該直接呼叫此函式。 支援驅動程式感知連接共用的 ODBC 驅動程式必須實作此函式。

每當驅動程式傳回SQL_ERROR或SQL_INVALID_HANDLE時，驅動程式管理員就會將錯誤傳回應用程式（在 SQLConnect 或 SQLDriverConnect 中）。

每當驅動程式傳回SQL_SUCCESS_WITH_INFO時，驅動程式管理員就會從 hDbcInfoToken 取得診斷資訊，並將SQL_SUCCESS_WITH_INFO傳回 SQLConnect 和 SQLDriverConnect 中的 應用程式。

當應用程式使用 SQLConnect 時， wszOutConnectString 會是 Null 緩衝區（最後三個參數全都設定為 Null、0、Null）。 否則，驅動程式必須傳回輸出連接字串，這會傳回至應用程式的 SQLDriverConnect 函 式呼叫。

包含 sqlspi.h 以進行 ODBC 驅動程式開發。

另請參閱

開發 ODBC 驅動程式
可感知驅動程式的連接共用
在 ODBC 驅動程式中開發連線集區覺察