SQLRateConnection, fonction

Article
05/23/2023

Conformité
Version introduite : Conformité aux normes ODBC 3.81 : ODBC

Résumé
SQLRateConnection détermine si un pilote peut réutiliser une connexion existante dans le pool de connexions.

Syntaxe

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

Arguments

hRequest
[Entrée] Handle de jeton représentant la nouvelle demande de connexion d’application.

hCandidateConnection
[Entrée] Connexion existante dans le pool de connexions. La connexion doit être dans un état ouvert.

fRequiredTransactionEnlistment
[Entrée] Si la valeur est TRUE, la réutilisation de hCandidateConnection de la connexion existante pour la nouvelle demande de connexion (hRequest) nécessite une inscription supplémentaire.

transId
[Entrée] Si fRequiredTransactionEnlistment a la valeur TRUE, transId représente la transaction DTC que la demande inscrit. Si fRequiredTransactionEnlistment a la valeur FALSE, transId est ignoré.

pRating
[Sortie] Évaluation de réutilisation de hCandidateConnection pour hRequest. Cette évaluation sera comprise entre 0 et 100 (inclus).

Retours

SQL_SUCCESS, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Le Gestionnaire de pilotes ne traite pas les informations de diagnostic retournées par cette fonction.

Remarques

SQLRateConnection produit un score compris entre 0 et 100 (inclus) indiquant la correspondance entre une connexion existante et la demande.

Score	Signification (quand SQL_SUCCESS est retourné)
0	hCandidateConnection ne doit pas être réutilisé pour hRequest.
Toutes les valeurs comprises entre 1 et 98 (inclus)	Plus le score est élevé, plus la correspondance entre hCandidateConnection et hRequest est proche.
99	Il n’y a que des incompatibilités dans les attributs non significatifs. Le Gestionnaire de pilotes doit arrêter la boucle d’évaluation.
100	Correspondance parfaite. Le Gestionnaire de pilotes doit arrêter la boucle d’évaluation.
Toute autre valeur supérieure à 100	hCandidateConnection est marqué comme mort et ne sera pas réutilisé même dans une demande de connexion ultérieure.

Le Gestionnaire de pilotes marque une connexion comme étant morte si le code de retour est autre que SQL_SUCCESS (y compris SQL_SUCCESS_WITH_INFO) ou si la note est supérieure à 100. Cette connexion morte ne sera pas réutilisée (même dans les demandes de connexion ultérieures) et sera finalement expirée une fois cpTimeout passé. Le Gestionnaire de pilotes continuera à trouver une autre connexion à partir du pool pour le taux.

Si le Gestionnaire de pilotes a réutilisé une connexion dont le score est strictement inférieur à 100 (dont 99), le Gestionnaire de pilotes appelle SQLSetConnectAttr(SQL_ATTR_DBC_INFO_TOKEN) pour rétablir la connexion dans l’état demandé par l’application. Le pilote ne doit pas réinitialiser la connexion dans cet appel de fonction.

Si fRequiredTransactionEnlistment a la valeur TRUE, la réutilisation de hCandidateConnection nécessite une inscription supplémentaire (transId != NULL) ou une désinscription (transId == NULL). Cela indique le coût de réutilisation d’une connexion et indique si le pilote doit inscrire/désinscrire la connexion s’il veut réutiliser la connexion. Si fRequireTransactionEnlistment a la valeur FALSE, le pilote doit ignorer la valeur de transId.

Le Gestionnaire de pilotes garantit que le handle HENV parent de hRequest et hCandidateConnection sont identiques . Le Gestionnaire de pilotes garantit que l’ID de pool associé à hRequest et hCandidateConnection sont identiques.

Les applications ne doivent pas appeler cette fonction directement. Un pilote ODBC qui prend en charge le regroupement de connexions prenant en charge les pilotes doit implémenter cette fonction.

Incluez sqlspi.h pour le développement de pilotes ODBC.

Voir aussi

Développement d’un pilote ODBC
Regroupement de connexions prenant en charge les pilotes
Développement de la reconnaissance des pools de connexions dans un pilote ODBC

Partage via