AS/400-iSeries Starter Kit

One of OS/400's most elegant features is the concept of a "job," a unit of work with a tidy package of attributes that lets you easily identify and track a job throughout your system. The AS/400 defines this unit of work with a job name, a user profile associated with the job, and a computer-assigned job number; it is these three attributes that make a job unique. For example, when a user signs on to a workstation, the resulting job might be known to the system as

Job name . . . : DSP10 (Workstation ID)

User profile . : WMADDEN

Job number . : 003459

Any transaction OS/400 completes is associated with an active job executing on the system. But where do these jobs come from? A job can be initiated when you sign on to the system from a workstation, when you submit a batch job, when your system receives a communications evoke request from another system, when you submit a prestart job, or when you create autostart job entries that the system automatically executes when it starts the associated subsystem.

Understanding how jobs get started on the system is crucial to grasping AS/400 work management concepts. So let's continue Chapter 17's look at the subsystem description by focusing on work entries, the part of the description that defines how jobs gain access to the subsystem for processing.

Types of Work Entries

There are five types of work entries: workstation, job queue, communications, prestart job, and autostart job. The easiest to understand is the workstation entry, which describes how a user gains access to a particular subsystem (for interactive jobs) using a workstation. To define a workstation entry, you use the ADDWSE (Add Work Station Entry) command. A subsystem can have as many workstation entries as you need, all of which have the following attributes:

• WRKSTNTYPE (workstation type) or WRKSTN (workstation name)

• JOBD (job description name)

• MAXACT (maximum number of active workstations)

• AT (when to allocate workstation)

When defining a workstation entry, you can use either the WRKSTNTYPE or WRKSTN attribute to specify which workstations the system should allocate. For instance, if you want to allocate all workstations, you specify WRKSTNTYPE(*ALL) in the workstation entry. This entry tells the system to allocate all workstations, regardless of the type (e.g., 5250, 5291, 3476, or 3477). Or you can use the WRKSTNTYPE attribute in one or more workstation entries to tell the system to allocate a specific type of workstation (e.g., WRKSTNTYPE(3477)).

You can also define workstation entries using the WRKSTN attribute to specify that the system allocate workstations by name. You can enter either a specific name or a generic name. For example, an entry defining WRKSTN(DSP01) tells the subsystem to allocate device DSP01. The generic entry, WRKSTNN(OHIO*), tells the subsystem to let any workstation whose name begins with "OHIO" establish an interactive job.

You must specify a value for either the WRKSTNTYPE parameter or the WRKSTN parameter. In addition, you cannot mix WRKSTNTYPE and WRKSTN entries in the same subsystem. If you do, the subsystem recognizes only the entries that define workstations by the WRKSTN attribute and ignores any entries using the WRKSTNTYPE attribute.

The JOBD workstation entry attribute specifies the job description for the workstation entry. You can give this attribute a value of *USRPRF (the default) to tell the system to use the job description named in the user profile of the person who signs on to the workstation. Or you can specify a value of *SBSD to tell the system to use the job description of the subsystem. You can also use a qualified name of an existing job description. For security reasons, it's wise to use the default value *USRPRF for the JOBD attribute so that a user profile is required to sign on to the workstation. If you use the value *SBSD or a job description name and there is a valid user profile associated with the job description via the USER attribute, any user can simply press Enter and sign on to the subsystem. In such a situation, the user then assumes the user ID associated with the default job description named on the workstation entry.

There may be times when you want to define a workstation entry so that one user profile is always used when someone accesses the system via a particular workstation (e.g., if you wanted to disseminate public information at a courthouse, mall, or school). In such cases, be sure to construct such configurations so that only certain workstation entries have a job description that provides this type of access.

The workstation entry's MAXACT attribute determines the maximum number of workstations allowed in the subsystem at one time. When this limit is reached, the subsystem must de-allocate one workstation before it can allocate another. The value that you should normally use for this attribute is the default, *NOMAX, because you typically control (i.e., you physically limit) the number of devices. In fact, supplying a number for this attribute could cause confusion if one day the limit is reached and some poor soul has to figure out why certain workstations aren't functioning. It could take days to find this seldom-used attribute and change the value.

The AT attribute tells the system when to allocate the workstation. The default value, AT(*SIGNON), tells the system to allocate the workstation (i.e., initiate a sign-on screen at the workstation) when the subsystem is started. AT(*ENTER) tells the system to let jobs enter the subsystem only via the TFRJOB (Transfer Job) command. (To transfer a job into an interactive subsystem, a job queue and a subsystem description job queue entry must exist.)

Now you're acquainted with the workstation entry attributes, but how can you use workstation entries? Let's say you want to process all your interactive jobs in subsystem QINTER. When you look at the default workstation entries for QINTER, you see the following: CRTSBSD (Create Subsystem Description) commands:

The first set of values tells the system to allocate all workstations to subsystem QINTER when the subsystem is started. The second set of values tells the system to let the console transfer into the subsystem, but not to allocate the device.

What about a multiple subsystem environment for interactive jobs? Let's say you want to configure three subsystems: one for programmers (PGMRS), one for local end-user workstations (LOCAL), and one for remote end-user workstations (REMOTE). How can you make sure the system allocates the workstations to the correct subsystem?

Perhaps you're thinking you can create individual workstation entries for each device. You can, but such a method would be a nightmare to maintain, and it would require you to end the subsystem each time you added a new device. Likewise, it would be impractical to use the WRKSTNTYPE attribute, because defining types does not necessarily define specific locations for certain workstations.

So you have only two good options for ensuring that the correct subsystem allocates the devices. One is to name your various workstations so you can use generic WRKSTN values in the workstation entry. For example, you can allocate programmers' workstations to the proper subsystem by first giving them names like PGMR01 or PGMR02 and then creating a workstation entry that specifies WRKSTN(PGMR*). You might preface all local end-user workstation names with ADMN and LOC and then create workstation entries in the local subsystem using WRKSTN(ADMN*) and WRKSTN(LOC*). For the remote subsystem, you could continue to create workstation entries using generic names like the ones described above, or simply specify WRKSTNTYPE(*ALL), which would cause the subsystem to allocate the remaining workstations. However, you will need to read on to learn how subsystems allocate workstations to ensure that those workstations in the programmer and local subsystems are allocated properly.

Your second option for ensuring that the correct subsystem allocates the devices is to use routing entries to reroute workstation jobs to the correct subsystem (I will explain how to do this in the next chapter).

Conflicting Workstation Entries

Can workstation entries in different subsystems conflict with each other? You bet they can! Consider what happens when two different subsystems have workstation entries that allocate the same device. If AT(*SIGNON) is specified in the workstation entry, the first subsystem will allocate the device, and the device will show a sign-on display. When the system starts another subsystem with a workstation entry that applies to that same device (with AT(*SIGNON) specified), the subsystem will try to allocate it. If no user is signed on to the workstation, the second subsystem will allocate the device.

This arrangement isn't all bad. In fact, you can make it work for you. Imagine that you want to establish an interactive environment for two subsystems: QINTER (for all end-user workstations) and QPGMR (for all programmer workstations). You supply WRKSTNTYPE(*ALL) for subsystem QINTER and WRKSTN(PGMR*) for subsystem QPGMR.

To ensure that each workstation is allocated to the proper subsystem, you should start QINTER first. Consequently, the system will allocate all workstations to QINTER. After a brief delay, start QPGMR, which will then allocate (from QINTER) only the workstations whose names begin with "PGMR". Every workstation has its rightful place by simply using the system to do the work.

What about you? Can you see how your configuration is set up to let interactive jobs process? Take a few minutes to examine the workstation entries in your system's subsystems. You can use the DSPSBSD (Display Subsystem Description) command to display the work entries that are part of the subsystem description.

Job Queue Entries

Job queue entries control job initiation on your system and define how batch jobs enter the subsystem for processing. To submit jobs for processing, you must assign one or more job queues to a subsystem. A job queue entry associates a job queue with a subsystem. The attributes of a job queue entry are as follows:

• JOBQ (job queue name)

• MAXACT (maximum number of active jobs from this job queue)

• SEQNBR (sequence number used to determine order of selection among all job queues)

• MAXPTYn (maximum number of active jobs with this priority)

The JOBQ attribute, which is required, defines the name of the job queue you are attaching to the subsystem. The subsystem will search this job queue to receive jobs for processing. You can name only one job queue for a job queue entry, but you can define multiple job queue entries for a subsystem.

The MAXACT attribute defines the maximum number of jobs that can be active in the subsystem from the job queue named in this entry. This attribute controls only the maximum number of jobs allowed into the subsystem from the job queue. The default for MAXACT is 1, which lets only one job at a time from this job queue process in the subsystem.

The MAXACT (yes, same name) attribute of the subsystem description controls the maximum number of jobs in the subsystem from all entries (e.g., job queue and communications entries).

You can use the SEQNBR attribute to sequence multiple job queue entries associated with the subsystem. The subsystem searches each job queue in the order specified by the SEQNBR attribute of each job queue entry. The default for this attribute is 10, which you can use to define only one subsystem job queue entry; however, when defining multiple job queue entries, you should determine the appropriate sequence numbers desired to prioritize the job queues.

The MAXPTYn attribute is similar to the MAXACT attribute except that MAXPTYn controls the number of active jobs from a job queue that have the same priority (e.g., MAXPTY1 defines the maximum for jobs with priority 1, MAXPTY2 defines the maximum number for jobs with priority 2). The default for MAXPTY1 through MAXPTY9 is *NOMAX.

To illustrate how job queue entries work together to create a proper batch environment, Figure 18.1 shows a scheme that includes three subsystems: DAYSBS, NIGHTSBS, and BATCHSBS. DAYSBS processes daytime, short-running end-user batch jobs. NIGHTSBS processes nighttime, long-running end-user batch jobs. BATCHSBS processes operator-submitted requests and program compiles. To create the batch work environment in Figure 18.1, you first create the subsystems using the following CRTSBSD (Create Subsystem Description) commands:

CRTSBSD SBSD(QGPL/DAYSBS) POOL((1 *BASE) (2 400 1)) MAXACT(1)
CRTSBSD SBSD(QGPL/NIGHTSBS) POOL((1 *BASE) (2 2000 2)) MAXACT(2)
CRTSBSD SBSD(QGPL/BATCHSBS) POOL((1 *BASE) (2 1500 3) MAXACT(3)

Notice that each subsystem has an established maximum number of active jobs (MAXACT(n)). The maximum limit matches the activity level specified in the subsystem pool definition so that each active job is assigned an activity level without having to wait for one.

The next step is to create the appropriate job queues with the following CRTJOBQ (Create Job Queue) commands:

CRTJOBQ JOBQ(QGPL/DAYQ)
CRTJOBQ JOBQ(QGPL/NIGHTQ)
CRTJOBQ JOBQ(QGPL/PGMQ)
CRTJOBQ JOBQ(QGPL/BATCHQ)

Then, add the job queue entries to associate the job queues with the subsystems:

ADDJOBQE SBSD(DAYSBS) JOBQ(DAYQ) MAXACT(*NOMAX) SEQNBR(10)
ADDJOBQE SBSD(NIGHTSBS) JOBQ(NIGHTQ) MAXACT(*NOMAX) SEQNBR(10)
ADDJOBQE SBSD(BATCHSBS) JOBQ(PGMQ) MAXACT(1) SEQNBR(10)
ADDJOBQE SBSD(BATCHSBS) JOBQ(BATCHQ) MAXACT(2) SEQNBR(20)

Now let's walk through this batch work environment. Subsystem DAYSBS is a simple configuration that lets one job queue feed jobs into the subsystem. Because the MAXACT attribute value of DAYSBS is 1, only one job filters into the subsystem at a time, despite the fact that you specified the attribute MAXACT(*NOMAX) for the DAYQ job queue entry. Later, you can change the subsystem pool size and activity level, along with the MAXACT subsystem attribute, to let more jobs from the job queue process without having to re-create the job queue entry to modify MAXACT.

The configuration of NIGHTSBS is similar to the configuration of DAYSBS, except that it lets two jobs process at the same time. This subsystem is inactive during the day and starts at night via the STRSBS (Start Subsystem) command. When a subsystem is inactive, no job queues are allocated and no jobs are processed. Therefore, application programs can send batch jobs to the NIGHTQ job queue, where they wait to process at night. When NIGHTSBS starts, the system allocates job queue NIGHTQ and jobs can be processed.

To show you how job queues can work together to feed into one subsystem, I configured the BATCHSBS subsystem with two job queue entries. Notice that BATCHSBS supports a maximum of three jobs (MAXACT(3)). Job queue entry PGMQ lets one job from that queue be active (MAXACT(1)), while job queue entry BATCHQ lets two jobs be active (MAXACT(2)).

As with workstation entries, job queue entries can conflict if you define the same job queue as an entry for more than one subsystem. When a subsystem starts, the job queues defined in the job queue entries are allocated. And when a job queue is allocated to an active subsystem, that job queue cannot be allocated to another subsystem until the first subsystem ends. In other words, first come, first served... or first come, first queued!

Communications Entries

After you establish a workstation and a physical connection between remote sites, you need a communications entry, which enables the subsystem to process the program start request. If there are no communications entries, the system rejects any program start request. There's no real pizazz to this entry; you simply need it to link the remote system with your subsystem.

A communications entry has the following attributes:

• DEV (name or type of communications device)
• RMTLOCNAME (remote location name)
• JOBD (job description name)
• DFTUSR (default user profile name)
• MODE (mode description name)
• MAXACT (maximum number of jobs active with this entry)

The DEV attribute specifies the particular device (e.g., COMMDEV or REMSYS) or device type (e.g., *APPC) needed for communications. The RMTLOCNAME attribute specifies the remote location name you define when you use the CRTDEVxxxx command to create the communications device. There is no default for the DEV or the RMTLOCNAME attribute. As with the WRKSTNTYPE and WRKSTN attributes, you must specify one or the other, but not both.

The next two attributes, JOBD and DFTUSR, are crucial. JOBD specifies the job description to associate with this entry. As you do with the workstation entry, you should use the default value *USRPRF to ensure that a user profile is used and that the system uses the job description associated with the user making the program start request. As with workstation entries, using a specific job description can cause a security problem if that job description names a default user. DFTUSR defines the default user for the communications entry. You should specify *NONE for this attribute to ensure that any program start request supplies a valid user profile and password.

The MODE attribute defines specific communications boundaries and variables. For more information about the MODE attribute, see the CRTMODD (Create Mode Description) command description in IBM's AS/400 Programming: Control Language Reference (SC41-0030).

The MAXACT attribute defines the maximum number of program start requests that can be active at any time in the subsystem for this communications entry.

You can add a communications entry by using the ADDCMNE (Add Communications Entry) command, as in the following example:

ADDCMNE SBSD(COMMSBS) RMTLOCNAME(NEWYORK) JOBD(*USRPRF)  +
        DFTUSR(*NONE) MODE(*ANY) MAXACT(*NOMAX)

If you are communicating already and you want to know what entries are configured, use the DSPSBSD (Display Subsystem Description) command to find out.

Prestart Job Entries

The prestart job entry goes hand-in-hand with the communications entry, telling the subsystem which program to start when the subsystem itself is started. The program does not execute -- the system simply performs all the opens and initializes the job named in the prestart job entry and then waits for a program start request for that particular program. When the system receives a program start request, it starts a job by using the prestart program that is ready and waiting, thus saving valuable time in program initialization.

The prestart job entry is the only work entry that defines an actual program and job class to be used. (Other jobs get their initial routing program from the routing data entries that are part of the subsystem description.) The two key attributes of the prestart job entry are PGM and JOBD. The PGM attribute specifies the program to use and the JOBD attribute specifies the job description to be used.

To add a prestart job entry, use an ADDPJE (Add Prestart Job Entry) command similar to the following:

ADDPJE SBSD(COMMSBS) PGM(OEPGM) JOBD(OEJOBD)

Then, when the communications entry receives a program start request (an EVOKE) and processes the request, it will compare the program evoke to the prestart job program defined. In this case, if the program evoke is also OEPGM, the system has no need to start a job because the prestart job is already started.

Autostart Job Entry

An autostart job entry specifies the job to be executed when the subsystem starts. For instance, if you want to print a particular history report each time the system is IPLed, you can add the following autostart job entry to the controlling subsystem description:

ADDAJE SBSD(sbs_name) JOB(HISTORY) JOBD(MYLIB/HISTJOBD)

The JOB and JOBD attributes are the only ones the autostart job entry defines, which means that the job description must use the request data or routing data to execute a command or a program. In the example above, HISTJOBD would have the correct RQSDTA (Request Data) attribute to call the program that generates the history report (e.g., RQSDTA('call histpgm')). The job HISTORY, defined in the autostart job entry, starts each time the associated subsystem starts, ensuring that the job runs whether or not anyone remembers to submit it.

OS/400 uses an autostart job entry to assist the IPL process. When you examine either the QBASE or QCTL subsystem description (using the DSPSBSD command), you will find that an autostart job entry exists to submit the QSTRUPJD job using the job description QSYS/QSTRUPJD. This job description uses the request data to call a program used in the IPL process.

Where Jobs Go

Now we've seen where jobs come from on the AS/400 -- but where do they go? I'll address that question in the next chapter when we look at how routing entries provide the final gateway to subsystem processing.

One reminder. If you decide to create or modify the system-supplied work management objects such as subsystem descriptions and job queues, you should place the new objects in a user-defined library. When you are ready to start using your new objects, you can change the system startup program QSYS/QSTRUP to use your new objects for establishing your work environment (to change the system startup program, you modify the CL source and recompile the program). By having your new objects in your own library, you can easily document any changes.