Función SQLCancelHandle

  • Artículo

Conformidad
Versión introducida: Cumplimiento de estándares ODBC 3.8: Ninguno

Se espera que la mayoría de los controladores ODBC 3.8 (y versiones posteriores) implementen esta función. Si un controlador no lo hace, una llamada a SQLCancelHandle con un identificador de conexión en el parámetro Handle devolverá SQL_ERROR con un SQLSTATE de IM001 y el mensaje "Driver does not support this function"" Una llamada a SQLCancelHandle con un identificador de instrucción, ya que el parámetro Handle se asignará a una llamada a SQLCancel por el Administrador de controladores y se puede procesar si el controlador implementa SQLCancel. Una aplicación puede usar SQLGetFunctions para determinar si un controlador admite SQLCancelHandle.

Resumen
SQLCancelHandle cancela el procesamiento en una conexión o instrucción. El Administrador de controladores asigna una llamada a SQLCancelHandle a una llamada a SQLCancel cuando HandleType está SQL_HANDLE_STMT.

Sintaxis

  
SQLRETURN SQLCancelHandle(  
      SQLSMALLINT  HandleType,  
      SQLHANDLE    Handle);

Argumentos

HandleType
[Entrada] Tipo del identificador en el que se va a procesar cacel. Los valores válidos son SQL_HANDLE_DBC o SQL_HANDLE_STMT.

Handle
[Entrada] Identificador en el que se va a cancelar el procesamiento.

Si Handle no es un identificador válido del tipo especificado por HandleType, SQLCancelHandle devuelve SQL_INVALID_HANDLE.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnóstico

Cuando SQLCancelHandle devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado mediante una llamada a SQLGetDiagRec con un HandleType de SQL_HANDLE_STMT y un identificador de instrucción Handle o un HandleType de SQL_HANDLE_DBC y un identificador de conexión.

En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLCancelHandle y se explica cada uno en el contexto de esta función; la notación "(DM)" precede a las descripciones de SQLSTATEs devueltas por el Administrador de controladores. El código de retorno asociado a cada valor SQLSTATE es SQL_ERROR, a menos que se indique lo contrario.

SQLSTATE Error Descripción
01000 Advertencia general Mensaje informativo específico del controlador. (Function devuelve SQL_SUCCESS_WITH_INFO).
HY000 Error general Se produjo un error para el que no había ningún SQLSTATE específico y para el que no se definió SQLSTATE específico de la implementación. El mensaje de error devuelto por SQLGetDiagRec en el argumento *MessageText buffer describe el error y su causa.
HY001 Error de asignación de memoria El controlador no pudo asignar memoria necesaria para admitir la ejecución o finalización de la función.
HY010 Error de secuencia de función Se llamó a una función relacionada con instrucciones de ejecución asincrónica para uno de los identificadores de instrucción asociados a Handle y HandleType se estableció en SQL_HANDLE_DBC. La función asincrónica todavía se estaba ejecutando cuando se llamó a SQLCancelHandle .

(DM) El argumento HandleType se SQL_HANDLE_STMT; se llamó a una función de ejecución asincrónica en el identificador de conexión asociado; y la función todavía se estaba ejecutando cuando se llamó a esta función.

Se llamó a SQLExecute, SQLExecDirect o SQLMoreResults para uno de los identificadores de instrucción asociados a Handle y HandleType en SQL_HANDLE_DBC y devolvió SQL_PARAM_DATA_AVAILABLE. Se llamó a esta función antes de recuperar los datos para todos los parámetros transmitidos.

Se llamó a SQLBrowseConnect para ConnectionHandle y devolvió SQL_NEED_DATA. Se llamó a esta función antes de que se completara el proceso de exploración.
HY013 Error de administración de memoria No se pudo procesar la llamada de función porque no se pudo tener acceso a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja.
HY092 Identificador de atributo o opción no válido HandleType se estableció en SQL_HANDLE_ENV o SQL_HANDLE_DESC.
HY117 La conexión se suspende debido al estado de transacción desconocido. Solo se permiten funciones de desconexión y de solo lectura. (DM) Para obtener más información sobre el estado suspendido, vea Función SQLEndTran.
HYT01 Se ha agotado el tiempo de espera de la conexión. El período de tiempo de espera de conexión expiró antes de que el origen de datos responda a la solicitud. El período de tiempo de espera de conexión se establece a través de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 El controlador no admite esta función (DM) El controlador asociado con el identificador no admite la función .

