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 を含めます。

参照

ODBC ドライバーの開発
ドライバー対応接続プール
ODBC ドライバー対応接続プールの開発