符合性
推出版本：ODBC 3.81 標準合規：ODBC
總結
SQLRateConnection 判斷驅動程式是否能在連線池中重複使用現有連線。
Syntax
SQLRETURN SQLRateConnection(
SQLHDBC_INFO_TOKEN hRequest,
SQLHDBC hCandidateConnection,
BOOL fRequiredTransactionEnlistment,
TRANSID transId,
DWORD * pRating );
論點
h請求
[輸入]一個代表新應用程式連接請求的權杖。
hCandidateConnection
[輸入]連線池中現有的連線。 連線必須處於開啟狀態。
fRequiredTransactionEnlistment
[輸入]若為真，則重新使用現有連線的 hCandidateConnection 以執行新的連線請求（hRequest）需額外一次登錄。
transId
[輸入]如果 fRequiredTransactionEnlistment 為 TRUE，transId 代表請求將登錄的 DTC 交易。 如果 fRequiredTransactionEnlistment 是 FALSE，transID 將會被忽略。
pRating
[輸出] hCandidateConnection 對 hRequest 的重用評分。 這個評分會在0到100之間（含）之間。
Returns
SQL_SUCCESS、SQL_ERROR或SQL_INVALID_HANDLE。
Diagnostics
驅動程式管理員不會處理此功能回傳的診斷資訊。
備註
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 需要額外的 enlistment （transId ！= NULL） 或 unenlistment（transId == NULL）。 這表示重複使用連線的成本，以及如果要重複使用該連線，驅動程式是否應該加入或取消該連線。 如果 fRequireTransactionEnlistment 是 FALSE，驅動程式應該忽略 transID 的值。
驅動程式管理器保證 hRequest 與 hCandidateConnection 的父 HENV 句柄相同。 驅動程式管理器保證與 hRequest 與 hCandidateConnect 相關的池 ID 相同。
應用程式不應直接呼叫此函式。 支援驅動程式感知連線池的 ODBC 驅動程式必須實作此功能。
請包含 sqlspi.h 以開發 ODBC 驅動程式。