Si se llama a SQLCancelHandle con HandleType establecido en SQL_HANDLE_STMT, puede devolver cualquier SQLSTATE que pueda devolver la función SQLCancel.

Comentarios

Esta función es similar a SQLCancel , pero puede tomar un identificador de conexión o instrucción como parámetro en lugar de solo un identificador de instrucción. El Administrador de controladores asigna una llamada a SQLCancelHandle a una llamada a SQLCancel cuando HandleType está SQL_HANDLE_STMT. Esto permite que las aplicaciones usen SQLCancelHandle para cancelar las operaciones de instrucciones aunque el controlador no implemente SQLCancelHandle.

Para obtener más información sobre cómo cancelar una operación de instrucción, vea Función SQLCancel.

Si no hay ninguna operación en curso en Controlar la llamada a SQLCancelHandle no tiene ningún efecto.

SQLCancelHandle en un identificador de conexión puede cancelar los siguientes tipos de procesamiento:

  • Función que se ejecuta de forma asincrónica en la conexión.

  • Una función que se ejecuta en el identificador de conexión en otro subproceso.

Cuando se llama a SQLCancelHandle para cancelar una función que se ejecuta de forma asincrónica en una conexión, los registros de diagnóstico publicados por SQLCancelHandle se anexan a los devueltos por la operación que se está cancelando; SQLCancelHandle no devuelve registros de diagnóstico, sin embargo, al cancelar una función que se ejecuta en una conexión en otro subproceso.

El uso de SQLCancelHandle para cancelar SQLEndTran puede poner la conexión en estado suspendido. Para obtener más información sobre el estado suspendido, vea Función SQLEndTran.

Nota

Para obtener información sobre cómo usar SQLCancelHandle en una aplicación que se implementará en un sistema operativo Windows anterior a Windows 7, vea Matriz de compatibilidad.

Si una función devuelve SQL_STILL_EXECUTING, una aplicación puede llamar a SQLCancelHandle para cancelar la operación. Si la solicitud de cancelación se realiza correctamente, SQLCancelHandle devuelve SQL_SUCCESS. Esto no significa que se canceló la función original; indica que se procesó la solicitud de cancelación. El controlador y el origen de datos determinan cuándo o si se cancela la operación. La aplicación debe seguir llamando a la función original hasta que no se SQL_STILL_EXECUTING el código de retorno. Si se canceló la función original, el código de retorno se SQL_ERROR y SQLSTATE HY008 (operación cancelada). Si la función original completó su procesamiento normal (no se canceló), el código de retorno se SQL_SUCCESS o SQL_SUCCESS_WITH_INFO, o SQL_ERROR y un SQLSTATE distinto de HY008 (operación cancelada), si se produjo un error en la función original.

Cancelación de funciones que se ejecutan en otro subproceso

En una aplicación multiproceso, la aplicación puede cancelar una operación que se ejecuta en otro subproceso. Para cancelar la operación, la aplicación llama a SQLCancelHandle con el identificador usado por la función, pero en un subproceso diferente. El controlador y el sistema operativo determinan cómo se cancela la operación. El código de retorno SQLCancelHandle indica si el controlador procesó la solicitud, devolviendo SQL_SUCCESS o SQL_ERROR (no se devuelve información de diagnóstico). Si se cancela el procesamiento en la función original, la función original devuelve SQL_ERROR y SQLSTATE HY008 (operación cancelada).

Si se ejecuta una función cuando se llama a SQLCancelHandle en otro subproceso para cancelar la función, es posible que la función se realice correctamente y devuelva SQL_SUCCESS antes de que la cancelación pueda surtir efecto. Una llamada a SQLCancelHandle no tiene ningún efecto si la operación se completó antes de que SQLCancelHandle pudiera cancelar la operación.

Para información acerca de Vea
Cancelar una función que se ejecuta de forma asincrónica en un identificador de instrucción, cancelar una función en una instrucción que necesita datos o cancelar una función que se ejecuta en una instrucción en otro subproceso. Función SQLCancel

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC
Ejecución asincrónica (método de sondeo)