Función SQLCancel

  • Artículo

Conformidad
Versión introducida: Cumplimiento de estándares ODBC 1.0: ISO 92

Resumen
SQLCancel cancela el procesamiento en una instrucción .

Para cancelar el procesamiento en una conexión o instrucción, use la función SQLCancelHandle.

Sintaxis

  
SQLRETURN SQLCancel(  
     SQLHSTMT     StatementHandle);

Argumentos

StatementHandle
[Entrada] Identificador de instrucción.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnóstico

Cuando SQLCancel 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 StatementHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLCancel 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 (DM) Se llamó a una función de ejecución asincrónica para el identificador de conexión asociado a StatementHandle. Esta función asincrónica todavía se estaba ejecutando cuando se llamó a la función SQLCancel .

(DM) Error en la operación de cancelación porque hay una operación asincrónica en curso en un identificador de conexión asociado a StatementHandle.
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.
HY018 Solicitud de cancelación rechazada por el servidor El servidor rechazó la solicitud de cancelación.
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 a StatementHandle no admite la función .

Comentarios

SQLCancel puede cancelar los siguientes tipos de procesamiento en una instrucción :

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

  • Función en una instrucción que necesita datos.

  • Función que se ejecuta en la instrucción en otro subproceso.

En ODBC 2. x, si una aplicación llama a SQLCancel cuando no se realiza ningún procesamiento en la instrucción , SQLCancel tiene el mismo efecto que SQLFreeStmt con la opción SQL_CLOSE; este comportamiento solo se define para la integridad y las aplicaciones deben llamar a SQLFreeStmt o SQLCloseCursor para cerrar los cursores.

Cuando se llama a SQLCancel para cancelar una función que se ejecuta de forma asincrónica en una instrucción o una función en una instrucción que necesita datos, se borran los registros de diagnóstico publicados por la función que se está cancelando y SQLCancel publica sus propios registros de diagnóstico; Cuando se llama a SQLCancel para cancelar una función que se ejecuta en una instrucción en otro subproceso, no borra los registros de diagnóstico de la función cancelada y no publica sus propios registros de diagnóstico.

Cancelación del procesamiento asincrónico

Una vez que una aplicación llama a una función de forma asincrónica, llama a la función repetidamente para determinar si ha terminado de procesarse. Si la función sigue procesando, devuelve SQL_STILL_EXECUTING. Si la función ha terminado de procesarse, devuelve un código diferente.

Después de cualquier llamada a la función que devuelve SQL_STILL_EXECUTING, una aplicación puede llamar a SQLCancel para cancelar la función. Si la solicitud de cancelación se realiza correctamente, el controlador devuelve SQL_SUCCESS. Este mensaje no indica que la función se canceló realmente; indica que se procesó la solicitud de cancelación. Cuando o si la función se cancela realmente es dependiente del controlador y dependiente del origen de datos. La aplicación debe seguir llamando a la función original hasta que no se SQL_STILL_EXECUTING el código de retorno. Si la función se canceló correctamente, el código de retorno se SQL_ERROR y SQLSTATE HY008 (operación cancelada). Si la función completó su procesamiento normal, el código de retorno se SQL_SUCCESS o SQL_SUCCESS_WITH_INFO si la función se realizó correctamente o SQL_ERROR y un SQLSTATE distinto de HY008 (operación cancelada) si se produjo un error en la función.

Nota

En ODBC 3.5, una llamada a SQLCancel cuando no se realiza ningún procesamiento en la instrucción no se trata como SQLFreeStmt con la opción SQL_CLOSE, pero no tiene ningún efecto. Para cerrar un cursor, una aplicación debe llamar a SQLCloseCursor, no SQLCancel.

Para obtener más información sobre el procesamiento asincrónico, vea Ejecución asincrónica.

Cancelación de funciones que necesitan datos

Después de que SQLExecute o SQLExecDirect devuelva SQL_NEED_DATA y antes de que se hayan enviado datos para todos los parámetros de datos en ejecución, una aplicación puede llamar a SQLCancel para cancelar la ejecución de la instrucción. Una vez cancelada la instrucción, la aplicación puede volver a llamar a SQLExecute o SQLExecDirect . Para obtener más información, vea SQLBindParameter.

Después de que SQLBulkOperations o SQLSetPos devuelva SQL_NEED_DATA y antes de que se hayan enviado datos para todas las columnas de datos en ejecución, una aplicación puede llamar a SQLCancel para cancelar la operación. Una vez cancelada la operación, la aplicación puede llamar a SQLBulkOperations o SQLSetPos de nuevo; la cancelación no afecta al estado del cursor ni a la posición actual del cursor. Para obtener más información, vea SQLBulkOperations o SQLSetPos.

Cancelación de funciones que se ejecutan en otro subproceso

En una aplicación multiproceso, la aplicación puede cancelar una función que se ejecuta en otro subproceso. Para cancelar la función, la aplicación llama a SQLCancel con el mismo identificador de instrucción que usa la función de destino, pero en un subproceso diferente. La forma en que se cancela la función depende del controlador y del sistema operativo. Como en la cancelación de una función que se ejecuta de forma asincrónica, el código de retorno de SQLCancel indica solo si el controlador procesó la solicitud correctamente. Solo se pueden devolver SQL_SUCCESS o SQL_ERROR; no se devuelve información de diagnóstico. Si se cancela la función original, devuelve SQL_ERROR y SQLSTATE HY008 (operación cancelada).

Si se ejecuta una instrucción SQL cuando se llama a SQLCancel en otro subproceso para cancelar la ejecución de la instrucción, es posible que la ejecución se realice correctamente y devuelva SQL_SUCCESS mientras que la cancelación también se realiza correctamente. En este caso, el Administrador de controladores supone que el cursor abierto por la ejecución de la instrucción está cerrado por la cancelación, por lo que la aplicación no podrá usar el cursor.

Para obtener más información sobre el subproceso, consulte Multithreading.

Para información acerca de Vea
Enlace de un búfer a un parámetro Función SQLBindParameter
Realización de operaciones de inserción o actualización masivas Función SQLBulkOperations
Cancela una función que se ejecuta de forma asincrónica en un identificador de conexión, además de la funcionalidad de SQLCancel. Función SQLCancelHandle
Ejecución de una instrucción SQL Función SQLExecDirect
Ejecución de una instrucción SQL preparada Función SQLExecute
Liberar un identificador de instrucción SQLFreeStmt
Obtener un campo de un registro de diagnóstico o un campo del encabezado de diagnóstico Función SQLGetDiagField
Obtención de varios campos de una estructura de datos de diagnóstico Función SQLGetDiagRec
Devolver el parámetro siguiente para enviar datos Función SQLParamData
Envío de datos de parámetros en tiempo de ejecución Función SQLPutData
Colocación del cursor en un conjunto de filas, actualización de datos en el conjunto de filas o actualización o eliminación de datos en el conjunto de resultados Función SQLSetPos

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC