SQLRateConnection 関数
準拠
導入されたバージョン: ODBC 3.81 Standards Compliance: 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 を含めます。