Функция SQLRateConnection

Статья
08/21/2023

Соответствия
Представлена версия: соответствие стандартам 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
[Выходные данные] Рейтинг повторного использования hCandidateConnection для hRequest. Этот рейтинг будет находиться в диапазоне от 0 до 100 (включительно).

Возвраты

SQL_SUCCESS, SQL_ERROR или SQL_INVALID_HANDLE.

Диагностика

Диспетчер драйверов не обрабатывает диагностические сведения, возвращаемые из этой функции.

Замечания

SQLRateConnection создает оценку от 0 до 100 (включительно), указывая, насколько хорошо существующее соединение соответствует запросу.

Балл	Значение (при возврате SQL_SUCCESS)
0	hCandidateConnection не следует повторно использовать для hRequest.
Любые значения от 1 до 98 (включительно)	Чем выше оценка, тем ближе, что матч hCandidateConnection с hRequest.
99	Существуют только несоответствия в незначительных атрибутах. Диспетчер драйверов должен остановить цикл оценки.
100	Идеальный матч. Диспетчер драйверов должен остановить цикл оценки.
Любое другое значение больше 100	hCandidateConnection помечен как мертвый, и он не будет повторно использоваться даже в будущем запросе на подключение.

Диспетчер драйверов помечает подключение как мертвое, если код возврата не является 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.

Диспетчер драйверов гарантирует, что родительский дескриптор HENV hRequest и hCandidateConnection одинаковы. Диспетчер драйверов гарантирует, что идентификатор пула, связанный с hRequest и hCandidateConnection , совпадают.

Приложения не должны вызывать эту функцию напрямую. Драйвер ODBC, поддерживающий пул подключений с поддержкой драйверов, должен реализовать эту функцию.

Включите sqlspi.h для разработки драйверов ODBC.

См. также

Разработка драйвера ODBC
Организация пулов соединений с учетом драйвера
Разработка драйвера ODBC с поддержкой пула подключений

Поделиться через