Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Conformidade
Versão Introduzida: Normas ODBC 1.0 Conformidade: ISO 92
Summary
O SQLCancel cancela o processamento de uma instrução.
Para cancelar o processamento numa ligação ou sentação, use a Função SQLCancelHandle.
Syntax
SQLRETURN SQLCancel(
SQLHSTMT StatementHandle);
Arguments
HandleStatement
[Entrada] Identificador do extrato.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando o SQLCancel devolve 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 seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLCancel e explica cada um no contexto desta função; a notação "(DM)" precede as descrições dos SQLSTATEs devolvidas pelo Gestor de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.
| SQLSTATE | Erro | Description |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica para o condutor. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| HY000 | Erro geral | Ocorreu um erro para o qual não existia um SQLSTATE específico e para o qual não estava definido nenhum SQLSTATE específico da implementação. A mensagem de erro devolvida pelo SQLGetDiagRec no argumento *MessageText buffer descreve o erro e a sua causa. |
| HY001 | Erro de alocação de memória | O driver não conseguia alocar a memória necessária para suportar a execução ou conclusão da função. |
| HY010 | Erro de sequência de funções | (DM) Uma função de execução assíncrona era chamada para o handle de ligação associado ao StatementHandle. Esta função assíncrona ainda estava a ser executada quando a função SQLCancel foi chamada. (DM) Operação de cancelamento falhou porque uma operação assíncrona está em curso num handle de ligação associado ao StatementHandle. |
| HY013 | Erro de gestão de memória | A chamada de função não podia ser processada porque os objetos de memória subjacentes não podiam ser acedidos, possivelmente devido a condições de baixa memória. |
| HY018 | Pedido de cancelamento do servidor recusado | O servidor recusou o pedido de cancelamento. |
| HY117 | A ligação é suspensa devido ao estado desconhecido da transação. Apenas funções de desconexão e de leitura são permitidas. | (DM) Para mais informações sobre o estado suspenso, veja Função SQLEndTran. |
| HYT01 | Expirou o tempo limite de ligação | O período de timeout da ligação expirou antes de a fonte de dados responder ao pedido. O período de tempo de expiração da ligação é definido através do SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | O driver não suporta esta função | (DM) O driver associado ao StatementHandle não suporta a função. |
Comments
O SQLCancel pode cancelar os seguintes tipos de processamento numa instrução:
Uma função a correr assíncrona sobre a instrução.
Uma função numa instrução que precisa de dados.
Uma função a correr sobre a instrução noutro tópico.
No ODBC 2. x, se uma aplicação chamar SQLCancel quando não está a ser feito processamento na instrução, SQLCancel tem o mesmo efeito que SQLFreeStmt com a opção SQL_CLOSE; este comportamento é definido apenas para completude e as aplicações devem chamar SQLFreeStmt ou SQLCloseCursor para fechar cursores.
Quando o SQLCancel é chamado para cancelar uma função a correr assíncrona numa instrução ou uma função numa instrução que necessita de dados, os registos de diagnóstico publicados pela função a cancelar são apagados, e o SQLCancel publica os seus próprios registos de diagnóstico; quando o SQLCancel é chamado para cancelar uma função a correr numa instrução noutra thread, no entanto, não apaga os registos de diagnóstico da função que está a ser cancelada e não publica os seus próprios registos de diagnóstico.
Cancelamento do Processamento Assíncrono
Depois de uma aplicação chamar uma função de forma assíncrona, chama-a repetidamente para determinar se terminou o processamento. Se a função ainda estiver a processar, ela devolve SQL_STILL_EXECUTING. Se a função terminou o processamento, devolve um código diferente.
Após qualquer chamada à função que devolve SQL_STILL_EXECUTING, uma aplicação pode chamar SQLCancel para cancelar a função. Se o pedido de cancelamento for bem-sucedido, o motorista devolve SQL_SUCCESS. Esta mensagem não indica que a função foi realmente cancelada; indica que o pedido de cancelamento foi processado. Quando ou se a função é efetivamente cancelada depende do driver e da fonte de dados. A aplicação 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 for cancelada com sucesso, o código de retorno é SQL_ERROR e SQLSTATE HY008 (Operação cancelada). Se a função completou o seu processamento normal, o código de retorno é SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO se a função teve sucesso ou SQL_ERROR e um SQLSTATE diferente de HY008 (Operação cancelada) se a função falhou.
Note
No ODBC 3.5, uma chamada ao SQLCancel quando não está a ser feito processamento na instrução não é tratada como SQLFreeStmt com a opção SQL_CLOSE, mas não tem qualquer efeito. Para fechar um cursor, uma aplicação deve chamar SQLCloseCursor, e não SQLCancel.
Para mais informações sobre processamento assíncrono, consulte Execução Assíncrona.
Cancelamento de Funções que Necessitam de Dados
Após o retorno do SQLExecute ou SQLExecDirect SQL_NEED_DATA e antes de os dados terem sido enviados para todos os parâmetros de execução, uma aplicação pode chamar o SQLCancel para cancelar a execução da instrução. Depois de a instrução ser cancelada, a aplicação pode chamar novamente SQLExecute ou SQLExecDirect . Para mais informações, consulte SQLBindParameter.
Depois de o SQLBulkOperations ou SQLSetPos devolver SQL_NEED_DATA e antes de os dados terem sido enviados para todas as colunas de dados na execução, uma aplicação pode chamar o SQLCancel para cancelar a operação. Após o cancelamento da operação, a aplicação pode chamar novamente SQLBulkOperations ou SQLSetPos ; cancelar não afeta o estado do cursor nem a posição atual do cursor. Para mais informações, consulte SQLBulkOperations ou SQLSetPos.
Cancelamento de Funções a Executar Noutra Thread
Numa aplicação multithread, a aplicação pode cancelar uma função que está a correr noutra thread. Para cancelar a função, a aplicação chama SQLCancel com o mesmo handle de instrução usado pela função de destino, mas numa thread diferente. A forma como a função é cancelada depende do driver e do sistema operativo. Tal como no cancelamento de uma função a correr assíncrono, o código de retorno do SQLCancel indica apenas se o driver processou o pedido com sucesso. Apenas SQL_SUCCESS ou SQL_ERROR podem ser devolvidos; Não é devolvida qualquer informação de diagnóstico. Se a função original for cancelada, devolve SQL_ERROR e SQLSTATE HY008 (Operação cancelada).
Se uma instrução SQL estiver a ser executada quando o SQLCancel é chamado noutro thread para cancelar a execução da sentença, é possível que a execução tenha sucesso e retorne SQL_SUCCESS enquanto o cancelamento também é bem-sucedido. Neste caso, o Driver Manager assume que o cursor aberto pela execução da instrução está fechado pelo cancelamento, pelo que a aplicação não poderá usar o cursor.
Para mais informações sobre threading, consulte Multithreading.
Funções relacionadas
| Para obter informações sobre | Veja |
|---|---|
| Ligar um buffer a um parâmetro | Função SQLBindParameter |
| Realização de operações de inserção ou atualização em massa | Função SQLBulkOperations |
| Cancela uma função a correr assíncrona numa alavanca de ligação, além da funcionalidade do SQLCancel. | Função SQLCancelHandle |
| Execução de uma instrução SQL | Função SQLExecDirect |
| Execução de uma instrução SQL preparada | Função SQLExecute |
| Libertação de um handle de instrução | SQLFreeStmt |
| Obtenção de um campo de um registo de diagnóstico ou de um campo do cabeçalho de diagnóstico | Função SQLGetDiagField |
| Obtenção de vários campos de uma estrutura de dados de diagnóstico | Função SQLGetDiagRec |
| Devolver o próximo parâmetro para enviar dados para | Função SQLParamData |
| Envio de dados de parâmetros no momento da execução | da função SQLPutData |
| Posicionar o cursor num conjunto de linhas, atualizar dados no conjunto de linhas, ou atualizar ou eliminar dados do conjunto de resultados | Função SQLSetPos |