Função SQLCancel
Compatibilidade
Versão introduzida: ODBC 1.0 Conformidade com os padrões: ISO 92
Resumo
SQLCancel cancela o processamento em uma instrução.
Para cancelar o processamento em uma conexão ou instrução, use a função SQLCancelHandle.
Sintaxe
SQLRETURN SQLCancel(
SQLHSTMT StatementHandle);
Argumentos
Identificador de declaração
[Entrada] Identificador de instrução.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLCancel retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_STMT e um Handle de StatementHandle. A tabela a seguir lista os valores SQLSTATE comumente retornados pelo SQLCancel e explica cada um deles no contexto dessa função; a notação "(DM)" precede as descrições de SQLSTATEs retornadas pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.
| SQLSTATE | Erro | Descrição |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica do driver. (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 da implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no buffer de argumento *MessageText 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 dar suporte à execução ou conclusão da função. |
| HY010 | Erro de sequência de função | (DM) Uma função de execução assíncrona foi chamada para o identificador de conexão associado ao StatementHandle. Essa função assíncrona ainda estava em execução quando a função SQLCancel foi chamada. (DM) Falha na operação de cancelamento porque uma operação assíncrona está em andamento em um identificador de conexão associado a StatementHandle. |
| 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 memória baixa. |
| HY018 | Servidor recusou solicitação de cancelamento | O servidor recusou a solicitação de cancelamento. |
| HY117 | A conexão está suspensa devido ao estado desconhecido da transação. Somente 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 da conexão expirou | O período de tempo limite da conexão expirou antes que a fonte de dados respondesse à solicitação. O período de tempo limite da conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | O driver não suporta esta função | (DM) O driver associado ao StatementHandle não dá suporte à função. |
Comentários
O SQLCancel pode cancelar os seguintes tipos de processamento em uma instrução:
Uma função em execução assíncrona na instrução.
Uma função em uma instrução que precisa de dados.
Uma função em execução na instrução em outro thread.
No ODBC 2.x, se um aplicativo chamar SQLCancel quando nenhum processamento estiver sendo feito na instrução, SQLCancel terá o mesmo efeito que SQLFreeStmt com a opção SQL_CLOSE; esse comportamento é definido apenas para integridade e os aplicativos devem chamar SQLFreeStmt ou SQLCloseCursor para fechar cursores.
Quando SQLCancel é chamado para cancelar uma função em execução assíncrona em uma instrução ou uma função em uma instrução que precisa de dados, os registros de diagnóstico postados pela função que está sendo cancelada são limpos e SQLCancel posta seus próprios registros de diagnóstico; no entanto, quando SQLCancel é chamado para cancelar uma função em execução em uma instrução em outro thread, ele não limpa os registros de diagnóstico da função que está sendo cancelada e não posta seus próprios registros de diagnóstico.
Cancelando o processamento assíncrono
Depois que um aplicativo chama uma função de forma assíncrona, ele chama a função repetidamente para determinar se ela concluiu o processamento. Se a função ainda estiver sendo processada, ela retornará SQL_STILL_EXECUTING. Se a função tiver concluído o processamento, ela retornará um código diferente.
Após qualquer chamada para a função que retorna SQL_STILL_EXECUTING, um aplicativo pode chamar SQLCancel para cancelar a função. Se a solicitação de cancelamento for bem-sucedida, o driver retornará SQL_SUCCESS. Essa mensagem não indica que a função foi realmente cancelada, mas indica que a solicitação de cancelamento foi processada. Quando ou se a função for realmente cancelada depende do driver e da fonte de dados. 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 foi cancelada com êxito, o código de retorno será SQL_ERROR e SQLSTATE HY008 (Operação cancelada). Se a função tiver concluído seu processamento normal, o código de retorno será SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO se a função tiver sido bem-sucedida ou SQL_ERROR e um SQLSTATE diferente de HY008 (Operação cancelada) se a função falhar.
Observação
No ODBC 3.5, uma chamada para SQLCancel quando nenhum processamento está sendo feito na instrução não é tratada como SQLFreeStmt com a opção SQL_CLOSE, mas não tem nenhum efeito. Para fechar um cursor, um aplicativo deve chamar SQLCloseCursor, não SQLCancel.
Para obter mais informações sobre o processamento assíncrono, consulte Execução assíncrona.
Cancelando funções que precisam de dados
Depois que SQLExecute ou SQLExecDirect retorna SQL_NEED_DATA e antes que os dados sejam enviados para todos os parâmetros de dados em execução, um aplicativo pode chamar SQLCancel para cancelar a execução da instrução. Depois que a instrução for cancelada, o aplicativo poderá chamar SQLExecute ou SQLExecDirect novamente. Para obter mais informações, consulte SQLBindParameter.
Depois que SQLBulkOperations ou SQLSetPos retorna SQL_NEED_DATA e antes que os dados sejam enviados para todas as colunas de dados em execução, um aplicativo pode chamar SQLCancel para cancelar a operação. Depois que a operação for cancelada, o aplicativo poderá chamar SQLBulkOperations ou SQLSetPos novamente; o cancelamento não afeta o estado do cursor ou a posição atual do cursor. Para obter mais informações, consulte SQLBulkOperations ou SQLSetPos.
Cancelando funções em execução em outro thread
Em um aplicativo multithread, o aplicativo pode cancelar uma função que está sendo executada em outro thread. Para cancelar a função, o aplicativo chama SQLCancel com o mesmo identificador de instrução usado pela função de destino, mas em um thread diferente. A forma como a função é cancelada depende do driver e do sistema operacional. Como no cancelamento de uma função em execução assíncrona, o código de retorno do SQLCancel indica apenas se o driver processou a solicitação com êxito. Apenas SQL_SUCCESS ou SQL_ERROR podem ser devolvidos; Nenhuma informação de diagnóstico é retornada. Se a função original for cancelada, ela retornará SQL_ERROR e SQLSTATE HY008 (Operação cancelada).
Se uma instrução SQL estiver sendo executada quando SQLCancel for chamado em outro thread para cancelar a execução da instrução, é possível que a execução seja bem-sucedida e retorne SQL_SUCCESS enquanto o cancelamento também for bem-sucedido. Nesse caso, o Gerenciador de Driver pressupõe que o cursor aberto pela execução da instrução é fechado pelo cancelamento, portanto, o aplicativo não poderá usar o cursor.
Para obter mais informações sobre threading, consulte Multithreading.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Associando um buffer a um parâmetro | Função SQLBindParameter |
| Executando operações de inserção ou atualização em massa | Função SQLBulkOperations |
| Cancela uma função em execução assíncrona em um identificador de conexão, além da funcionalidade do SQLCancel. | Função SQLCancelHandle |
| Executando uma instrução SQL | Função SQLExecDirect |
| Executando uma instrução SQL preparada | Função SQLExecute |
| Liberando um identificador de instrução | SQLFreeStmt |
| Obtendo um campo de um registro de diagnóstico ou um campo do cabeçalho de diagnóstico | Função SQLGetDiagField |
| Obtendo vários campos de uma estrutura de dados de diagnóstico | Função SQLGetDiagRec |
| Retornando o próximo parâmetro para o qual enviar dados | Função SQLParamData |
| Enviando dados de parâmetro em tempo de execução | Função SQLPutData |
| Posicionar o cursor em um conjunto de linhas, atualizar dados no conjunto de linhas ou atualizar ou excluir dados no conjunto de resultados | Função SQLSetPos |