Función SQLRateConnection

Conformidad
Versión introducida: Cumplimiento de estándares odbc 3.81: ODBC

Resumen
SQLRateConnection determina si un controlador puede reutilizar una conexión existente en el grupo de conexiones.

Sintaxis

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

Argumentos

hRequest
[Entrada] Identificador de token que representa la nueva solicitud de conexión de la aplicación.

hCandidateConnection
[Entrada] Conexión existente en el grupo de conexiones. La conexión debe estar en un estado abierto.

fRequiredTransactionEnlistment
[Entrada] Si es TRUE, la reutilización de hCandidateConnection de la conexión existente para la nueva solicitud de conexión (hRequest) requiere una inscripción adicional.

transId
[Entrada] Si fRequiredTransactionEnlistment es TRUE, transId representa la transacción DTC que la solicitud inscribirá. Si fRequiredTransactionEnlistment es FALSE, se omitirá transId .

pRating
[Salida] Clasificación de reutilización de hCandidateConnection para hRequest. Esta clasificación estará entre 0 y 100 (inclusive).

Devoluciones

SQL_SUCCESS, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnóstico

El Administrador de controladores no procesará la información de diagnóstico devuelta desde esta función.

Comentarios

SQLRateConnection genera una puntuación entre 0 y 100 (inclusive) que indica el estado de coincidencia de una conexión existente con la solicitud.

Puntuación	Significado (cuando se devuelve SQL_SUCCESS)
0	hCandidateConnection no se debe reutilizar para hRequest.
Cualquier valor entre 1 y 98 (ambos incluidos)	Cuanto mayor sea la puntuación, más cercana será la coincidencia de hCandidateConnection con hRequest.
99	Solo hay discrepancias en atributos insignificantes. El Administrador de controladores debe detener el bucle de clasificación.
100	Coincidencia perfecta. El Administrador de controladores debe detener el bucle de clasificación.
Cualquier otro valor mayor que 100	hCandidateConnection se marca como inactivo y no se volverá a usar incluso en una solicitud de conexión futura.

El Administrador de controladores marcará una conexión como inactiva si el código de retorno es distinto de SQL_SUCCESS (incluido SQL_SUCCESS_WITH_INFO) o la clasificación es mayor que 100. Esa conexión inactiva no se volverá a usar (incluso en futuras solicitudes de conexión) y finalmente se agotará el tiempo de espera después de que CPTimeout pase. El Administrador de controladores seguirá buscando otra conexión del grupo a la tarifa.

Si el Administrador de controladores ha reutilizado una conexión cuya puntuación es estrictamente inferior a 100 (incluido 99), el Administrador de controladores llamará a SQLSetConnectAttr(SQL_ATTR_DBC_INFO_TOKEN) para restablecer la conexión en el estado solicitado por la aplicación. El controlador no debe restablecer la conexión en esta llamada de función.

Si fRequiredTransactionEnlistment es TRUE, la reutilización de hCandidateConnection necesita una inscripción adicional (transId != NULL) o anular la inscripción (transId == NULL). Esto indica el costo de reutilizar una conexión y si el controlador debe inscribir o anular la inscripción de la conexión si va a reutilizar la conexión. Si fRequireTransactionEnlistment es FALSE, el controlador debe omitir el valor de transId.

El Administrador de controladores garantiza que el controlador HENV primario de hRequest y hCandidateConnection sean los mismos. El Administrador de controladores garantiza que el identificador del grupo asociado a hRequest y hCandidateConnection son los mismos.

Las aplicaciones no deben llamar directamente a esta función. Un controlador ODBC que admita la agrupación de conexiones compatibles con controladores debe implementar esta función.

Incluya sqlspi.h para el desarrollo de controladores ODBC.

Consulte también

Desarrollar un controlador ODBC
Agrupación de conexiones dependientes del controlador
Desarrollar el conocimiento de la agrupación de conexiones en un controlador ODBC