The Background Processor

In OpenInsight version 9.2 and above, there is now the ability to send requests from within OpenInsight to a "background processor" which can execute these requests, leaving the current OpenInsight instance available for additional processing. This functionality can be used either when running in the normal "GUI" OpenInsight front end, or when running through one of the non-GUI interfaces (including CTO, O4W, OECGI4, etc.). When running from a non-GUI interface, this functionality is especially useful, as it allows the non-GUI OEngine to execute tasks that require a Windows interface (for example, generating a PDF).

The Background Processor can be run in either of two ways:

1. Invoked on an "ad hoc" basis, generating a new OpenInsight instance for each request;

2. Managed via a "queue manager"

In order to use these functions, OpenInsight must be configured to allow background processing. This is done by creating and configuring a record in the SYSENV table called CFG_AUTOEXEC. The CFG_AUTOEXEC record must exist, and should have 2 fields. Field one contains the name of the routine to call when this OpenInsight instance has been invoked to handle a background task; this should be set to RTI_TASKMANAGER. Field 2 contains the maximum number of OpenInsight instances that can be "spawned" to handle the background requests.

Note that the CFG_AUTOEXEC record can be configured on a per-application, per-user, and/or per-application-and-user basis. OpenInsight will first look for an entry named CFG_AUTOEXEC*<app>*<user>, where <app> and <user> is the application name and user name, respectively, of the current application and user. If not found, the system then looks for an entry named CFG_AUTOEXEC**<user>; if this is not found, then the system looks for an entry named CFG_AUTOEXEC*<app>; if this is not found, the system-wide CFG_AUTOEXEC is read and used.

To have the background process request executed immediately, without running a queue manager, a stored procedure can call the RTI_TASK_SUBMIT function:

DECLARE FUNCTION RTI_TASK_SUBMIT

taskID = RTI_TASK_SUBMIT("", PROC_NAME, PARAM1, PARAM2, PARAM3…)

The first parameter specifies the type of call; if set to null, this is an "immediate" request (without requiring a queue manager). The second parameter is the name of the function you wish the background process to invoke. The third and additional parameters are any parameters you wish to pass into the function that the background process will invoke.

RTI_TASK_SUBMIT will return a unique "task id" that your routine can use to check the status, and retrieve the results, of background processing. This value should be greater than 0; a 0 or negative number indicates an error in your request, or in processing.

To check the status of the request, a stored procedure can invoke the RTI_TASK_STATUS function:

DECLARE FUNCTION RTI_TASK_STATUS

status = RTI_TASK_STATUS(taskID, results)

The first parameter of the RTI_TASK_STATUS call should be the "task id" returned by the RTI_TASK_SUBMIT function. RTI_TASK_STATUS will return a status code, and - if the submitted task has been completed - will fill the "results" parameter with any results returned by the submitted task. Values for the status parameter include 'COMPLETED', 'ERROR', 'PROCESSING', 'SUBMITTED', and 'IMMEDIATE' (though only the values COMPLETED and ERROR should be checked).

When the task returns COMPLETED or ERROR, it is removed from the background processing system, so no additional cleanup is required. Note that a task may be deleted from the system two days after it has completed, even if its results are not checked and retrieved with RTI_TASK_STATUS.

For a more "managed" background process, a queue manager can be started up; this queue manager can then dispatch requests to some defined number of other OpenInsight instances (as opposed to an 'ad hoc' invocation, where any number of OpenInsight instances may be created to handle the requests).

The queue manager can be started via the RTI_TASK_STARTUP command:

DECLARE SUBROUTINE RTI_TASK_STARTUP

RTI_TASK_STARTUP()

This command creates an OpenInsight instance and instructs it to operate as the Queue Manager; it then waits for background requests to be submitted. Note that if the maximum number of queues (as defined in the CFG_AUTOEXEC record) is non-zero, the queue manager will create up to that number of OpenInsight instances to handle the requests; if the maximum number of queues parameter is 0, then the queue manager will execute each request itself, without "spawning" any additional OpenInsight instances.

Submitting a background task is similar to the 'ad-hoc' method:

DECLARE FUNCTION RTI_TASK_SUBMIT

taskID = RTI_TASK_SUBMIT("0", PROC_NAME, PARAM1, PARAM2, PARAM3…)

Note that the first parameter is now set to "0"; this instructs the system to place this in the background queue for processing.

It is also possible to call RTI_TASK_SUBMIT and have _it_ start up the queue manager, if needed; specify a "1" as the first parameter to RTI_TASK_SUBMIT to combine these two functions.

Checking for results is the same as when working in the "ad-hoc" system; call RTI_TASK_STATUS with the specific "task id" to examine the status of your request.

If you wish to shut down the queue manager, simply invoke the RTI_TASK_SHUTDOWN command:

DECLARE SUBROUTINE RTI_TASK_SHUTDOWN

RTI_TASK_SHUTDOWN()

This will instruct the queue manager to terminate, leaving any pending items in the queue for later processing.