SQLRateConnection 函式

一致性
引進的版本:ODBC 3.81 標準合規性:ODBC

總結
SQLRateConnection 會判斷驅動程式是否可以重複使用連接集區中的現有連線。

語法

  
SQLRETURN  SQLRateConnection(  
                SQLHDBC_INFO_TOKEN   hRequest,  
                SQLHDBC              hCandidateConnection,  
                BOOL                 fRequiredTransactionEnlistment,  
                TRANSID              transId,  
                DWORD *              pRating );  

引數

hRequest
[輸入]表示新應用程式連線要求的權杖控制碼。

hCandidateConnection
[輸入]連接集區中的現有連線。 連線必須處於已開啟狀態。

fRequiredTransactionEnlistment
[輸入]如果為 TRUE,則針對新的連線要求重複使用現有連線的 hCandidateConnection (hRequest) 需要額外的登記。

transId
[輸入]如果 fRequiredTransactionEnlistment 為 TRUE, transId 代表要求將登記的 DTC 交易。 如果 fRequiredTransactionEnlistment 為 FALSE,則會忽略 transId

pRating
[輸出] hCandidateConnectionhRequest重複使用評等。 此評等會介於 0 到 100 (內含) 之間。

傳回

SQL_SUCCESS、SQL_ERROR或SQL_INVALID_HANDLE。

診斷

驅動程式管理員不會處理從此函式傳回的診斷資訊。

備註

SQLRateConnection 會產生介於 0 到 100 (內含) 分數,指出現有連線與要求相符程度。

Score 傳回SQL_SUCCESS時 (的意義)
0 hCandidateConnection 不得針對 hRequest重複使用。
包含 1 到 98 之間的任何值 () 分數越高, hCandidateConnectionhRequest相符越接近。
99 在不重要的屬性中,只有不相符。 驅動程式管理員應該停止評等迴圈。
100 完美相符專案。 驅動程式管理員應該停止評等迴圈。
大於 100 的任何其他值 hCandidateConnection 標示為無效,即使在未來的連線要求中也不會重複使用。

如果傳回碼不是SQL_SUCCESS (,包括SQL_SUCCESS_WITH_INFO) 或評等大於 100,驅動程式管理員會將連線標示為無效。 即使未來連線要求) ,該無效連線也不會重複使用 (,而且最終會在 CPTimeout 通過之後逾時。 驅動程式管理員會繼續從集區尋找另一個連線至速率。

如果驅動程式管理員重複使用的連線分數嚴格小於 100 (,包括 99) ,驅動程式管理員會呼叫 SQLSetConnectAttr (SQL_ATTR_DBC_INFO_TOKEN) ,將連線重設為應用程式所要求的狀態。 驅動程式不應在此函式呼叫中重設連線。

如果 fRequiredTransactionEnlistment 為 TRUE,則重複使用 hCandidateConnection 需要額外的登記 (transId != Null) 或 unenlistment (transId == Null) 。 這表示重複使用連線的成本,以及驅動程式是否應該在連接重複使用時登記/取消登錄連線。 如果 fRequireTransactionEnlistment 為 FALSE,驅動程式應該忽略 transId的值。

驅動程式管理員保證 hRequesthCandidateConnection 的父 HENV 控制碼相同。 驅動程式管理員保證與 hRequesthCandidateConnection 相關聯的集區識別碼相同。

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

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

另請參閱

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