AS/400-iSeries Starter Kit

So far, I have explained how jobs are defined and started on the AS/400. We've seen that jobs are processed in a subsystem, which is where the system combines all the resources needed to process work. And we've seen how work entries control how jobs gain access to the subsystem. Now we need to talk about routing, which determines how jobs are processed after they reach the subsystem. I am constantly surprised by the number of AS/400 programmers who have never fully examined routing. In fact, it's almost as though routing is some secret whose meaning is known by only a few. In this chapter, I concentrate on subsystem routing entries to prove to you, once and for all, that you have nothing to fear!

The AS/400 uses routing to determine where jobs go. To understand routing, it might help to think of street signs, which control the flow of traffic from one place to another. The AS/400 uses the following routing concepts to process each and every job:

• Routing data -- A character string, up to 80 characters long, that determines the routing entry the subsystem will use to establish the routing step.
  
• Routing entry -- A subsystem description entry, which you create, that determines the program and job class the subsystem will use to establish a routing step.
  
• Routing step -- The processing that starts when the routing program executes.

To execute in a subsystem, AS/400 jobs must have routing data. Routing data determines which routing entry the subsystem will use. For most jobs, routing data is defined by either the RTGDTA (Routing Data) parameter of the job description associated with the job or by the RTGDTA parameter of the SBMJOB (Submit Job) command. Now let's look at each of these job types to see how routing data is defined for each.

Routing Data for Interactive Jobs

Users gain access to a given subsystem for interactive jobs via workstations, defined by workstation entries. The key to determining routing data for an interactive job is the JOBD (Job Description) parameter of the workstation entry that the subsystem uses to allocate the workstation being used. If the value for the JOBD parameter is *USRPRF, the routing data defined on the job description associated with the user profile is used as the routing data for the interactive job. If the value of the JOBD parameter of the workstation entry is *SBSD (which instructs the system to use the job description that has the same name as the subsystem description) or an actual job description name, the routing data of the specified job description will be used as the routing data for the interactive job. Let me give you a couple examples.

Let's say you create a user profile using the CRTUSRPRF (Create User Profile) command and do not enter a specific job description. The system uses QDFTJOBD (the default job description) for that user profile. Executing DSPJOBD QDFTJOBD reveals that the RTGDTA attribute has a value of QCMDI. When a user signs on to a workstation that uses a subsystem workstation entry where *USRPRF is defined as the JOBD attribute, the routing data for that interactive job would be the routing data defined on the job description associated with the user profile; in this case, the JOBD would be QDFTJOBD, and the routing data would be QCMDI.

Now look at Figure 19.1, in which the workstation entry defines SPJOBD as the job description. Instead of using the job description associated with the user profile, the subsystem uses the SPJOBD job description to establish job attributes, including the RTGDTA value of SPECIAL.

Routing Data for Batch Jobs

Establishing routing data for a batch job is simple; you use the RTGDTA parameter of the SBMJOB (Submit Job) command. The RTGDTA parameter on this command has four possible values:

• JOBD -- the routing data of the job description.
  
• RQSDTA -- the value specified in the RQSDTA (Request Data) parameter on the SBMJOB command. (Because the request data represents the actual command or program to process, specifying *RQSDTA is practical only if specific routing entries have been established in a subsystem to start specific routing steps based on the command or program being executed by a job.)
  
• QCMDB -- the default routing data used by the IBM-supplied subsystems QBASE or QBATCH to route batch jobs to the CL processor QCMD (more on this later).
  
• routing-data -- up to 80 characters of user-defined routing data.

Keeping these values in mind, let's look at a SBMJOB command. To submit a batch job that sends the operator the message "hi," you would enter the command

 SBMJOB JOB(MESSAGE) CMD('SNDMSG"hi" TOMSGQ(QSYSOPR)')

This batch job would use the routing data of QCMDB. How do I know that? Because, as I stated above, the value QCMDB is the default. If you submit a job using the SBMJOB command without modifying the default value for the RTGDTA parameter, the routing data is always QCMDB -- as long as this default has not been changed via the CHGCMDDFT (Change Command Default) command.

