| Description | RTI_TASK_SCHEDULER creates a Windows scheduler entry to launch your task at the desired time. RTI_TASK_SCHEDULER can also modify or delete existing tasks. The RTI_TASK_SCHEDULER is member of the RTI_TASK_xxx programs. Use RTI_TASK_SCHEDULER when you need to create tasks triggered by time, independent of other programs, for example as nightly processing and background indexing. RTI_TASK_SCHEDULER can configure one-time application parameters such as the details needed to connect to an Engine Server and configure per-task information such as the program name, parameters and start time. [See RTI_TASK_SUBMIT to create background tasks launched by another program, such as a long running report.] |
| Parameters | The function has the following parameters: | Parameter | Description | | tasktype | There are three possible values: | Value | Description | | ADD | Adds the specified task to the task record and the windows task scheduler. Syntax: Rslt = RTI_TASK_SCHEDULER("ADD",<taskname>,<taskdetails>{,<overwriteflag>}) If the specified taskname already exists, and the overwriteflag is not set to "1", then the task is not added and -1 is returned in rslt. | | QUERY | Returns the entire contents of the task schedule record for the current application or the task schedule record for the specific task as defined in the current application. Syntax: Rslt = RTI_TASK_SCHEDULER("QUERY") Returns the entire contents of the task schedule record for the current application Syntax: Rslt =RTI_TASK_SCHEDULER("QUERY", <taskname>) Returns the task schedule record for the specific task as defined in the current application. | | DELETE | Deletes the specified task from the task record and the Windows Task Scheduler. Syntax: Rslt = RTI_TASK_SCHEDULER("DELETE",<taskname>) Returns 1 if the task is found, 0 otherwise | | | taskname | The name of the task to be added, queried or deleted. | | taskdetails | An @FM delimited array containing the information to place into the Task Scheduler for the specific job. Used with the ADD tasktype only. | | overwriteflag | A boolean value to determine whether the named Task should be overwritten on an ADD Tasktype. | |
| | The Task Detail Record is outlined below. This is used with the ADD Tasktype. | Field # | Description | | <1> | engineserver: user name (optional) | | <2> | engineserver: password (optional) | | <3> | engineserver: URL (optional) | | <4> | engineserver: port (optional) | | <5> | Task Name (same as passed-in parameter #2) | | <6> | Stored Procedure to invoke (optional) | | <7> | Command to pass | | <8> | starting date (in internal format) | | <9> | ending date (in internal format) (optional) | | <10> | schedule type (see below) | | <11> | frequency (optional - only specified for schedule type RUN_TYPE_EVERY) (see below) | | <12> | starting time (in internal format) | | <13> | idle time (minutes) (optional - only specified for schedule type RUN_TYPE_IDLE)(see below) | | <14> | windows user (optional) | | <15> | windows pwd (optional) | Fields 1-4 specify information used for the connection to the engine server, and if specified will REPLACE the values in the current task schedule record. Fields 5-15 are always appended to the end of the current task schedule record fields 5-15 (which are associated multivalues). Schedule type is one of the following codes: Equ RUN_TYPE_STARTUP$ To 0 - run when the Windows operating system starts up Equ RUN_TYPE_LOGON$ To 1 - run when the user logs on Equ RUN_TYPE_IDLE$ To 2 - run when the Windows operating system is idle (must specify idle time) Equ RUN_TYPE_ONCE$ To 3 - run only 1 time Equ RUN_TYPE_EVERY$ To 4 - run at scheduled frequency For RUN_TYPE_EVERY, the frequency must be specified. It takes the form of <n><space><interval> - for example, "5 MINUTE(S) ". The valid interval choices are: MINUTE(S) HOUR(S) DAY(S) WEEK(S) MONTH(S) Notes: Application specific information is stored in the SYSENV table. The SYSTASKS table holds task specific information. The Windows scheduled task is created on the machine where you run the program. The scheduled task calls OERUN.EXE, which in turn calls the Oengineserver to run the task, so you must have an oengineserver running. RTI_TASK_SHUTDOWN | Description | RTI_TASK_SHUTDOWN stops the polling service that processes background tasks. It is a member of the RTI_TASK_xxx programs. | | Syntax | call RTI_TASK_SHUTDOWN() | | Parameters | None | | Returns | | | | | | | Notes: Use RTI_TASK_SHUTDOWN to terminate the background processing manager and any associated queues launched explicitly by the RTI_TASK_STARTUP command, or implicitly by the RTI_TASK_SUBMIT command. | RTI_TASK_STARTUP | Description | RTI_TASK_STARTUP starts a polling service to process background tasks. It is a member of the RTI_TASK_xxx programs. | | Syntax | Rslt = RTI_TASK_STARTUP(bStartPolling{, task_id}) | | Parameters | The function has the following parameters: | Parameter | Description | | bStartPolling | True(1) to launch an oinsight.exe process to poll the task queue for pending tasks and launch them. | | task_id | (Optional) The id of a specific task to launch. | | | Returns | | | | | | | Notes: RTI_TASK_STARTUP is a supporting routine, normally called by RTI_TASK_SUBMIT. Use RTI_TASK_STARTUP if you want to launch a task or start a poller yourself. The task will use the credentials of the current user. | RTI_TASK_STATUS | Description | RTI_TASK_STATUS returns the current status of a submitted background tasks, and its results (if the task is complete). It is a member of the RTI_TASK_xxx programs. | | Syntax | Rslt = RTI_TASK_STATUS(taskID, results) | | Parameters | The function has the following parameters: | Parameter | Description | | taskID | The task ID returned from the RTI_TASK_SUBMIT call | | results | The results generated by the background task, if it is completed. | | | Returns | The current status of the task. | | | | | | Notes: RTI_TASK_STATUS will return the current status of the requested task. Possible return values include "SUBMITTED" (the task has been placed in the queue but is not yet processed), "IMMEDIATE" (the task has been submitted for immediate processing but has not yet been processed), "PROCESSING" (the task is currently in process), "COMPLETED" (the task is complete), and "ERROR" (an error was encountered). If the task status is COMPLETED, the return value of the task (invoked as a function) will be returned in the "results" parameter; if the status is ERROR, the "results" parameter will contain additional error information. If the status is either COMPLETED or ERROR, the task entry will be removed after the RTI_TASK_STATUS call (so additional calls to RTI_TASK_STATUS with the same taskID will return an error). | RTI_TASK_SUBMIT | Description | RTI_TASK_SUBMIT creates and optionally launches a background task. It is a member of the RTI_TASK_xxx programs. Use RTI_TASK_SUBMIT to trigger a background task from a program. RTI_TASK_SUBMIT allows you to launch tasks which require the presentation server, for example OIPI reports. It can be configured to start up an additional OpenInsight for each requested task, or to maintain a "background queue" of OpenInsight invocations that can be used to process requests in the order they are submitted. [See RTI_TASK_SCHEDULER for the case where you to create a task triggered by time.] | | Syntax | Rslt = RTI_TASK_SUBMIT(callType, funcName {,<param1>} {,<param2>} {,<param10>}) | | Parameters | The function has the following parameters: | Parameter | Description | | callType | There are three possible values: | Value | Description | | Value | Description | | null | Launch immediately | | 0 | Add task to the queue | | 1 | Add to the queue, launch a poller to process the queue | | | funcName | The name of the fuction or subroutine to execute. | | taskdetails | An @FM delimited array containing the information to place into the Task Scheduler for the specific job. Used with the ADD tasktype only. | | {,<param1>} {,<param2>}... {,<param10>} | The arguments for the function. RTI_TASK_SUBMIT supports functions with up to ten arguments. | | | Returns | The "task ID" of the newly submitted task. The TaskID will be used to query the background processor about the status of the request, and retrieve any generated results, with the RTI_TASK_STATUS call | | | | | | RTI_TASK_SUBMIT uses the ShellExecute function to launch a new Oinsight.exe to execute the task. Unlike OERUN, which similarly runs background tasks via the engine server, RTI_TASK_SUBMIT uses oinsight.exe to support tasks which require the presentation server, such as OIPI reports. In immediate mode, the launched OInsight.exe will execute the requested task and terminate. In polling mode, the launched OInsight.exe will check to see if a "task manager" is currently running, and if it is not, it will remain running as the task manager, dispatching the requests to additional OInsight.exe instances. If a task manager is already running, the launched OInsight.exe will terminate, leaving the processing of the task to the already-running task manager. See RTI_TASKMANAGER for configuration information. RTI_TASK_SUBMIT can be called from any program, including other tasks or programs that are not in event context, such as INET and O4W routines. Launching OIPI reports and returning PDFS to web clients is a common use. | RTI_TASKMANAGER | Description | RTI_TASKMANAGER is a support routine that manages the processing of background tasks, possibly creating additional OInsight.exe instances to perform those tasks. It is a member of the RTI_TASK_xxx programs. | | Syntax | Rslt = RTI_TASKMANAGER(numberofqueues) | | Parameters | The function has the following parameters: | Parameter | Description | | Numberofqueues | The maximum number of OInsight.exe instances to launch to process tasks that have been queued. | | | Returns | | | | | | | Notes: The RTI_TASKMANAGER is a utility routine that is never directly invoked by the user; an instance of OpenInsight will automatically call the RTI_TASKMANAGER routine if it is running as the "background task manager". The number of queues (which controls the maximum number of OpenInsight instances the background task manager can create to process the tasks) is controlled by the configuration record CFG_AUTOEXEC in the SYSENV table. The configuration record should contain "RTI_TASKMANAGER" in field 1 (or field 1 may be left blank), and field 2 should contain the number of queues the background task manager should manage. The specific record used for the configuration will be either CFG_AUTOEXEC*<appid>*<user> (where <appid> is the name of the application, and <user> is the name of the user), or CFG_AUTOEXEC**<user>, or CFG_AUTOEXEC*<appid>, or CFG_AUTOEXEC; OpenInsight will use the most specific configuration record found. | |
