SQLRateConnection 函数SQLRateConnection Function

Conformance
引入的版本: ODBC 3.81 标准符合性: ODBCVersion Introduced: ODBC 3.81 Standards Compliance: ODBC

摘要Summary
SQLRateConnection 确定驱动程序是否可以重复使用连接池中的现有连接。SQLRateConnection determines if a driver can reuse an existing connection in the connection pool.

语法Syntax

  
SQLRETURN  SQLRateConnection(  
                SQLHDBC_INFO_TOKEN   hRequest,  
                SQLHDBC              hCandidateConnection,  
                BOOL                 fRequiredTransactionEnlistment,  
                TRANSID              transId,  
                DWORD *              pRating );  

参数Arguments

hRequesthRequest
送表示新应用程序连接请求的标记句柄。[Input] A token handle representing the new application connection request.

hCandidateConnectionhCandidateConnection
送连接池中的现有连接。[Input] The existing connection in the connection pool. 连接必须处于打开状态。The connection must be in an opened state.

fRequiredTransactionEnlistmentfRequiredTransactionEnlistment
送如果 为 TRUE,则为新 的连接请求重复使用现有连接 (hRequest) 需要额外的登记。[Input] If TRUE, reusing the existing connection's hCandidateConnection for the new connection request (hRequest) requires an additional enlistment.

transIdtransId
送如果 fRequiredTransactionEnlistment 为 TRUE,则 transId 表示请求将登记的 DTC 事务。[Input] If fRequiredTransactionEnlistment is TRUE, transId represents the DTC transaction that the request will enlist. 如果 fRequiredTransactionEnlistment 为 FALSE,则将忽略 transIdIf fRequiredTransactionEnlistment is FALSE, transId will be ignored.

pRatingpRating
输出 hCandidateConnectionhRequest 的重复使用评级。[Output] hCandidateConnection's reuse rating for the hRequest. 此级别将介于0到100之间 (包含) 之间。This rating will be in between 0 and 100 (inclusive).

返回Returns

SQL_SUCCESS、SQL_ERROR 或 SQL_INVALID_HANDLE。SQL_SUCCESS, SQL_ERROR, or SQL_INVALID_HANDLE.

诊断Diagnostics

驱动程序管理器不会处理从此函数返回的诊断信息。The Driver Manager will not process diagnostic information returned from this function.

备注Remarks

SQLRateConnection 生成0到100之间的分数 (包含) 指示现有连接与请求的匹配程度。SQLRateConnection produces a score between 0 and 100 (inclusive) indicating how well an existing connection matches the request.

分数Score 返回 SQL_SUCCESS 时的意义 () Meaning (when SQL_SUCCESS is returned)
00 hRequest 不能重复使用 hCandidateConnectionhCandidateConnection must not be reused for the hRequest.
1到98之间的任何值 (包含) Any values between 1 and 98 (inclusive) 分数越高, hCandidateConnectionhRequest 匹配越接近。The higher the score, the closer that hCandidateConnection match with hRequest.
9999 只有无意义的属性中存在不匹配的情况。There are only mismatches in insignificant attributes. 驱动程序管理器应停止评级循环。The Driver Manager should stop the rating loop.
100100 完全匹配。Perfect match. 驱动程序管理器应停止评级循环。The Driver Manager should stop the rating loop.
任何其他大于100的值Any other value greater than 100 hCandidateConnection 被标记为 "死",即使在未来的连接请求中也不会重复使用。hCandidateConnection is marked as dead and it will not be reused even in an future connection request.

如果返回代码不是 SQL_SUCCESS (包括 SQL_SUCCESS_WITH_INFO) 或分级大于100,驱动程序管理器会将连接标记为 "死"。The Driver Manager will mark a connection as dead if the return code is anything other than SQL_SUCCESS (including SQL_SUCCESS_WITH_INFO) or the rating is greater than 100. 即使在未来的连接请求) ,也不会重复使用该死连接 (,并最终会在 CPTimeout 通过后超时。That dead connection will not be reused (even in future connection requests) and will eventually be timed out after CPTimeout passes. 驱动程序管理器将继续从池中找到另一个连接以进行评级。The Driver Manager will continue to find another connection from the pool to rate.

如果驱动程序管理器重复使用某个连接,其分数严格小于 100 (包括 99) ,则驱动程序管理器将调用 SQLSetConnectAttr (SQL_ATTR_DBC_INFO_TOKEN) ,以将该连接重置回应用程序所请求的状态。If the Driver Manager reused a connection whose score is strictly smaller than 100 (including 99), the Driver Manager will call SQLSetConnectAttr(SQL_ATTR_DBC_INFO_TOKEN) to reset the connection back into the state requested by the application. 在此函数调用中,驱动程序不应重置连接。The driver should not reset the connection in this function call.

如果 fRequiredTransactionEnlistment 为 TRUE,则重复使用 hCandidateConnection 需要额外的登记 (transId ! = null) 或 unenlistment (transId = = null) 。If fRequiredTransactionEnlistment is TRUE, reusing hCandidateConnection needs an extra enlistment (transId != NULL) or unenlistment (transId == NULL). 这表示重新使用连接的成本,以及驱动程序是否应在该连接再次使用连接的情况下登记或取消登记连接。This indicates the cost of reusing a connection and whether the driver should enlist / unenlist the connection if it is going to reuse the connection. 如果 fRequireTransactionEnlistment 为 FALSE,则驱动程序应忽略 transId 的值。If fRequireTransactionEnlistment is FALSE, driver should ignore the value of transId.

驱动程序管理器保证 hRequestHCANDIDATECONNECTION 的父 HENV 句柄相同。The Driver Manager guarantees that the parent HENV handle of hRequest and hCandidateConnection are the same. 驱动程序管理器保证与 hRequesthCandidateConnection 相关联的池 ID 是相同的。The Driver Manager guarantees that the pool ID associated with hRequest and hCandidateConnection are the same.

应用程序不应直接调用此函数。Applications should not call this function directly. 支持驱动程序感知连接池的 ODBC 驱动程序必须实现此功能。An ODBC driver that supports driver-aware connection pooling must implement this function.

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

另请参阅See Also

开发 ODBC 驱动程序 Developing an ODBC Driver
识别驱动程序的连接池 Driver-Aware Connection Pooling
在 ODBC 驱动程序中开发连接池感知Developing Connection-Pool Awareness in an ODBC Driver