SQLRateConnection 関数

適合 性
導入されたバージョン: ODBC 3.81 標準準拠: ODBC

まとめ
SQLRateConnection は 、ドライバーが接続プール内の既存の接続を再利用できるかどうかを判断します。

構文

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

引数

hRequest
[入力]新しいアプリケーション接続要求を表すトークン ハンドル。

hCandidateConnection
[入力]接続プール内の既存の接続。 接続は開いている状態である必要があります。

fRequiredTransactionEnlistment
[入力]TRUE の場合、新しい接続要求 (hRequest) に対して既存の接続の hCandidateConnection を再利用するには、追加の参加リストが必要です。

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 hCandidateConnection、hRequest に再利用する必要があります
1 ~ 98 の値 (含む) スコアが高いほど 、hCandidateConnectionhRequest と一致するほど近くなります
99 重要ではない属性の不一致だけが存在します。 ドライバー マネージャーは、評価ループを停止する必要があります。
100 完全一致。 ドライバー マネージャーは、評価ループを停止する必要があります。
100 より大きいその他の値 hCandidateConnection は dead としてマークされ、今後の接続要求でも再利用されません。

リターン コードが 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 ドライバー対応接続プールの開発