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 驅動程式開發。