Now examine the following SBMJOB command:

 SBMJOB JOB(PRIORITY) CMD('call user-pgm')  +
       RTGDTA('high-priority')

In this example, a routing data character string ('high-priority') is defined. By now you are probably wondering just how modifying the routing data might change the way a job is processed. We'll get to that in a minute.

Figure 19.2 provides an overview of how the routing data for a batch job is established. A user submits a job via the SBMJOB command. The RTGDTA parameter of the SBMJOB command determines the routing data, and the resulting job (012345/USER_XX/job_name) is submitted to process in a subsystem. We can pick any of the four possible values for the RTGDTA attribute on the SBMJOB command and follow the path to see how that value eventually determines the routing data for the submitted batch job.

If you specify RTGDTA(*JOBD), the system examines the JOBD parameter of the SBMJOB command and then uses either the user profile's job description or the actual job description named in the parameter. If you define the RTGDTA parameter as *RQSDTA, the job uses the value specified in the RQSDTA (Request Data) parameter of the SBMJOB command as the routing data. Finally, if you define the RTGDTA parameter as QCMDB or any user-defined routing data, that value becomes the routing data for the job.

Routing Data for Autostart, Communications, and Prestart Jobs

As you may recall from Chapter 18, an autostart job entry in the subsystem description consists of just two attributes: the job name and the specific job description to be used for processing. The routing data of a particular job description is the only source for the routing data of an autostart job.

For communications jobs (communications evoke requests), the subsystem builds the routing data from the program start request, which always has the value PGMEVOKE starting in position 29, immediately followed by the desired program name. The routing data is not taken from a permanent object on the AS/400, but is instead derived from the program start request that the communications entry in the subsystem receives and processes.

Prestart jobs use no routing data. The prestart job entry attribute, PGM, specifies the program to start in the subsystem. The processing of this program is the routing step for that job.

The Importance of Routing Data

When a job enters a subsystem, the subsystem looks for routing data that matches the compare value in one or more routing entries of the subsystem description -- similar to the way you would check your written directions to see which highway exit to take. The subsystem seeks a match to determine which program to use to establish the routing step for that job. Routing entries, typically defined when you create a subsystem, are defined as part of the subsystem description via the ADDRTGE (Add Routing Entry) command. Before we take a closer look at the various attributes of a routing entry, let me explain how routing entries relate to routing data.

Figure 19.3 shows how the subsystem uses routing data for an interactive job. When USER_XX signs on to workstation DSP01, the interactive job is started, and the routing data (QCMDI) is established. When the job enters the subsystem, the system compares the routing data in the job to the routing data of each routing entry until it finds a match. (The search is based on the starting position specified in the routing entry and the literal specified as the compare value.)

In Figure 19.3, the compare value for the first routing entry (SEQNBR(10)) and the routing data for job 012345/USER_XX/DSP01 are the same. Because the system has found a match, it executes the program defined in the routing entry (QCMD in library QSYS) to establish the routing step for the job in the subsystem. In addition to establishing the routing step, the routing entry also provides the job with specific runtime attributes based on the job class specified. In this case, the specified class is QINTER.

Jobs that require routing data (all but prestart jobs) follow this same procedure when being started in the subsystem. Now that you have the feel of how this process works, let's talk about routing entries and associated job classes.

In Chapter 18, I said that routing entries identify which programs to call, define which storage pool the job will be processed in, and specify the execution attributes the job will use for processing. As shown in Figure 19.3, a routing entry consists of a number of attributes: sequence number, compare value, starting position, program, class, maximum active, and pool ID. Each attribute is defined when you use the ADDRTGE command to add a routing entry to a subsystem description. It's important that you understand these attributes and how you can use them to create the routing entries you need for your subsystems.

The sequence number is simply a basic numbering device that determines the order in which routing entries will be compared against routing data to find a match. When assigning a sequence number, you need to remember two rules. First, always use the compare value *ANY with SEQNBR(9999) so it will be used only when no other match can be found. (Notice that routing entry SEQNBR(9999) in Figure 19.3 has a compare value of *ANY.) Second, when using similar compare values, use the sequence numbers to order the values from most to least specific. For example, you would arrange the values PGMR, PGMRS, AND PGMRS1 this way:

             Sequence Number          Compare Value  
                10 			'PGMRS1'
                20 			'PGMRS'
                30 			'PGMR'

Placing the least specific value (PGMR) first would cause a match to occur even when the intended value (e.g., PGMRS1) is more specific.

The compare value and starting position attributes work together to search a job's routing data for a match. For example, if the value (ROUTE 5) is used, the system searches the job's routing data starting in position 5 for the value ROUTE. The compare value can be any characters you want (up to 80). The important thing is to use a compare value that matches some routing data that identifies a particular job or job type. Why go to this trouble? Because you can use this matching routing entry to determine a lot about the way a job is processed on the system (e.g., subsystem storage pool, run priority, and time slice).

The PGM attribute determines what program is called to establish the routing step for the job being processed. Remember, a routing step simply starts the program named in the routing entry. Normally, this program is QCMD (the IBM CL processor), but it can be any program. When QCMD is the routing program, it waits for a request message to process. For an interactive job, the request message would be the initial program or menu request; for a batch job, it would be the request data (i.e., the command or program to execute). If the routing program is a user-defined program, the program simply executes. The routing entry program is the first program executed in the routing step. The routing entry can be used to make sure that a specific program is executed when certain routing data is found, regardless of the initial program or specific request data for a job. Later in this chapter, I explain how this might be beneficial to you.

Runtime Attributes

The CLASS (job class) is an important performance-related object that defines the run priority of the job, as well as the time slice for a job. (The time slice is the length of time, in CPU milliseconds, a job will process before being bumped from the activity level to wait while another job executes a time slice.) A routing entry establishes a job's run priority and time slice much the way speed limit or yield signs control the flow of traffic. For more information on these performance-related attributes of the CLASS object, see IBM's AS/400 Programming: Work Management Guide (SC41-8078).

In Figure 19.3, all the routing entries use class QINTER, which is defined to represent the run priority and time slice typical for an interactive job. Because you would not want to process a batch job using these same values, the system also has an IBM-supplied class, called QBATCH, that defines attributes more typical for batch job processing. If you look at the subsystem description for QBASE or QBATCH, you will find the following routing entry:

      Sequence     Compare
      Number       Value          Program  	Class
     	10        'QCMDB'         QSYS/QCMD      QBATCH

This entry uses program QCMD and directs the system to use class QBATCH to define the runtime attributes for jobs having routing data QCMDB. To route jobs with the correct routing program and job class, the system-supplied routing data for the default batch job description QBATCH is QCMDB. You can use different classes to create the right performance mix.

MAXACT determines the maximum number of active jobs that can use a particular routing entry. You will rarely need to change this attribute's default (*NOMAX).

The last routing entry attribute is the POOLID (subsystem storage pool ID). As I explained in Chapter 17, the subsystem definition includes the specific storage pools the subsystem will use. These storage pools are numbered in the subsystem, and these numbers are used only within that particular subsystem description; they do not match the numbering scheme of the system pools. The routing entry attribute POOLID tells the system which subsystem storage pool to use for processing this job. Look at the following pool definition and abbreviated routing entry:

      Pool Definition:
     ((1 *BASE) (2 10000 20))

     Sequence Number  Compare Value  Pool ID
     	10               'QCMDI'        1

This routing entry tells the system to use subsystem pool number 1 (*BASE). Considering that 10,000 KB of storage is set aside in pool number 2, this routing entry is probably incorrectly specifying pool number 1. Beginners commonly make the mistake of leaving the default value in the routing entry definition when creating their own subsystems and defining their own routing entries. Just remember to compare the pool definition with the routing entry definition to ensure that the correct subsystem pool is being used.

Is There More Than One Way to Get There?

So far, we've discussed how routing data is created, how routing entries are established to search for that routing data, and how routing entries establish a routing step for a job and control specific runtime attributes of a job.

