AS/400-iSeries Starter Kit

The job scheduling function, new with V2R2, lets you schedule jobs to run at dates and times you choose without performing any add-on programming. There are two V2R2 additions that let you control job scheduling:

• new parameters on the SBMJOB command
• the new job schedule object

The job schedule function was made possible by enhancing the operating system with QJOBSCD, a new system job that is started automatically when you IPL the system. This job monitors scheduled job requirements, then submits and releases scheduled jobs at the appropriate date and time.

Arriving on Time

The SBMJOB command, of course, places a job on a job queue for batch processing, apart from an interactive workstation session. Starting with V2R2, the new SCDDATE and SCDTIME parameters let you specify a date and time for the job to be run. This scheduling method is a one-time shot; you use it for a job that you want to run only once, at a later date and/or time. If you want a job to run more than once, you'll have to remember to submit it each time (or use the job schedule object, as I discuss later).

When you use the new parameters to indicate a schedule date and/or time, the SBMJOB command places the job on a job queue in a scheduled state (SCD) until the date and time you specified; then the system releases the job on the job queue and processes it just like any other submitted job. If you specify HOLD(*YES) on the SBMJOB command, at the appointed time the job's status on the queue will change from scheduled/held (SCD HLD) to held (HLD). You can then release the job when you choose.

The default value for the SCDDATE and SCDTIME parameters is *CURRENT, which indicates that you want to submit the job immediately; so if you don't specify a value for these parameters, the SBMJOB command works just as it always has. Otherwise, you'll usually specify an exact date (in the same format as the job's date) and time for the job to run. There are, however, other possible special values that you may find useful for the SCDDATE parameter.

If you indicate SCDDATE(*MONTHSTR), the job will run at the scheduled time on the first day of the month. SCDDATE(*MONTHEND) will run the job on the last day of the month. (No more "30 days hath September..." or counting on your fingers!) Or you can specify SCDDATE(*MON) or *TUE, *WED, *THU, *FRI, *SAT, or *SUN, to run the job on the specified day of the week.

During which month, on which Monday, and so on, will your job be run? That depends. For example, if today is the first day of the month and you specify SCDDATE(*MONTHSTR) and the current time is previous to the time in the SCDTIME parameter... it'll run today. Otherwise, it'll wait until next month. Similar logic applies for other SCDDATE and SCDTIME possibilities.

If you remove a scheduled job from a job queue, the job will not run, even when the scheduled time and date occur. You can remove a job from the queue either by using the CLRJOBQ (Clear Job Queue) command or by using the WRKJOBQ (Work with Job Queue) command and ending the job. Holding a job queue that includes a scheduled job can delay execution of the job, but it will not prevent the job from running when you release the job queue, even if the scheduled time has passed.

Running on a Strict Schedule

In addition to enhancing the SBMJOB command, V2R2 introduces a new type of AS/400 object, the job schedule, with a system identifier of *JOBSCD. (Sorry, Canadians and Brits, IBM didn't pick *JOBSHD.) The job schedule is a timetable that contains descriptive entries for jobs to be executed at a specific date, time, and/or frequency. It is most useful for jobs that you want to run repeatedly according to a set schedule. If a job is on the job schedule, you need not remember to submit it for every execution; the operating system takes care of that chore. The job schedule function is documented in the Work Management Guide (SC41-8078).

One job schedule exists on the system: object QDFTJOBSCD in library QUSRSYS. Although its name indicates that this object is the default job schedule, it is the only one. The operating system offers no commands to create, change, or delete your own customized job schedules... yet. You can manipulate the entries in the job schedule using the following new commands:

• ADDJOBSCDE (Add Job Schedule Entry)
• CHGJOBSCDE (Change Job Schedule Entry)
• HLDJOBSCDE (Hold Job Schedule Entry)
• RLSJOBSCDE (Release Job Schedule Entry)
• RMVJOBSCDE (Remove Job Schedule Entry)
• WRKJOBSCDE (Work with Job Schedule Entries)

Figure 13.1 shows a sample list display that appears when you run the WRKJOBSCDE command. When you select option 5 (Display details) for an entry, you get a display such as that in Figure 13.2. This example shows the details of a job my system runs every weekday morning at 3:30.

Each job schedule entry is made up of many components that define the job to be run and describe the environment in which it will run. Figure 13.3 describes those components and lists the parameter keywords the job-scheduling CL commands use. With V2R3, you can print a list of your job schedule entries by entering the WRKJOBSCDE command, followed by a space and OUTPUT(*PRINT). For detailed information on each job schedule entry on the list, follow the WRKJOBSCDE command with PRTFMT(*FULL).

OS/400 gives each job schedule entry a sequence number to identify it uniquely. You usually refer to an entry by its job name, but if there are multiple entries with the same job name, you also have to specify the sequence number to correctly refer to the entry. For example, in Figure 13.1, there are three entries named VKEMBOSS. Displaying the details for each, however, would show that they each have a unique sequence number.

The frequency component (FRQ) of a schedule entry may seem confusing at first. It's obvious that you can schedule a job to run *ONCE, *WEEKLY, or *MONTHLY; but what if you want to schedule a daily job? In that case, you need to use an additional schedule entry element, the scheduled day (SCDDAY). To run a job every day, specify FRQ(*WEEKLY) and SCDDAY(*ALL). You can also run the job only on weekdays, using FRQ(*WEEKLY) and SCDDAY(*MON *TUE *WED *THU *FRI). Just Thursdays? That's easy: FRQ(*WEEKLY) and SCDDAY(*THU).

The scheduled date component (SCDDATE) of a schedule entry tells the system a specific date to run the job. If you use the SCDDAY parameter, you cannot use the SCDDATE parameter; the two don't make sense together. The combination of FRQ(*MONTHLY) and SCDDATE(*MONTHEND) will run a job on the last day of each month, regardless of how many days each month has.

The relative day of the month parameter (RELDAYMON) gives the job schedule even more flexibility. For instance, if you want to run a job only on the first Tuesday of each month, you indicate values for three parameters: FRQ(*MONTHLY) SCDDAY(*TUE) RELDAYMON(1).

Sometimes your computer can't run a job at the scheduled time; for example, your AS/400 may be powered off or in the restricted state at the time the job is to be submitted. In the recovery action component (RCYACN) of the schedule entry, you can tell the computer to take one of three actions. RCYACN(*SBMRLS) submits the job to be run as soon as possible. RCYACN(*SBMHLD) submits the job, but holds it until you explicitly release it for processing. RCYACN(*NOSBM) is the "Snooze, you loose" option; the job scheduler will not attempt to submit the job after the scheduled time passes. Notice that this feature applies only to jobs scheduled from the job schedule, not to those you submit with SBMJOB.

Two Trains on the Same Track

When I was setting up job schedule entries for my system, I discovered that many of the entries I made were similar. I found myself wanting to copy a job schedule entry to save myself from the drudgery of retyping long, error-prone command strings. Because the job schedule commands don't offer such a function, I decided to write a command that does.

My command, CRTDUPSCDE (Create a Duplicate Job Schedule Entry), is easy to use. You simply supply the command with the job name of the existing job schedule entry you want to copy from and a name you want to give the copy:

CRTDUPSCDE FROMJOB(job-name) NEWNAME(new-name)

The NEWNAME parameter defaults to *FROMJOB, indicating that the new entry should have the same name as the original; the system will give the entry a unique sequence number.

Figure 13.4 provides the code for the CRTDUPSCDE command. Figure 13.5 is the command processing program (CPP). CRTDUPSCDE uses the IBM-supplied program QWCLSCDE, a new API that lists job schedule entries in a user space. (See A in Figure 13.5.) After retrieving the "from" job schedule entry (which you specified in the FROMJOB parameter), the program breaks the output from the API down into the parameter values that describe the entry; then it uses the same values in the ADDJOBSCDE command to create a new entry based on the existing one. After that, it's a simple matter to use the CHGJOBSCDE command to make any minor changes the new entry needs. (You can find documentation for QWCLSCDE and the user space layouts used in CRTDUPSCDE in the System Programmer's Interface Reference (SC21-8223).) The command also uses two user space APIs: QUSCRTUS and QUSRTVUS.

In addition to being easy to use, CRTDUPSCDE is very basic. To conserve space, I didn't include some features that you might want to add. For example, I used very basic error trapping instead of error-message-handling routines. Also, the command retrieves only the first instance of a schedule entry with the name you choose, even though the job schedule could contain multiple entries of the same name. If you have multiple same-name entries and you want to retrieve one other than the first, you'll need to add the code to loop through the data structure that returns the name. Finally, my command doesn't duplicate the OMITDATE values from the original. Doing so would require adding array-handling techniques to the CL program, which isn't worth the effort to me because I hardly ever use this parameter. I encourage you to experiment with enhancing this command to suit your own needs.

Derailment Dangers

A few cautionary comments are in order before we finish our exploration of the new OS/400 job schedule object. There are a few situations that I ran into when I was implementing the function and that the Work Management Guide doesn't adequately cover.

It is important to know that a job submitted by the job schedule will not retain the contents of the LDA from the job that originally added it to the job schedule. In my tests of the new function, I was never able to run the scheduled job with anything other than a blank LDA. When you submit a job with the SBMJOB command, however, the system passes a copy of the LDA to the submitted job. It's a common practice to store variable processing values in the LDA as a handy means of communicating between jobs or between programs within a job. If your application depends upon specific values in the LDA, you may want to schedule jobs using the SBMJOB command instead of creating a job schedule entry.

I've discovered an alternate technique, however, that still lets me take advantage of a job schedule entry for recurring jobs that need the LDA. When I add the job schedule entry, I also create a unique data area that contains the proper values in the proper locations, according to the specifications in the submitted program. It's then a simple matter to make a minor change to the submitted program so that the program either uses the new data area instead of the LDA or retrieves the new data area and copies it to the LDA using the RTVDTAARA (Retrieve Data Area) and/or CHGDTAARA (Change Data Area) commands. This new data area should be a permanent object on the system as long as the dependent job schedule entry exists.

SBMJOB has another benefit that a job scheduling entry does not offer. When you use SBMJOB to schedule a job, the system defaults to using an initial library list that is identical to the library list currently in use by the submitting job. The job schedule entry, on the other hand, depends upon the library list in its JOBD component. If you've gotten out of the old S/38 habit of creating unique job descriptions primarily to handle unique library lists, you'll need to resurrect this technique to describe the library list for job schedule entries.

It's also noteworthy that, just like the railroad, the job scheduling function may not always run on time, no matter whether you use SBMJOB or the job schedule object. Although you can schedule a job to the second, the load on your system determines when the job actually runs. The system submits a job schedule entry to a job queue or releases a scheduled job already on a job queue approximately on time -- usually within a few seconds. But if there are many jobs waiting on the job queue ahead of the scheduled job, it will simply have to wait its turn. If it's critical that a job run at a specific time, you can help by ensuring that the job's priority (parameter JOBPTY) puts it ahead of other jobs on the queue; but the job may still have to wait for an available activity slot before it can begin. And as I mentioned earlier, if your system is down or in a restricted state at the appointed time, the job schedule may not submit the job at all.

Changing your system's date or time can also affect your scheduled jobs. If you move the date or time system values backward, the effect is fairly straightforward: The system will not reschedule any job schedule entries that were run within the repeated time. For example, if at three o'clock you change your system's time back to one o'clock, the job you had scheduled to run at two o'clock won't repeat itself. The system stores a "next submission" date and time for each entry, which it updates each time the job schedule submits a job.

Changing the system's date or time forward, however, can be tricky. If the change causes the system to skip over a time when you had a job scheduled, the job schedule's action depends upon whether or not the system is in restricted state when you make the change. If the system was not restricted, any missed job schedule entries are submitted immediately (only one occurrence of each missed entry is submitted even if, for example, you've scheduled a job to run daily and moved the system date ahead two days). If the system is in restricted state when you change the date or time system values, the system refers to the RCYACN attributes of the missed job schedule entries to determine whether or not to submit the jobs when you bring the system out of its restricted state.

The job scheduling function in V2R2 does not offer job completion dependencies, regardless of which method you use. For example, if you use the job schedule to run a daily transaction posting, then a daily closing, you cannot condition the closing job to be run only if the posting job goes through to a successful completion. Some third-party scheduling functions offer this capability. Without a third-party product, if you need to schedule jobs with such a completion requirement, your best bet is probably to incorporate the entire procedure into a single CL program with appropriate escape routes defined in case one or more functions fail.