Submitted Job Tracker

The Submitted Job Tracker is an IBM® i work management feature that tracks the lifecycle of submitted jobs for a user specified set of jobs queues.

The ADD_TRACKED_JOB_QUEUE procedure registers a job queue to be tracked by adding it to the Job Queue List (JQL). After a job queue has been registered, any jobs subsequently submitted to that job queue are tracked in a job tracking file. A user can use the information stored in the job tracking file to resubmit a job on the original node where the job was tracked or another node. The information in the job tracking file can help prepare for maintenance, recover from a node failure, or balance workload.

The job tracking file is a database file that keeps track of job submit parameters and job status for any jobs being tracked by Submitted Job Tracker. The job tracking files is named QSBMJOBTRK/QAMRDJTS¹ and can exist in SYSBAS or within an IASP.

Tracking job lifecycle events

To track job lifecycle events, Submitted Job Tracker uses the following work management exit points:

Change Job (QIBM_QWT_CHGJOB)
Job Notification (QIBM_QWT_JOBNOTIFY)
Submit Job (QIBM_QWT_SBMJOB)

See the details for how Submitted Job Tracker handles each lifecycle event below.

Submit Job (SBMJOB) command: When a job is submitted to a tracked job queue with SBMJOB, parameters that would be necessary to resubmit the job are stored in the job tracking file.
Change Job (CHGJOB) command or API (QWTCHGJB): When a tracked job is changed while it is on a job queue, the job tracking file is updated to reflect the changes.; When a tracked job is changed while it is active, the job tracking file is not updated.; If a tracked job is moved from an untracked job queue to one that is not tracked, then tracking ends for that job and no further updates are made to the job tracking file. However, the information for that job remains in the job tracking file until the job queue is no longer tracked or the job tracking file is cleared.; If a job is moved from an untracked job queue to one that is tracked, then the job remains not tracked.; Note: It is recommended to track all job queues involved in the lifecycle of a tracked job.
Transfer Job (TFRJOB) or Transfer Batch Job (TFRBCHJOB) command: Each time an active job is transferred to a tracked job queue, an additional entry is added to the job tracking file to represent the new routing step associated with that job. If the job queue for a routing step is not a tracked job queue, then no additional entry for that routing step is added to the job tracking file.; When the last routing step ends, all entries in the job tracking file for that job are updated to indicate the job end time. If the job queue for the last routing step is not a tracked job queue, then the job end time is not updated for any of the entries for that job in the job tracking file.; Note: It is recommended to track all job queues involved in the lifecycle of a tracked job.
Job starts: When a tracked job starts, the job tracking file is updated to indicate the job start time.
Job ends: When a tracked job ends, the job tracking file is updated to indicate the job end time and other completion details.; If a job is ended while it is on a tracked job queue that is not allocated to a subsystem, the job tracking file remains unchanged until the job queue is no longer tracked or the job tracking file is cleared.
Job schedule entries: Jobs that are scheduled to run at a future date or time using the Add Job Schedule Entry (ADDJOBSCDE) or Work with Job Schedule Entries (WRKJOBSCDE) commands are not tracked.

The job tracking file is updated asynchronously while tracked jobs encounter lifecycle events. Tracking information is gathered, processed, and stored in a job tracking file asynchronously by the Submitted Job Tracker job (QMRDBJNFY). Subsequently, tracking information in the job tracking file will always lag the real lifecycle event. The lag time should be small in most cases, but it is not zero. This means:

A job that is queued at the time of a node failure may not appear in the job tracking file.
A job that has started running at the time of node failure may not appear in the job tracking file or may be described in the job track file as still queued.
A job that has ended at the time of node failure may be described in the job tracking file as still queued or running.

Managing the Submitted Job Tracker

Displaying tracked job queues

The list of job queues that have been registered to be tracked is displayed using the TRACKED_JOB_QUEUES view.

Adding tracked job queues

Job queues are registered to be tracked using the ADD_TRACKED_JOB_QUEUE procedure.

Note: It is recommended to register all job queues allocated to a subsystem before starting the subsystem.

Removing tracked job queues

Job queues are removed from being tracked using the REMOVE_TRACKED_JOB_QUEUE procedure.

Displaying tracked jobs

Tracked jobs and their details are displayed using the TRACKED_JOB_INFO table function.

Clearing tracked jobs details

Tracked job information is eligible to be automatically removed from a job tracking file after the job has ended, the job tracking file has been updated with a job end time value, and the job retention period has elapsed. The job retention period is specified when a job queue is registered with the JQL. The Submitted Job Tracker job (QMRDBJNFY) periodically checks for tracked job information that is eligible to be removed and clears those entries.

All tracked job information for a particular job queue is removed from a job tracking file when that job queue is removed from the JQL.

There are several situations that may cause Submitted Job Tracker to not receive a notification that a job has ended and therefore the job end time in the job tracking file did not get updated. These entries must be manually cleared from the job tracking file. The following situations can cause a tracked job to get into this state:

A node has an unplanned outage. When the node is active again, information in the job tracking file about active jobs when the outage occurred will not have a job end time value set.
An IASP is varied off or is unavailable. While the IASP is unavailable, Submitted Job Tracker is unable to update the job tracking file. When it is varied on again, entries in the job tracking file may still exist for jobs that have ended but the job end time value is not set.
A job is changed or transferred from a tracked job queue to an untracked job queue. This causes tracking to end for that job but information about it remains in the job tracking file and the job end time value is not set.
A user registers a job queue to be tracked by adding it to the JQL after starting the subsystem where the jobs will run. This can prevent Submitted Job Tracker from receiving notifications when a job ends, which results in entries in the job tracking files not being properly updated with job end time values.
A user submits a job to a tracked job queue and the job is ended before the job queue is allocated to a subsystem. Submitted Job Tracker does not receive a notification from work management that the job has ended in this case, therefore the job end time value is not set for the job in the job tracking file.
The limit of eight data queues registered for the work management job notification exit point (QIBM_QWT_JOBNOTIFY) is exceeded. This may cause Submitted Job Tracker to not receive notifications when a job starts or ends, which results in entries in the job tracking file not being properly updated.

Tracked job information can be cleared manually using the CLEAR_TRACKED_JOB_INFO procedure.

Restoring Submitted Job Tracker data: The JQL, which is a database file named QSYS/QAMRDJQL, can be restored from save media. This will replace the existing list of tracked job queues with the list of tracked job queues from the save media. When the QAMRDJQL file is restored, each job queue on the restored list of tracked job queues is ensured to be properly registered with Submitted Job Tracker. If the restore causes a job queue to no longer be tracked, then the job tracking file will be cleared of entries for that job queue.; The job tracking file, which is a database file named QSBMJOBTRK/QAMRDJTS², cannot be restored from save media. If an attempt is made to restore this system object, it will not be restored and the existing object is left unchanged. If other objects are included in the restore request, they will be processed normally.

¹ For an IASP, the QAMRDJTS job tracking file exists in library QSJTnnnnn.

² For an IASP, the QAMRDJTS job tracking file exists in library QSJTnnnnn.