Compartilhar via

Função SQLCancelHandle

  • Artigo

Conformidade
Versão introduzida: Conformidade de padrões do ODBC 3.8: Nenhum

Espera-se que a maioria dos drivers ODBC 3.8 (e posteriores) implemente essa função. Se um driver não fizer isso, uma chamada para SQLCancelHandle com um identificador de conexão no parâmetro Handle retornará SQL_ERROR com um SQLSTATE de IM001 e a mensagem 'Driver não dá suporte a essa função'' Uma chamada para SQLCancelHandle com um identificador de instrução como o parâmetro Handle será mapeada para uma chamada para SQLCancel pelo Gerenciador de Driver e poderá ser processada se o driver implementar SQLCancel. Um aplicativo pode usar SQLGetFunctions para determinar se um driver dá suporte a SQLCancelHandle.

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 do identificador no qual o processamento de cacel deve ser processado. Os valores válidos são SQL_HANDLE_DBC ou SQL_HANDLE_STMT.

Handle
[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.

Retornos

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

Quando SQLCancelHandle 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 instrução Handle ou um HandleType de SQL_HANDLE_DBC e um identificador de conexão Handle.

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 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 Uma função relacionada à instrução em execução assíncrona foi chamada para um dos identificadores de instrução associados ao Handle e HandleType foi definido 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 essa função foi chamada.

(DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para um dos identificadores de instrução associados ao Handle e HandleType foi definido como SQL_HANDLE_DBC e retornado SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes de os dados serem recuperados para todos os parâmetros transmitidos.

SQLBrowseConnect foi chamado para ConnectionHandle e retornou SQL_NEED_DATA. Essa função foi chamada antes da conclusão do processo de navegação.
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.
HY092 Identificador de atributo/opção inválido HandleType foi definido como SQL_HANDLE_ENV ou SQL_HANDLE_DESC.
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 Identificador não dá suporte à função .

Se SQLCancelHandle for chamado com HandleType definido como SQL_HANDLE_STMT, ele poderá retornar qualquer SQLSTATE que possa ser retornado pela função SQLCancel.

Comentários

Essa função é semelhante a SQLCancel , mas pode usar uma conexão ou um identificador de 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 nenhuma operação em andamento em Manipular 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 em execução de forma assíncrona na conexão.

  • Uma função em execução no identificador de conexão em outro thread.

Quando SQLCancelHandle é chamado para cancelar uma função em execução de forma assíncrona em uma conexão, os registros de diagnóstico postados por SQLCancelHandle são acrescentados àqueles 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.

Usar SQLCancelHandle para cancelar SQLEndTran pode colocar a conexão no 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.

Se uma função retornar SQL_STILL_EXECUTING, um aplicativo poderá 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 a solicitação de cancelamento foi processada. O driver e a fonte de dados determinam quando ou se a operação foi 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 tiver sido cancelada, o código de retorno será SQL_ERROR e SQLSTATE HY008 (Operação cancelada). Se a função original tiver concluído seu processamento normal (não foi cancelada), o código de retorno será 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 em execução 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 código de retorno SQLCancelHandle 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 chamado em outro thread para cancelar a função, é possível que a função tenha êxito e retorne SQL_SUCCESS antes que o cancelamento possa entrar em vigor. Uma chamada para SQLCancelHandle não terá efeito se a operação for concluída antes que SQLCancelHandle possa cancelar a operação.

Para obter informações sobre Consulte
Cancelar uma função em execução de forma assíncrona em um identificador de instrução, cancelar uma função em uma instrução que precisa de dados ou cancelar uma função em execução em uma instrução em outro thread. Função SQLCancel

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC
Execução assíncrona (método polling)