Partilhar via


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.

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

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC