2. PJS System Overview
The Personal Job Scheduler (PJS) is a job scheduling system that enables you to schedule your own batch jobs. This chapter introduces PJS components and concepts.
The following subsections briefly describe the types of data PJS accepts and how PJS software components process that data.
PJS keeps most of its information in a system data set called the PJS Request Queue. When you issue a PJS/TSO command or use the PJS/ISPF interface, the TSO commands and ISPF dialogs access the PJS Request Queue. Information can be added, modified, deleted, or listed.
Most PJS information is kept in three PJS Request Queue record types:
· Job Request Records contain information about jobs and job submission.
· Calendar Records contain information about PJS calendars, which can be specified by job requests.
· Event Records contain information about the events specified in the Job Request Records.
You can safely ignore the structure of these records.
PJS can submit a job from your data set, which is called a JCL data set, or from the PJS JCL Spool. The PJS JCL Spool is an internal data set that can contain copies of the jobs in your JCL data sets.
A user who has update access to the JCL data set cannot modify the job JCL kept on the PJS JCL Spool. A job placed on the PJS JCL Spool is protected from any user who isn't authorized to update the job request.
The PJS JCL Spool is an optional feature. Your site can disable it, it can require that you use it, or it can give you a choice.
PJS/TSO commands can create, modify, list, and delete job requests, calendars, and events. You can issue PJS/TSO commands at the READY prompt, or anywhere else TSO commands are issued. These commands can be used in TSO CLISTs or REXX EXECs to further automate PJS updates.
Detailed information on PJS/TSO commands is contained in Chapter 4.
PJS/ISPF panels replicate the PJS/TSO commands, but the panels are much friendlier. In addition to a simple, menu‑driven panel system, the PJS/ISPF interface provides a tutorial, context‑sensitive help panels, and field‑level prompts.
Detailed information on PJS/TSO commands is contained in Chapter 4.
The PJS System Task monitors the contents of the PJS Request Queue, takes care of events, keeps track of when each job request is to be submitted, submits the job for execution, and handles processing errors. The PJS System Task should run whenever the system runs: the system operator should start the PJS System Task at IPL time and should only stop the System Task during system maintenance.
Detailed information on the PJS System Task is contained in Section 2.6.
Because PJS can keep records for many users on a PJS Request Queue, PJS must be able to identify who owns each record. PJS associates an owner‑ID with each record on the PJS Request Queue.
In most cases, the owner‑ID is just the TSO user‑ID of the person who added the record. However, if a record is associated with more than one owner, a site can allow an owner‑ID to be a group‑ID, a system‑ID, or some arbitrary value assigned by the Site Administrator.
Detailed information on how to specify an owner‑ID is contained in Section 3.1.
When you tell PJS you want a job to run at a later time, you have issued a job request to PJS. Among other things, you tell PJS the name of the data set that contains the job, the date and time to submit the job, how often you want the job submitted, and any events on which the job depends. PJS puts valid job requests on the PJS Request Queue.
This following subsections briefly the options you can specify in a job request.
Each job request placed on the PJS Request Queue is assigned a unique request‑ID. The request‑ID consists of an owner‑ID and a request number, and is usually formatted as owner‑ID.req‑number. The request number is a number PJS assigns when the job request is added to the PJS Request Queue.
Detailed information on how to specify a request‑ID is contained in Section 3.2.
Each job request has an associated status:
WAIT means the job request is either waiting for the next date and time of job submission, or is waiting for all of its job request events to be posted.
COMPLETE means that all job request processing has been completed. The last date and time for job submission is past.
ERROR means that the PJS System Task encountered an error as it processed the job. The PJS System Task cannot process the job request until the status is changed.
DISABLED means that the job request has been disabled by the user. The PJS System Task cannot process the job request until the status is changed.
SUBMIT means that the PJS System Task is submitting the job. After job submission is complete, the job request is placed in WAIT, COMPLETE, or ERROR status.
The PJS System Task assigns job request status. You can set or change job request status with PJS/TSO command parameters, or equivalent PJS/ISPF panels.
You must specify a JCL data set for each job request. This data set contains the job you want PJS to submit for execution. PJS can submit a job from the JCL data or from the PJS JCL Spool.
2.3.4 Job Submission Date and Time
Each job request maintains several dates and times to manage job submission. You will enter some of these values, and some of these values are only maintained by PJS.
2.3.4.1 Start Date and Start Time
You will enter a Start Date and a Start Time. These values define the first date and time on which you want PJS to submit the job. Every job request must have a Start Date and a Start Time.
If you specify a frequency option that conflicts with your Start Date, PJS first submits the job on the next available and valid date. For example, if your Start Date is a Monday, but you've specified that the job is only submitted on Tuesdays, PJS begins to submit the job on the first Tuesday after your Start Date.
You can enter an End Date and an End Time to define the last date and time on which you want PJS to submit the job. If you don't specify these values, a job you want submitted periodically, for example, every week, can be submitted forever.
If you specify a frequency option that conflicts with your End Date, PJS last submits the job on the nearest previous and valid date. For example, if your End Date is a Wednesday, but you've specified that the job is only submitted on Tuesday, PJS stops submitting the job on the Tuesday before your End Date.
2.3.4.3 Next Run Date and Time
The Next Run Date and Time is the next scheduled date and time on which PJS can submit the job. PJS calculates this value based on the Start Date and Start Time, how often you want PJS to submit the job, and the time at which PJS performs this calculation.
Unposted events can delay job submission. More information on events is contained in Section 2.5.
2.3.4.4 Last Run Date and Time
The Last Run Date and Time is the last date and time on which PJS submitted the job. This is the actual date and time of submission, which is not always the scheduled date and time of submission.
Job requests cannot always be processed exactly at the specified run time. A job can be submitted late for several reasons:
· Normal system processing loads can cause a delay.
· The act of job submission can take time.
· Your system may be shut down for maintenance.
· Your site may call a halt to job submission for a variety of reasons.
· A job can be delayed until all of its job request events have been posted.
The first two factors are common, and usually delay PJS job submission by no more than a few minutes. In most cases, a short delay in job submission is not a problem. In some cases, however, submitting a job at the wrong time can cause serious problems.
For example, suppose you want PJS to submit a long‑running batch update that enqueues a data set, and suppose that the data set must be available during the day. PJS can schedule the job to be submitted after normal working hours. If, however, system problems cause PJS to be down for an extended period of time, and if the job is submitted late, the job may not finish execution before the data set is needed. One way to remedy this problem is to specify a Submit Window.
A Submit Window sets a deadline for job submission. If your job is not submitted before the Submit Window expires, you can tell PJS to take one of the following actions:
DISABLE places the job request in DISABLED status.
ERROR places the job request in ERROR status.
SKIP causes PJS to behave as if the job was submitted. PJS resets all job request events and, if the job is to be submitted more than once, calculates the Next Run Date and Time.
PJS provides several scheduling options, called frequency options, that tell PJS how often to submit the job:
· A one‑time job is submitted only once, at the Start Date and Start Time you specify. After the job is submitted, the job request is placed in COMPLETE status.
· A periodic frequency specifies a regular interval between job submissions. You can choose from MINUTES, HOURS, DAYS, WEEKS, MONTHS, or YEARS. You can specify a periodic frequency as small as 1 minute or as large as 99 years.
· A day‑of‑week frequency tells PJS to submit the job on specified days of the week. You can specify any combination of days.
· The end‑of‑month frequency tells PJS to submit the job every month on the last day of the month or some number of days before the last day of the month. Because of February, you cannot use this option to submit a job more than 27 days before the end of any month.
· The calendar frequency tells PJS to submit the job on the dates you have selected on a PJS calendar. You must define at least one calendar before you specify a calendar as a frequency option.
More information on calendars is contained in Section 2.4.
If the system is down when the job is supposed to run, the PJS System Task will try to submit the job after the system is restarted. If the system is down for an extended period of time, a number of planned job submissions may be skipped. The number depends on the frequency option.
In addition to the date and time options mentioned above, you can control job submission with events. An event can be used to delay job submission until some outside condition is satisfied. Events are often used to control the submission of dependent jobs.
More information on events and job request events is contained in Section 2.5.
You can use PJS calendars to specify arbitrary sets of dates for job submission. For example, you can select the second Monday of each month, select the set of national and state holidays, or select every day except for company‑defined holidays.
You must assign a unique calendar‑ID to each calendar you place on the PJS Request Queue. The calendar‑ID consists of an owner‑ID and a calendar name, and is usually formatted as owner‑ID.cal‑name.
Detailed information on how to specify a calendar‑ID is contained in Section 3.3.
PJS events enable you to schedule jobs based on circumstances other than the next date and time of job submission. An event can be used to delay job submission until some outside condition is satisfied. Events are often used to control the submission of dependent jobs.
PJS events are automatically created and deleted. An event is created when it is specified in a job request. That same event can be specified in any number of job requests. If the event is not specified in any job request, the PJS Queue Maintenance Utility, which is run periodically by the system operator, will delete the event from the PJS Request Queue.
You must assign a unique event‑ID to each event you place on the PJS Request Queue. The event‑ID consists of an owner‑ID and an event name, and is usually formatted as owner‑ID.event‑name.
Detailed information on how to specify an event‑ID is contained in Section 3.4.
2.5.2 Events and Job Request Events
PJS keeps event information in two different places:
· Each unique event you specify in a job request command has a record created for it in the PJS Request Queue. This record is called an event record. An event record refers to an event that can be specified in many job requests.
· Each job request that specifies events contains information about each event. The information is contained in the job request record and is called a job request event. A job request event is specific to the job request in which it is specified.
When you specify a new, unique event, PJS will create an event record and put a job request event in the job request. When you specify the same event in other job requests, PJS puts a job request event in the job request, but does not create a new event. Although events and job request events are closely related, you can treat job request events as independent entities.
The PJS System Task only uses and event record to post or reset the corresponding job request events in all of the job requests that specify the event. When an event record is posted or reset, PJS puts the event record in POST PENDING or RESET PENDING status. The PJS System Task then posts or resets all of the corresponding job request events. After the job request events are posted or reset, the event record returns to its normal state.
When the PJS System Task checks to see if a job request is ready for submission, it checks the job request events, not the event record. If all of the job request events are posted, PJS submits the job. After submission, all of the job request's job request events are reset. Only the job request events for the submitted job request are reset; other job requests that specify the same event are not affected.
2.5.3 How to Post Events or Job Request Events
When you tell PJS that the outside condition associated with the event is satisfied, you post the event. To post an event, you can use one of the following methods:
· To post a PJS event from a batch job, you can add a step to the job:
//stepname EXEC PGM=PJSPOST,PARM='owner-id.event-name'
where:
stepname is any valid stepname.
owner‑ID is the owner-ID of the event to be posted. You must specify this value.
event‑name is the event name of the event to be posted.
For compatibility with release 2.0, the program name PJSEVENT can be used as an alias of PJSPOST. PJSPOST is the recommended program name.
· You can use the PJS/TSO PJEVPOST command or the PJS/ISPF Post Event Panel.
· You can use a site‑created MVS System Exit.
If you want to post job request events in a single job request, you can use PJS/TSO job request commands or PJS/ISPF job request panels. The corresponding event record and corresponding job request events in other job requests are not posted.
2.5.4 Preposted and Non‑Preposted Events
By default, a job request event is posted any time the event record is posted, without regard to the scheduled run time of the job request. Job request events can be posted far in advance of the Next Run Date and Time. This is called preposting.
In some cases, you may not want to post a job request event until after the Next Run Date and Time is reached. If the PJS System Task tries to post the job request event before the scheduled run time, the job request event is not posted. The job will be run some time after its scheduled run time, whenever all of its job request events are posted.
2.5.5 How to Reset Events or Job Request Events
When you remove the posting from an event, you reset the event. In most cases, the only reason to reset an event is to remove the posting from events and job request events that should not have been posted. To reset an event, you can use one of the following methods:
· To reset a PJS event from a batch job, you can add a step to the job:
//stepname EXEC PGM=PJSRESET,PARM='owner-id.event-name'
where:
stepname is any valid stepname.
owner‑ID is the owner-ID of the event to be reset. You must specify this value.
event‑name is the event name of the event to be reset.
· You can use the PJS/TSO PJEVREST command or the PJS/ISPF Reset Event Panel.
If you want to reset job request events in a single job request, you can modify the job request.
2.6 PJS System Task Process Summary
The PJS System Task manages the PJS Request Queue and job submission.
The following diagram shows how PJS handles your job requests:
|
|
|
Figure 1. System Flow Diagram |
To schedule a job, you should do the following:
1. Put the JCL for job you want to schedule into a data set.
2. Use the PJS ISPF panels or the PJS TSO commands to add the job to PJS.
3. The PJS ISPF panels or TSO commands will add the Job Request to the PJS Request Queue.
4. If you specified the Save JCL option on your Job Request, the PJS ISPF panels or TSO commands will copy your JCL from your JCL dataset to the PJS JCL Spool.
5. PJS ISPF panels and TSO commands are also available to query the status of your Job Requests. ISPF panels and TSO commands are also be used to modify or delete existing Job Requests, and to create, modify, and delete PJS Calendars, and to post or reset PJS Events.
About once a minute, the PJS System Task checks the PJS Request Queue for any new or modified Job Requests, or for any posted or reset Events.
6. First, if any posted or reset Events are found, the related Job Request Events may be posted or reset. For each related Job Request Event:
· If the Job Request Event can be ‘preposted’, it will be posted even if posting occurs before the Next Run Date and Time.
· If the Job Request Event cannot be ‘preposted’, and it will be posted only if the Next Run Date and Time for the Job Request has been reached. Otherwise the Job Request Event will not be posted.
· If the Event is reset, every related Job Request Event is reset. The ‘prepost’ attribute does not affect this case.
7. Next, the PJS System Task checks the PJS Request Queue for Job Requests that are ready to be submitted. For each Job Request that is ready to be submitted, the System Task uses the following procedure:
· The PJS System Task retrieves the PJS job request record from the PJS Request Queue. The status of the Job Request is changed to SUBMIT to lock the Job Request and prevent anyone from updating the Job Request while it is being submitted.
· The Next Run Date and Time is checked against the job request's Submit Window and the current system date and time. If Submit Window has expired the Job Request will be either rescheduled or set to the ERROR status. Otherwise processing continues.
8. The JCL for the job is retrieved from the user’s JCL Dataset or PJS JCL Spool.
9. The PJS System Task submits the job for execution.
10. After the job is submitted, the Job Request is updated to reflect the results of the submit:
· Any Job Request Events are reset.
· The Last Run Date and Time is set to the actual time of job submission.
· A new value for the Next Run Date and Time is caluclated.
· If there is a new value for Next Run Date and Time, PJS places the job request in WAIT status.
· If there is no Next Run Date and Time, PJS places the job request in COMPLETE status.
· If an error occurred during processing, the job request is placed in ERROR status.
11. The PJS System Task sends a message to tell you that job submission succeeded or failed. Messages are sent by the TSO SEND command with the LOGON option. All messages are recorded in the system log.
To receive PJS messages, your TSO profile must include the INTERCOMM operand. If you're not logged on when a PJS message is issued, or if you've chosen not to receive messages during the course of a session, the message is saved in the TSO messages data set, and the message is sent the next time you log on.