This chapter provides information on implementing repeat queries using OpenAPI, unique repeat query IDs, and the query parameter mechanism used for repeat queries.
|
|
|
Embedded SQL provides the ability to mark delete, insert, select, and update statements with the keyword repeated. Through a protocol hidden by the embedded preprocessor and implemented by the embedded runtime system, these queries are optimized in the server for repeated execution. The queries are shared among all clients running a given application.
OpenAPI also lets you use repeat queries, though not with the ease provided by embedded SQL. For an OpenAPI application to use repeat queries, it must adhere to the same protocol implemented in the embedded runtime system. This protocol is explained in the following paragraphs.
|
|
|
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 (described in 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.