Now for one more hurdle... A job can have more than one routing step. But why would you want it to? One reason might be to use a new class to change the runtime attributes of the job.

After a job is started, you can reroute it using the RRTJOB (Reroute Job) command or transfer it to another subsystem using the TFRJOB (Transfer Job) command. Both commands have the RTGDTA parameter, which lets you modify the job's current routing data to establish a new routing step. Suppose you issue the following command during the execution of a job:

RRTJOB RTGDTA('FASTER') RQSDTA(*NONE)

Your job would be rerouted in the same subsystem but use the value FASTER as the value to be compared in the routing entries.

Do-It-Yourself Routing

To reinforce your understanding of routing and tie together some of the facts you've learned about work management, consider the following example.

Let's say you want to place programmers, OfficeVision/400 (OV/400) users, and general end users in certain subsystems based on their locations or functions. You need to do more than just separate the workstations; you need to separate the users, no matter what workstation they are using at the time. Figures 19.4a through 19.4f describe the objects and attributes needed to define such an environment.

Figure 19.4a lists three job descriptions that have distinct routing data. User-defined INTERJOBD has QINTER as the routing data. OFFICEJOBD and PGMRJOBD have QOFFICE and QPGMR specified, respectively, as their routing data. (Note that the routing data need not match the job description name.) To enable users to work in separate subsystems, you first need to create or modify their user profiles and supply the appropriate job description based on the subsystem in which each user should work. In our example, general end users would have INTERJOBD, OV/400 users would have OFFICEJOBD, and programmers would have the job description PGMRJOBD.

Next, you must build subsystem descriptions that use the routing entries associated with the job descriptions. Figure 19.4b shows some sample subsystem definitions. All three subsystems use the WRKSTNTYPE (workstation type) entry with the value *ALL. However, only the workstation entry in QINTER uses the AT(*SIGNON) entry to tell the subsystem to allocate the workstations. This means that subsystem QINTER allocates all workstations and QOFFICE and QPGMR (both with AT(*ENTER)) only allocate workstations as jobs are transferred into those subsystems. Also, notice that each workstation entry defines JOBD(*USRPRF) so that the routing data from the job descriptions of the user profiles will be the routing data for the job.

After a user signs on to a workstation in subsystem QINTER, the routing entries do all the work. The first routing entry looks for the compare value QOFFICE. When it finds QOFFICE, program QOFFICE in library SYSLIB is called to establish the routing step. In Figure 19.4c, program QOFFICE simply executes the TFRJOB command to transfer this particular job into subsystem QOFFICE. However, if you look carefully at
Figure 19.4c, you will see that the TFRJOB command also modifies the routing data to become QCMDI, so that when the job enters subsystem QOFFICE, routing data QCMDI matches the corresponding routing entry and uses program QCMD and class QOFFICE. If an error occurs on the TFRJOB command, the MONMSG CPF0000 EXEC(RRTJOB RTGDTA(QCMDI)) command reroutes the job in the current subsystem. Figure 19.4d shows how class QOFFICE might be created to provide the performance differences needed for OV/400 users.

Look again at Figure 19.4b. The next routing entry in the QINTER subsystem looks for compare value QPGMR. When it finds QPGMR, it calls program QPGMR (Figure 19.4e) to transfer the job into subsystem QPGMR. Routing data QCMDI calls program QCMD and then processes the initial program or menu of the user profile. The same is true for routing data *ANY.

In our example, subsystems QOFFICE and QPGMR use similar routing entries to make sure each job enters the correct subsystem. Notice that each subsystem has a routing entry that searches for QINTER. If this compare value is found, program QINTER (Figure 19.4f) is called to transfer the job into subsystem QINTER.

As intimidating as they may at first appear, routing entries are really plain and simple. Basically, you can use them to intercept jobs as they enter the subsystem and then control the jobs using various run-time variables. I strongly recommend that you take the time to learn how your system uses routing entries. Start by studying subsystem descriptions to learn what each routing entry controls. Once you understand them, you will find that you can use routing entries as solutions to numerous work management problems.