Função SQLCancel
Conformidade
Versão introduzida: Conformidade de padrões do ODBC 1.0: 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
StatementHandle
[Entrada] Identificador de instrução.
Retornos
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 Identificador de StatementHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por 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 o contrário.
| 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 nenhum SQLSTATE específico e para o qual nenhum SQLSTATE específico da implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no 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 dar suporte à execução ou à conclusão da função. |
| HY010 | Erro de sequência de funções | (DM) Uma função em 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 | Solicitação de cancelamento recusada pelo servidor | O servidor recusou a solicitação de cancelamento. |
| HY117 | A conexão está suspensa devido ao estado de transação desconhecido. Somente funções desconectar 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 da fonte de dados responder à 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 dá suporte a essa 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 de forma 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 de forma assíncrona em uma instrução ou em 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 o SQLCancel posta seus próprios registros de diagnóstico; quando SQLCancel é chamado para cancelar uma função em execução em uma instrução em outro thread, no entanto, ele não limpa os registros de diagnóstico da função que está sendo cancelada e não publica 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 terminou o processamento. Se a função ainda estiver sendo processada, ela retornará SQL_STILL_EXECUTING. Se a função tiver terminado 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; indica que a solicitação de cancelamento foi processada. Quando ou se a função for realmente cancelada é dependente de driver e dependente 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 tiver sido 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 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 retornar SQL_NEED_DATA e antes de os dados serem enviados para todas as colunas de dados em execução, um aplicativo poderá chamar SQLCancel para cancelar a operação. Depois que a operação for cancelada, o aplicativo poderá chamar SQLBulkOperations ou SQLSetPos novamente; cancelar 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á em execução 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. Assim como no cancelamento de uma função em execução de forma assíncrona, o código de retorno do SQLCancel indica apenas se o driver processou a solicitação com êxito. Somente SQL_SUCCESS ou SQL_ERROR podem ser retornados; 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, será 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 seja 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 |
|---|---|
| Associar 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 de forma 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 |
| Enviar dados de parâmetro no momento da execução | Função SQLPutData |
| Posicionando o cursor em um conjunto de linhas, atualizando dados no conjunto de linhas ou atualizando ou excluindo dados no conjunto de resultados | Função SQLSetPos |