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
[输出] hCandidateConnectionhRequest 重用分级。 此评级将在 0 到 100 ((含) )之间。

返回

SQL_SUCCESS、SQL_ERROR或SQL_INVALID_HANDLE。

诊断

驱动程序管理器不会处理从此函数返回的诊断信息。

注解

SQLRateConnection 生成 0 到 100 (非独占) 分数,指示现有连接与请求的匹配程度。

分数 表示返回SQL_SUCCESS时 ()
0 不得对 hRequest 重复使用 hCandidateConnection
介于 1 和 98 之间的任何值 ((含) ) 分数越高, hCandidateConnectionhRequest 匹配越近。
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) 或未登记 (transId == NULL) 。 这表示重新使用连接的成本,以及驱动程序是否在重新使用连接时应登记/取消登记连接。 如果 fRequireTransactionEnlistment 为 FALSE,驱动程序应忽略 transId 的值。

驱动程序管理器保证 hRequesthCandidateConnection 的父 HENV 句柄相同。 驱动程序管理器保证与 hRequesthCandidateConnection 关联的池 ID 相同。

应用程序不应直接调用此函数。 支持驱动程序感知连接池的 ODBC 驱动程序必须实现此函数。

包括用于 ODBC 驱动程序开发的 sqlspi.h。

另请参阅

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