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
[輸出] hCandidateConnection hRequest 重複使用評等。 此評等將在 0 到 100 之間(含)。

傳回

SQL_SUCCESS、SQL_ERROR或SQL_INVALID_HANDLE。

診斷

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

備註

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

Score 意義(傳回SQL_SUCCESS時)
0 hCandidateConnection 不得重複使用給 hRequest
介於 1 到 98 之間的任何值(含) 分數越高,hCandidateConnection 與 hRequest 相符越近
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 的值

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

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

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

另請參閱

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