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。

另请参阅

开发 ODBC 驱动程序
识别驱动程序的连接池
在 ODBC 驱动程序中开发连接池感知