IIapi_cancel() Function—Cancel an Outstanding Query Statement
The IIapi_cancel() function causes a query statement started with IIapi_query() or an event retrieval started with IIapi_catchEvent() to complete its operations.
When IIapi_cancel() completes successfully, the query may not yet be canceled; it simply means that the server has received the cancellation request. Each canceled query receives a callback.
This function is different from IIapi_close(), which is used to end a query. The IIapi_close() function waits for the completion of the query, whereas IIapi_cancel() attempts to end it before it is completed.
Statement handle output from IIapi_query() and event handle output from IIapi_catchEvent() is available when the function returns, so queries can be canceled at anytime thereafter.
The following are possible results of the IIapi_cancel() function and their corresponding actions:
• Completes with status IIAPI_ST_SUCCESS-Cancel request has been issued but the server has not yet canceled the query. There is an outstanding OpenAPI request that will complete with status IIAPI_ST_FAILURE and error code E_AP0009_QUERY_CANCELLED, after which the statement handle can be closed using IIapi_close().
• Completes with status IIAPI_ST_WARNING-IIapi_cancel() has already been called for the statement handle and this call has been ignored; otherwise, same as IIAPI_ST_SUCCESS status above.
• Completes with status IIAPI_ST_FAILURE and error code E_AP0009_QUERY_CANCELLED-The query has been canceled and statement handle can be closed using IIapi_close().
• Completes with status IIAPI_ST_FAILURE and error code E_AP0008_QUERY_DONE-Query has completed processing and cannot be canceled. Statement handle can be closed using IIapi_close().
• Completes with status IIAPI_ST_FAILURE and error code E_AP0006_INVALID_SEQUENCE-Statement handle is in the process of being closed and no further actions are permitted.
This function has the following syntax:
II_VOID IIapi_cancel (IIAPI_CANCELPARM *cancelParm);
typedef struct _IIAPI_CANCELPARM
{
IIAPI_GENPARM cn_genParm;
II_PTR cn_stmtHandle;
} IIAPI_CANCELPARM;
This function has the following parameters:
cn_genParm
Type: input and delayed output
Specifies the generic parameters.
cn_stmtHandle
Type: input
Specifies the statement or event handle identifying the query to be canceled.