SQLRateConnection-Funktion

  • Artikel

Konformität
Version eingeführt: ODBC 3.81 Standards Compliance: ODBC

Zusammenfassung
SQLRateConnection bestimmt, ob ein Treiber eine vorhandene Verbindung im Verbindungspool wiederverwenden kann.

Syntax

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

Argumente

hRequest
[Eingabe] Ein Tokenhandle, das die neue Anwendungsverbindungsanforderung darstellt.

hCandidateConnection
[Eingabe] Die vorhandene Verbindung im Verbindungspool. Die Verbindung muss geöffnet sein.

fRequiredTransactionEnlistment
[Eingabe] Wenn TRUE, erfordert die Wiederverwendung der hCandidateConnection der vorhandenen Verbindung für die neue Verbindungsanforderung (hRequest) eine zusätzliche Registrierung.

transId
[Eingabe] Wenn fRequiredTransactionEnlistment TRUE ist, stellt transId die DTC-Transaktion dar, die von der Anforderung eingetragen wird. Wenn fRequiredTransactionEnlistment FALSE ist, wird transId ignoriert.

pRating
[Ausgabe] hCandidateConnection's reuse rating for the hRequest. Diese Bewertung liegt zwischen 0 und 100 (inklusive).

Gibt zurück

SQL_SUCCESS, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnose

Der Treiber-Manager verarbeitet keine Diagnoseinformationen, die von dieser Funktion zurückgegeben werden.

Bemerkungen

SQLRateConnection erzeugt eine Bewertung zwischen 0 und 100 (einschließlich), die angibt, wie gut eine vorhandene Verbindung mit der Anforderung übereinstimmt.

Bewertung Bedeutung (wenn SQL_SUCCESS zurückgegeben wird)
0 hCandidateConnection darf nicht für die hRequest wiederverwendet werden.
Beliebige Werte zwischen 1 und 98 (einschließlich) Je höher die Punktzahl, desto enger stimmt hCandidateConnection mit hRequest überein.
99 Es gibt nur Unstimmigkeiten bei unbedeutenden Attributen. Der Treiber-Manager sollte die Bewertungsschleife beenden.
100 Perfekte Übereinstimmung. Der Treiber-Manager sollte die Bewertungsschleife beenden.
Jeder andere Wert größer als 100 hCandidateConnection ist als tot markiert und wird auch in einer zukünftigen Verbindungsanforderung nicht wiederverwendet.

Der Treiber-Manager markiert eine Verbindung als nicht beendet, wenn der Rückgabecode nicht SQL_SUCCESS (einschließlich SQL_SUCCESS_WITH_INFO) ist oder die Bewertung größer als 100 ist. Diese nicht beendete Verbindung wird nicht wiederverwendet (auch nicht in zukünftigen Verbindungsanforderungen) und wird schließlich nach dem Bestanden von CPTimeout zeitverwendet. Der Treiber-Manager sucht weiterhin eine andere Verbindung aus dem Pool, um die Rate zu bewerten.

Wenn der Treiber-Manager eine Verbindung wiederverwendet hat, deren Bewertung streng kleiner als 100 (einschließlich 99) ist, ruft der Treiber-Manager SQLSetConnectAttr(SQL_ATTR_DBC_INFO_TOKEN) auf, um die Verbindung wieder in den von der Anwendung angeforderten Zustand zurückzusetzen. Der Treiber sollte die Verbindung in diesem Funktionsaufruf nicht zurücksetzen.

Wenn fRequiredTransactionEnlistment TRUE ist, ist für die Wiederverwendung von hCandidateConnection eine zusätzliche Aufnahme (transId != NULL) oder eine Nichteinlistung (transId == NULL) erforderlich. Dies gibt die Kosten für die Wiederverwendung einer Verbindung an und gibt an, ob der Treiber die Verbindung ein- bzw. aufheben soll, wenn die Verbindung wiederverwendet wird. Wenn fRequireTransactionEnlistment false ist, sollte der Treiber den Wert von transId ignorieren.

Der Treiber-Manager garantiert, dass das übergeordnete HENV-Handle von hRequest und hCandidateConnection identisch ist. Der Treiber-Manager garantiert, dass die pool-ID, die hRequest und hCandidateConnection zugeordnet ist, identisch ist.

Anwendungen sollten diese Funktion nicht direkt aufrufen. Diese Funktion muss von einem ODBC-Treiber implementiert werden, der treiberbasierte Verbindungspools unterstützt.

Schließen Sie sqlspi.h für die ODBC-Treiberentwicklung ein.

Weitere Informationen

Entwickeln eines ODBC-Treibers
Treiberfähiges Verbindungspooling
Entwickeln von Verbindungspool-Unterstützung in einem ODBC-Treiber