Purging and Archiving the QTRACS Database - OMPURGE

Purging and Archiving the QTRACS Database (OMPURGE)

Required Parameter Group:
(None)

API Overview:
The Purging and Archiving the QTRACS Database API (OMPURGE) supports the purging and archiving of the QTRACS database. This process is controlled via the purge configuration parameters that are defined by the System Administrator. These purge configuration parameters are available via the System Configuration option on the QTRACS Command Menu. The database purge is system-wide; individual files are not purged independently of other files. In other words, the same process purges the Message Database, the Position History, and the Driver Event History.

Normally, it is envisioned that the user shall specify that the purge shall automatically be run one or more days per week, or once at month end. Doing this shall cause QTRACS to establish an entry in the AS/400's job scheduler. OS400 shall be responsible for submitting the purge according to the parameters indicated by the user. The name of the 'scheduled job entry' is OMNIDATA (or whatever the name of the data library happens to be).

Alternately, the user may decide that he doesn't want the purge to run automatically at certain intervals. In this case, he may press F15 from within the Database Purge Parameters screen of the System Configuration UI. This has the effect of submitting the purge on demand.

Finally, the user may decide to invoke the purge by calling it from within a site-specific 'housekeeping' program that runs on a regular schedule. To do so, simply the call this API directly.

There are no run-time contingencies for the purge, and it may be executed while the QTRACS system is in use.

Purge Controlling Values
There are no parameters on the call to OMPURGE. The purge job retrieves all of its controlling parameters from a file that has been predefined by the system administrator. These parameters are defined in the Database Purge subsection from with the System Configuration option. These parameters consist of the following:

Days to Retain
These three parameters control how many days of position history, messages, and driver event history to retain. A purge date is calculated by taking the current date and subtracting the 'days to retain'. Any records that are older than their respective purge date will be deleted.

Archive Deleted Messages
This field controls whether the 'Position History Archiving' feature is enabled. Only the values *YES or *NO are accepted. While this feature is enabled, all purged message records will be archived.

Day(s) of Week to Run Purge
This field specifies the days of the week on which the purge will be run. These day(s) are stored in the job scheduler's entry as well as the QTRACS database and will be used to drive the scheduled purge. An 'X' must be placed in front of one or more days that the purge is to run. The selected day(s), in conjunction with the time field are used to define the purge's run time. The purge will run on the same selected day(s) and time each week unless *YES is selected in the 'Run Purge at Month End Only' field. In this case, the purge will run on the last day of each month. If 'Run Purge at Month End Only' field is set to *YES, then the user cannot select any days in this field. And visa versa, if any days are selected, the user must select *NO in the 'Run Purge at Month End Only' field.

Run Purge Month End Only
This field controls the month end purge processing option. If this field is set to *YES then the purge will run on the last day of every month only. Also, if this field is set to *YES, there cannot be any days selected in the 'Day(s) of the Week to Run Purge' field.

Time of Day to Run Purge
The time of day which the purge should be executed must also be specified.

Last Purge Date
This is the date and time of the last successful execution of OMPURGE.

Submitting the Purge for the First Time
The system administrator should define all of the parameters listed above via the Database Purge option from within the System Configuration option. This will create the Scheduled Job Entry named OMNIDATA (or whatever the name of the data library happens to be). The operating system will automatically submit this job depending on the purge run parameters entered.

If the purge is not configured as a Scheduled Job Entry, then it may be called from a custom external application as desired. Or, the purge may be requested at any time simply by pressing F15 from the purge configuration menu.

Effect
The execution of the purge job will remove records from the Message Database and the Position History Database. If the system is configured to archive the Message Database, then the purged messages will be copied to the Archive Message Database before being removed from the live Message Database.
The Archive Message Database, if activated, should be manually saved to backup media and cleared at regular intervals. This 'save and clear' of the Archive Message Database may be done while QTRACS is active. The only contingency is to ensure the purge itself is not currently executing.
The Archive Message Database consists of all physical files with name OMMZ*.