Función SQLCancel
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 instrucciones.
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 llamando 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 funciones | (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 del 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 las funciones de desconexión y 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 respondiera 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 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, los registros de diagnóstico publicados por la función que se cancelan se borran 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
Después de que una aplicación llame 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 haya cancelado realmente; indica que la solicitud de cancelación se ha procesado. 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 el código devuelto no sea SQL_STILL_EXECUTING. Si la función se canceló correctamente, el código de retorno es 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 VALOR 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 a 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 los datos se hayan enviado 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 llamar a SQLExecute o SQLExecDirect de nuevo. Para obtener más información, vea SQLBindParameter.
Después de que SQLBulkOperations o SQLSetPos devuelva SQL_NEED_DATA y antes de enviar los 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 usó la función de destino, pero en otro subproceso. 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 asume 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.
Funciones relacionadas
| Para obtener información sobre | 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 siguiente parámetro 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 |