Função SQLCancelHandle
Conformidade
Versão introduzida: ODBC 3.8 Conformidade com padrões: Nenhum
Espera-se que a maioria dos drivers ODBC 3.8 (e posteriores) implemente essa função. Se um driver não funcionar, uma chamada para
Resumo
SQLCancelHandle cancela o processamento em uma conexão ou instrução. O Gerenciador de Driver mapeia uma chamada para SQLCancelHandle para uma chamada para SQLCancel quando HandleType é SQL_HANDLE_STMT.
Sintaxe
SQLRETURN SQLCancelHandle(
SQLSMALLINT HandleType,
SQLHANDLE Handle);
Argumentos
HandleType
[Entrada] O tipo de identificador no qual cancelar o processamento. Os valores válidos são SQL_HANDLE_DBC ou SQL_HANDLE_STMT.
Manipular
[Entrada] O identificador no qual cancelar o processamento.
Se Handle não for um identificador válido do tipo especificado por HandleType, SQLCancelHandle retornará SQL_INVALID_HANDLE.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnóstico
Quando
A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLCancelHandle e explica cada um deles no contexto dessa função; a notação "(DM)" precede as descrições de SQLSTATEs retornados pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.
| SQLSTATE | Erro | Descrição |
|---|---|---|
| 01000 | Advertência geral | Mensagem informativa específica do motorista. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| HY000 | Erro geral | Ocorreu um erro para o qual não havia SQLSTATE específico e para o qual nenhum SQLSTATE específico de implementação foi definido. A mensagem de erro retornada pelo SQLGetDiagRec no de argumento *MessageText buffer descreve o erro e sua causa. |
| HY001 | Erro de alocação de memória | O driver não pôde alocar a memória necessária para suportar a execução ou conclusão da função. |
| HY010 | Erro de sequência de função | Uma função relacionada à instrução de execução assíncrona foi chamada para um dos identificadores de instrução associados ao Handlee HandleType foi definida como SQL_HANDLE_DBC. A função assíncrona ainda estava em execução quando SQLCancelHandle foi chamado. (DM) O argumento HandleType foi SQL_HANDLE_STMT; uma função de execução assíncrona foi chamada no identificador de conexão associado; e a função ainda estava em execução quando esta função foi chamada. (DM) SQLExecute, SQLExecDirectou SQLMoreResults foi chamado para um dos identificadores de instrução associados ao Handle e HandleType foi definido como SQL_HANDLE_DBC e retornou SQL_PARAM_DATA_AVAILABLE. Esta função foi chamada antes que os dados fossem recuperados para todos os parâmetros transmitidos. SQLBrowseConnect foi chamado para ConnectionHandle e retornou SQL_NEED_DATA. Esta função foi chamada antes do processo de navegação concluído. |
| HY013 | Erro de gerenciamento de memória | A chamada de função não pôde ser processada porque os objetos de memória subjacentes não puderam ser acessados, possivelmente devido a condições de pouca memória. |
| HY092 | Identificador de atributo/opção inválido | HandleType foi definido como SQL_HANDLE_ENV ou SQL_HANDLE_DESC. |
| HY117 | A conexão é suspensa devido ao estado desconhecido da transação. Apenas as funções de desconexão e somente leitura são permitidas. | (DM) Para obter mais informações sobre o estado suspenso, consulte função SQLEndTran. |
| HYT01 | O tempo limite de conexão expirou | O período de tempo limite de conexão expirou antes que a fonte de dados respondesse à solicitação. O período de tempo limite da conexão é definido por meio SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Driver não suporta esta função | (DM) O condutor associado ao de |
Se SQLCancelHandle for chamado com HandleType definido como SQL_HANDLE_STMT, ele poderá retornar qualquer SQLSTATE que possa ser retornado pela função SQLCancel.
Observações
Essa função é semelhante a SQLCancel, mas pode tomar um identificador de conexão ou instrução como um parâmetro em vez de apenas um identificador de instrução. O Gerenciador de Driver mapeia uma chamada para SQLCancelHandle para uma chamada para SQLCancel quando HandleType é SQL_HANDLE_STMT. Isso permite que os aplicativos usem SQLCancelHandle para cancelar operações de instrução mesmo que o driver não implemente SQLCancelHandle.
Para obter mais informações sobre como cancelar uma operação de instrução, consulte função SQLCancel.
Se não houver operações em andamento no Handle a chamada para SQLCancelHandle não terá efeito.
SQLCancelHandle em um identificador de conexão pode cancelar os seguintes tipos de processamento:
Uma função executada de forma assíncrona na conexão.
Uma função em execução na alça de conexão em outro thread.
Quando SQLCancelHandle é chamado para cancelar uma função em execução assíncrona em uma conexão, os registros de diagnóstico postados por SQLCancelHandle são anexados aos retornados pela operação que está sendo cancelada; SQLCancelHandle não retorna registros de diagnóstico, no entanto, ao cancelar uma função em execução em uma conexão em outro thread.
Usando SQLCancelHandle para cancelar SQLEndTran pode colocar a conexão em estado suspenso. Para obter mais informações sobre o estado suspenso, consulte função SQLEndTran.
Observação
Para obter informações sobre como usar SQLCancelHandle em um aplicativo que será implantado em um sistema operacional Windows anterior ao Windows 7, consulte Matriz de compatibilidade.
Cancelando Connection-Related processamento assíncrono
Se uma função retornar SQL_STILL_EXECUTING, um aplicativo pode chamar SQLCancelHandle para cancelar a operação. Se a solicitação de cancelamento for bem-sucedida, SQLCancelHandle retornará SQL_SUCCESS. Isso não significa que a função original foi cancelada; indica que o pedido de cancelamento foi processado. O driver e a fonte de dados determinam quando ou se a operação é cancelada. O aplicativo deve continuar a chamar a função original até que o código de retorno não seja SQL_STILL_EXECUTING. Se a função original foi cancelada, o código de retorno é SQL_ERROR e SQLSTATE HY008 (Operação cancelada). Se a função original completou seu processamento normal (não foi cancelado), o código de retorno é SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO, ou SQL_ERROR e um SQLSTATE diferente de HY008 (Operação cancelada), se a função original falhar.
Cancelando funções em execução em outro thread
Em um aplicativo multithread, o aplicativo pode cancelar uma operação que está sendo executada em outro thread. Para cancelar a operação, o aplicativo chama SQLCancelHandle com o identificador usado pela função, mas em um thread diferente. O driver e o sistema operacional determinam como a operação é cancelada. O SQLCancelHandle código de retorno indica se o driver processou a solicitação, retornando SQL_SUCCESS ou SQL_ERROR (nenhuma informação de diagnóstico é retornada). Se o processamento na função original for cancelado, a função original retornará SQL_ERROR e SQLSTATE HY008 (Operação cancelada).
Se uma função estiver sendo executada quando SQLCancelHandle for chamada em outro thread para cancelar a função, é possível que a função seja bem-sucedida e retorne SQL_SUCCESS antes que o cancel possa entrar em vigor. Uma chamada para SQLCancelHandle não terá efeito se a operação for concluída antes de SQLCancelHandle foi capaz de cancelar a operação.
Funções relacionadas
Ver também
de referência da API ODBC
Arquivos de cabeçalho ODBC
Execução assíncrona (método de sondagem)