SQLRateConnection-Funktion

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 Tokenhandpunkt, der die neue Anwendungsverbindungsanforderung darstellt.

hCandidateConnection
[Eingabe] Die vorhandene Verbindung im Verbindungspool. Die Verbindung muss sich in einem geöffneten Zustand befinden.

fRequiredTransactionEnlistment
[Eingabe] Wenn TRUE verwendet wird, erfordert die erneute Verwendung der hCandidateConnection für die neue Verbindungsanforderung (hRequest) eine zusätzliche Liste.

transId
[Eingabe] Wenn fRequiredTransactionEnlistment TRUE ist, stellt transId die DTC-Transaktion dar, die die Anforderung auflisten wird. Wenn fRequiredTransactionEnlistment FALSCH ist, wird transId ignoriert.

pRating
[Ausgabe] hCandidateConnections Wiederverwendungsbewertung für hRequest. Diese Bewertung wird zwischen 0 und 100 (einschließlich) liegen.

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.

Hinweise

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 das hRequest wiederverwendet werden.
Alle Werte zwischen 1 und 98 (einschließlich)	Je höher die Bewertung ist, desto näher, dass hCandidateConnection mit hRequest übereinstimmt.
99	Es gibt nur Unübereinstimmungen in 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 gekennzeichnet und wird auch in einer zukünftigen Verbindungsanforderung nicht wiederverwendet.

Der Treiber-Manager markiert eine Verbindung als tot, wenn der Rückgabecode etwas anderes als SQL_SUCCESS (einschließlich SQL_SUCCESS_WITH_INFO) ist oder die Bewertung größer als 100 ist. Diese tote Verbindung wird nicht wiederverwendet (auch in zukünftigen Verbindungsanforderungen) und wird schließlich nach dem Übergeben von CPTimeout zeitüberschreitungen. Der Treiber-Manager sucht weiterhin eine weitere Verbindung vom Pool zu rate.

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 zustand zurückzusetzen, der von der Anwendung angefordert wird. Der Treiber sollte die Verbindung in diesem Funktionsaufruf nicht zurücksetzen.

Wenn fRequiredTransactionEnlistment TRUE ist, benötigt das erneute Verwenden von hCandidateConnection eine zusätzliche Enlistment (transId != NULL) oder unenlistment (transId == NULL). Dies gibt die Kosten für die erneute Verwendung einer Verbindung an und ob der Treiber die Verbindung auflisten / aufheben soll, wenn die Verbindung wiederverwendet werden soll. Wenn fRequireTransactionEnlistment FALSCH ist, sollte der Treiber den Wert von transId ignorieren.

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

Anwendungen sollten diese Funktion nicht direkt aufrufen. Ein ODBC-Treiber, der treiberfähige Verbindungspooling unterstützt, muss diese Funktion implementieren.

Schließen Sie sqlspi.h für die ENTWICKLUNG von ODBC-Treibern ein.

Weitere Informationen

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