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.

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.

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

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC