UPSTREAM Scheduler

USTSCHED Overview

UPSTREAM includes a simple, yet flexible scheduler program (USTSCHED), which can be used to schedule the automatic execution of:

• z/OS console commands to control UPSTREAM operations. This includes most of the commands described in UPSTREAM Operation, with the exception of z/OS START (UPSTREAM has to be started before the scheduler can be activated, so the scheduler cannot start UPSTREAM itself).
  
• USTSCHED can also be used to schedule any other command that can be issued on the z/OS console.
  
• It can also schedule commands to start USTBATCH tasks (z/OS Initiation with USTBATCH).
  
• It can be used to initiate any other (i.e., non-UPSTREAM) z/OS batch job or operator command.
  

It is important to note that USTSCHED is a basic scheduler and it has not been designed to replace other console automation or job scheduling software, which can usually do more sophisticated scheduling control, such as checking the results of a scheduled job or command.

If you currently use other, more advanced, scheduling software, it is recommended that you use that software for scheduling your UPSTREAM operations, instead of using USTCHED.

USTSCHED Schedules

USTSCHED schedules are stored and maintained as one or more members of a PDS, as indicated by the USTSCHED DD statement in the UPSTREAM startup PROC (see Define the UPSTREAM Started Task PROC).

This PDS is usually the same PDS as the one containing the main UPSTREAM configuration member (UPSTREAM Configurator). However, another PDS with the same characteristics (RECFM=FB, LRECL=120) can be used, if desired.

USTSCHED TSO/ISPF Dialog

The USTSCHED schedules are maintained through the UPSTREAM TSO/ISPF dialog. Select option 10 (“SCHEDULE”) and press ENTER.

UPSTREAM TSO/ISPF Dialog

You then specify the member name of the specific schedule that you wish to create, display or modify. You can use any name up to 8 characters in length.

UPSTREAM - Command Scheduler

Once a schedule member has been created or modified, you can test the schedule by specifying “YES” in the Test Schedule field. If necessary, update the Test Date field (the current date is filled in by default). The resulting dialog then displays all the commands that are issued on that date, with the time of day, under the schedule member shown.

Specifying the Schedules

When a schedule member is being created, or an existing member is being displayed or modified, you get a display similar to the one shown below:

UPSTREAM - Command Scheduler

Our preceding example shows a schedule with two entries. The first entry is for the reorganization of the CATALOG repository file, scheduled to run every Tuesday and Friday at 02:00. The second entry is a backup of SERVER 1 to be run every other Monday at 22:00. Although not shown here, a SERVER1 member within PROD.JCL.CNTL will contain the USTBATCH parameters required to initiate the backup.

As you can see, the CMD field on the far left of the screen is normally filled in with the unique sequence number of the schedule entry. However, you can overtype this number with any of the following standard ISPF-type editing codes:

• I - insert a new entry after this one.
  
• D - delete this entry.
  
• R - replicate this entry.
  

The Schedule operands follow:

• Selection ID - A meaningful description of the schedule entry.
  
• z/OS Command - The z/OS console command to be issued. (Required).
  
• Time(s) - One or more times (in 24-hour clock format). (Required).
  
• Date(s) - One or more dates (mm/dd/yy or mm/dd/yyyy). (Conditional).
  
• Monthday(s) - One or more days of the month (nn or LAST). (Conditional).
  
• Weekday(s) - One or more days of the week (any character). (Conditional).
  

At least one entry is required for either the Date(s), or Monthday(s), or Weekdays(s) operands. If two or all three of the operands has an entry, each will be honored.

If one or more Weekday(s) are checked, you may optionally modify that selection with data on one of the two Occurrence lines, as follows:

• Place any character in one or more of the boxes on the first occurrence line to limit execution to the first, second, last, etc., occurrence of the selected weekdays.
  
• Alternatively, you can enter values on the second occurrence line to limit execution to selected weekdays on every nth week, for up to 52 weeks, starting on the indicated date (the current date by default).
  

The Time(s), Date(s), and Monthday(s) fields are limited in size. If you run out of room before you enter all required values, you can replicate the entry (using “R” in the CMD field) and add the additional values on the new entry. Normally, the Selection ID field should be unique for each entry, but it may be the same for entries replicated for this purpose.

If you want to schedule the execution of batch jobs you can use the SUB command, as shown in the second example entry. Alternately, you can copy the USTRDR member from the UPSTREAM Installation Control Library (ICL) to a system PROCLIB. It can then be used in the UPSTREAM schedule, or as an actual console command to submit jobstreams from any library using the following syntax:

   S USTRDR,DSN=PROD.JCL.CNTL(SERVER1)The difference between using USTRDR and the SUB command relates to security:

• With the SUB command, the submitted job inherits the security userid under which the UPSTREAM started task itself runs.
  
• With USTRDR, the security userid probably needs to be specified in the submitted jobstream.
  

Schedule Exclusions

You notice towards the top of the scheduler screen that there are two check boxes called “Selection Entries” and “Exclusion Entries”. There is an “X” in one of these two boxes indicating what type of schedule entries are being displayed on the panel, as follows:

• “Selection Entries” displays the actual schedule entries.
  
• “Exclusion Entries” display exceptions to the selection schedules.
  

The exceptions may, for example, be special dates on which the schedules are not to be executed. The “Exclusion Entries” panel optionally allows you to exclude certain commands (or all commands) from executing at certain times.

You can enter an “X” (or any other character) in the “Selection Entries” or “Exclusion Entries” check box to switch between the two types of display. When you select “Exclusion Entries”, you get a display similar to this:

UPSTREAM - Command Scheduler

The values specified here are dates and/or times that the equivalent selection entries are not to be executed. An exclusion entry is only meaningful if there is one or more accompanying selection entry that matches on the time and/or date specified.

The first entry in our preceding example (“Global Exclusion Entry”) will apply to all selection entries, causing the entire schedule to be bypassed on January 1 in 2012 and 2013.

To specify an exclusion that applies only to a particular selection entry, specify an Exclusion ID that matches the Selection ID of the entry to which it applies.

If there are multiple Selection IDs with the same name, the exclusion will apply to all of them. Conversely, if there are multiple Exclusion IDs with the same name, they affect all Selection ID's that match that name.

In the preceding example, the selection entry with an ID of “Backup Server 1” is bypassed if it falls on the last day of any month.

Saving the Schedule

The revised schedule member is not modified or saved until you enter SAVE in the command field at the top of the panel. If you do not wish to save the changes you have made, enter CANCEL to discard them and then exit.

Operation and Startup

USTSCHED operates as a sub-task of the main UPSTREAM started task. It can be automatically started whenever the UPSTREAM started task is initiated by adding the SCHEDULE parameter (via a PARM=) to the UPSTREAM startup PROC (see Define the UPSTREAM Started Task PROC).

USTSCHED can also be started and stopped manually at any time. Below is an example of the z/OS MODIFY command (issued to the UPSTREAM started task) to start the scheduler.

The “membername” and “list” parameters are both optional. “Membername” points to the PDS member containing the current schedule. This is not needed if that member is pointed to by the USTSCHED DD statement in the UPSTREAM startup PROC (see Define the UPSTREAM Started Task PROC). The “List” parameter causes the schedule entries to be listed out in the UPSTREAM log file (USTLOG) as it is activated:

F UPSTREAM,SCHEDULE MEMBER=membername LISTThe result of the preceding MODIFY command depends on the following:

• If USTSCHED is currently started and has been activated from the same member, the schedule is refreshed and USTSCHED continues operation. This allows you to update the schedule dynamically, without having to stop/start USTSCHED or the UPSTREAM started task.
  
• If USTSCHED is not already active when the preceding command is issued, it starts up using the settings in the specified member.
  
• If USTSCHED is already active but it has been activated from a different member to the one indicated by membername, it start a second instance in a separate sub-task using the settings in the specified member. This allows you to have more than one USTSCHED schedule active at any one time, each controlled by a different member.
  

USTSCHED Task Control

Any task that has been successfully initiated through USTSCHED is then regarded as being just another UPSTREAM sub-task. Thus, once running, that sub-task can be controlled with the standard z/OS console commands (e.g., STOP, MODIFY, CANCEL), as described in UPSTREAM Operation.

USTSCHED in Status Displays

On z/OS status displays (see Status Display (MODIFY Command)) and Status Display (TSO/ISPF)), all instances of USTSCHED will be displayed with the unique “membername” appearing in the userid field.