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 (（含）) 分数，指示现有连接与请求的匹配程度。
| 分数 | 表示) 返回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 关联的池 ID 相同。
应用程序不应直接调用此函数。 支持驱动程序感知连接池的 ODBC 驱动程序必须实现此函数。
包括用于 ODBC 驱动程序开发的 sqlspi.h。