7. Using Repeat Queries with OpenAPI : Repeat Queries : How the Repeat Query Protocol Works
Share this page                  
How the Repeat Query Protocol Works
You must first define a repeat query for a given server connection. When a repeat query is defined, the server determines if another client has defined the repeat query previously. This is done through a unique repeat query ID that the application provides. If the repeat query has not been defined previously, the server builds a query plan for the repeat query. All subsequent attempts to define the repeat query for that server inherits the original query plan.
Once a repeat query has been defined, the application invokes (executes) the query. The repeat query can be invoked repeatedly once it has been defined, and subsequent definitions are not generally required. However, it is possible that a server will need to drop a query plan for a repeat query, and the application must be prepared for such an occurrence. If the server returns an indication that a repeat query is no longer defined, the application must redefine the query and redo the invocation that failed.
An OpenAPI application defines a repeat query by calling IIapi_query() with the query type set to IIAPI_QT_DEF_REPEAT_QUERY and the query text containing the statement to be repeatedly executed (not including the repeated keyword). A unique repeat query ID (see Repeat Query ID) is passed as a parameter using IIapi_setDescriptor() and IIapi_putParms(). If there are no errors processing the query, the application obtains a repeat query handle by calling IIapi_getQueryInfo(). The repeat query handle will be used to invoke the repeat query.
To invoke a repeat query, the application calls IIapi_query() with the query type set to IIAPI_QT_EXEC_REPEAT_QUERY and no query text. The repeat query handle returned by IIapi_getQueryInfo() when the query was defined is passed as a query parameter using IIapi_setDescriptor() and IIapi_putParms(). If an OpenAPI error code of E_AP0014_INVALID_REPEAT_ID is returned (or the IIAPI_GQF_UNKNOWN_REPEAT_QUERY flag is returned by IIapi_getQueryInfo()), the application must redefine and invoke the repeat query.