Função SQLRateConnection

Conformidade
Versão introduzida: ODBC 3.81 Standards Compliance: ODBC

Resumo
SQLRateConnection determina se um driver pode reutilizar uma conexão existente no pool de conexões.

Sintaxe

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

Argumentos

hRequest
[Entrada] Um identificador de token que representa a nova solicitação de conexão de aplicativo.

hCandidateConnection
[Entrada] A conexão existente no pool de conexões. A conexão deve estar em um estado aberto.

fRequiredTransactionEnlistment
[Entrada] Se TRUE, reutilizar hCandidateConnection da conexão existente para a nova solicitação de conexão (hRequest) exigirá uma inscrição adicional.

transId
[Entrada] Se fRequiredTransactionEnlistment for TRUE, transId representará a transação DTC que a solicitação inscreverá. Se fRequiredTransactionEnlistment for FALSE, transId será ignorado.

pRating
[Saída] Classificação de reutilização de hCandidateConnection para o hRequest. Essa classificação será entre 0 e 100 (inclusive).

Retornos

SQL_SUCCESS, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

O Gerenciador de Driver não processará as informações de diagnóstico retornadas dessa função.

Comentários

SQLRateConnection produz uma pontuação entre 0 e 100 (inclusive) indicando o quão bem uma conexão existente corresponde à solicitação.

Pontuação	Significado (quando SQL_SUCCESS é retornado)
0	hCandidateConnection não deve ser reutilizado para o hRequest.
Todos os valores entre 1 e 98 (inclusive)	Quanto maior a pontuação, mais próximo que hCandidateConnection corresponder com hRequest.
99	Há apenas incompatibilidades em atributos insignificantes. O Gerenciador de Driver deve interromper o loop de classificação.
100	Combinação perfeita. O Gerenciador de Driver deve interromper o loop de classificação.
Qualquer outro valor maior que 100	hCandidateConnection está marcado como morto e não será reutilizado mesmo em uma solicitação de conexão futura.

O Gerenciador de Driver marcará uma conexão como morta se o código de retorno for diferente de SQL_SUCCESS (incluindo SQL_SUCCESS_WITH_INFO) ou a classificação for maior que 100. Essa conexão morta não será reutilizado (mesmo em solicitações de conexão futuras) e acabará atingindo o tempo limite após a aprovação do CPTimeout. O Gerenciador de Driver continuará a encontrar outra conexão do pool com a taxa.

Se o Gerenciador de Driver reutiliza uma conexão cuja pontuação é estritamente menor que 100 (incluindo 99), o Gerenciador de Driver chamará SQLSetConnectAttr(SQL_ATTR_DBC_INFO_TOKEN) para redefinir a conexão de volta para o estado solicitado pelo aplicativo. O driver não deve redefinir a conexão nesta chamada de função.

Se fRequiredTransactionEnlistment for TRUE, reutilizar hCandidateConnection precisará de um alistamento extra (transId != NULL) ou unenlistment (transId == NULL). Isso indica o custo de reutilização de uma conexão e se o driver deve inscrever/desenlistar a conexão se for reutilizar a conexão. Se fRequireTransactionEnlistment for FALSE, o driver deverá ignorar o valor de transId.

O Gerenciador de Driver garante que o identificador HENV pai de hRequest e hCandidateConnection sejam os mesmos. O Gerenciador de Driver garante que a ID do pool associada a hRequest e hCandidateConnection seja a mesma.

Os aplicativos não devem chamar essa função diretamente. Um driver ODBC que dá suporte ao pool de conexões com reconhecimento de driver deve implementar essa função.

Inclua sqlspi.h para desenvolvimento de driver ODBC.

Consulte Também

Desenvolver um driver ODBC
Pool de conexões com reconhecimento de driver
Desenvolvimento um reconhecimento de pool de conexão em um driver ODBC