Tuning prestart job entries

You should have enough prestart jobs started by the subsystem so that work is handled as it arrives rather than waiting for new jobs to be started. These tips show how to tune your prestart jobs for optimum performance.

Setting the number of prestart jobs

While the system is handling its normal workload and information about the workload is available, follow the following steps:

Use the Work with Subsystems (WRKSBS) command to get a list of all active subsystems. For each subsystem in the list of active subsystems, use option 5 to display the subsystem description.
On the Display Subsystem Description panel, use option 10 to display prestart job entries. If there are no prestart job entries for that subsystem description, continue with the next subsystem in the WRKSBS list.
On the Display Prestart Job Entries panel, use option 5 to display details for the prestart job entry. Make a note of the current settings for Initial number of jobs, Threshold, and Additional number of jobs.
For each prestart job entry in the subsystem description, enter a Display Active Prestart Jobs (DSPACTPJ) command.
For example:
```
DSPACTPJ SBS(SUBSYSTEM) PGM(PJPGMLIB/PJPROGRAM) 
```
If the DSPACTPJ command is not currently allowed, the prestart job entry is not active and does not need to be changed. Continue with the next prestart job entry or the next subsystem description.

Use the DSPACTPJ information to get an estimate of your workload. The DSPACTPJ command produces a display that looks like this:

------------------------------------------------------------------------------
                         Display Active Prestart Jobs                 SYSTEM
                                                            08/06/03  07:35:00
Subsystem  . . . . . :   SUBSYSTEM       Reset date . . . . . :   08/06/03
Program  . . . . . . :   PJPROGRAM       Reset time . . . . . :   07:23:03
  Library  . . . . . :     PJPGMLIB      Elapsed time . . . . :   0000:11:57

Prestart jobs:
  Current number . . . . . . . . . . . . . . . . :   122
  Average number . . . . . . . . . . . . . . . . :   21.4
  Peak number  . . . . . . . . . . . . . . . . . :   122

Prestart jobs in use:
  Current number . . . . . . . . . . . . . . . . :   120
  Average number . . . . . . . . . . . . . . . . :   17.7
  Peak number  . . . . . . . . . . . . . . . . . :   120

                                                                       More...
Press Enter to continue.

F3=Exit   F5=Refresh   F12=Cancel   F13=Reset statistics
------------------------------------------------------------------------------

------------------------------------------------------------------------------
                         Display Active Prestart Jobs                 SYSTEM
                                                            08/06/03  07:35:00
Subsystem  . . . . . :   SUBSYSTEM       Reset date . . . . . :   08/06/03
Program  . . . . . . :   PJPROGRAM       Reset time . . . . . :   07:23:03
  Library  . . . . . :     PJPGMLIB      Elapsed time . . . . :   0000:11:57
Program start requests:
  Current number waiting . . . . . . . . . . . . :   0
  Average number waiting . . . . . . . . . . . . :   .0
  Peak number waiting  . . . . . . . . . . . . . :   1
  Average wait time  . . . . . . . . . . . . . . :   00:00:00.0
  Number accepted  . . . . . . . . . . . . . . . :   120
  Number rejected  . . . . . . . . . . . . . . . :   0
                                                                        Bottom
Press Enter to continue.

F3=Exit   F5=Refresh   F12=Cancel   F13=Reset statistics
------------------------------------------------------------------------------

Find the prestart jobs in use section and the value for the peak number. In this example, the value is 120. This number is an estimate of your peak workload. Make a note of this value, it is used in the following steps.

Find the program start requests section and the value for the peak number waiting. You may need to page down to see this field. In this example, the value is 1. This number tells you how well the system is handling the arrival of new work. Make a note of this value, it is used in the following steps.

If DSPACTPJ shows a zero (0) for the peak number of prestart jobs in use, the prestart job entry is not being used by your workload and therefore does not need to be changed. Continue with the next prestart job entry or the next subsystem description.
Choose a value for the THRESHOLD parameter. When the pool of available jobs is reduced below this number, more jobs are started. Starting jobs takes time. Meanwhile, more requests for work may arrive. Set THRESHOLD to a value of at least one plus the number of requests that can arrive while new jobs are being started
In this example, the value chosen is 10. This is an estimate of arrival of work requests, a guess based on the peak number of jobs in use. This is not an accurate analysis of hard-to-get measurements.

Refer to the notes you took in an earlier step. If the current setting for THRESHOLD is high enough, the peak number waiting is zero. If the peak number waiting is not zero, add this number to your current THRESHOLD value and compare the result to the estimated value based on arrivals. Use the larger value. The sample DSPACTPJ information shows a value of 1 which means the current value for THRESHOLD is too low. The current setting plus one is less than the estimate of 10. For this example, we use the value 10.
Choose a value for the initial number of jobs (INLJOBS) parameter. INLJOBS specifies the number of jobs that are started when the subsystem is started. Also, INLJOBS is part of what the subsystem uses to decide if there are too many prestart jobs waiting for work.
Refer to the notes you took in an earlier step. Use the peak number of prestart jobs in use as the estimate for peak workload, add the value for THRESHOLD, and use the result as the new value for INLJOBS. The DSPACTPJ information shows a peak of 120 prestart jobs in use and we have already chosen a THRESHOLD of 10, so the new value chosen for INLJOBS is 130.
Choose a value for the additional number of jobs (ADLJOBS) parameter. ADLJOBS specifies the additional number of prestart jobs that are started when the number of available prestart jobs drops below the value specified on the Threshold (THRESHOLD) parameter.
When INLJOBS and THRESHOLD are high enough to avoid causing requests to wait, ADLJOBS can be fairly low. If INLJOBS is far below peak workload, ADLJOBS may need to be as high as THRESHOLD. In this example, the chosen value is 5.

Try to avoid large numbers. If you specify a large value for ADLJOBS, the subsystem starts a large number of jobs all at once. This can adversely affect system performance and it delays the subsystem's handling of other work.
Compare the newly chosen values with the values configured in the prestart job entry. To be sure to have enough prestart jobs, use the larger value for each parameter. Change the configured values by using the Change Prestart Job Entry (CHGPJE) command.
```
CHGPJE SBSD(SBSLIB/SUBSYSTEM) PGM(PJPGMLIB/PJPROGRAM)
           INLJOBS(130) THRESHOLD(10) ADLJOBS(5)
```
Continue with the next prestart job entry or the next subsystem description.

Details

Some additional details may help you make good decisions when following this procedure.

If the THRESHOLD value is too small, work waits for new jobs to be started. In some cases, errors occur because requests time out.
Consider an example where THRESHOLD is 2 and there are only two jobs waiting for work. When the next work request arrives, that request is given to one of the waiting jobs and additional jobs are started. In this example, two more requests arrive before the new jobs are ready. The first request is handled by a waiting job. The second request waits for one of the new jobs to become ready. For the example workload, THRESHOLD should be set to at least 3: one to trigger the creation of more jobs plus two for the number of requests that arrive while new jobs are being started.
Because the subsystem starts jobs when they are needed, the subsystem also ends jobs when they are not needed. This happens for prestart job entries that specify a maximum number of uses (MAXUSE) greater than one. The value for the INLJOBS parameter tells the subsystem how many jobs are needed. You need to get INLJOBS set correctly to prevent the subsystem from ending too many jobs.
If the INLJOBS value is too small, the subsystem periodically starts jobs because there are too few and end jobs because there are too many. Moreover, the system incurs the cost of starting new jobs at the time when the system is most busy.
In the sample output from the DSPACTPJ command, the peak number of prestart jobs in use is 120 while the average number of prestart jobs in use is 17.7. This is not a high peak. This is a low average. By default, DSPACTPJ shows what has happened since the subsystem started. The average includes periods when the workload is zero.
Even when you use F13 to reset the statistics and even when you carefully control the sample interval, the average number of prestart jobs in use is likely to be lower than the number you should tune to. A workload may have an average somewhere between 40 and 60 jobs and yet have lots of peaks between 100 and 120 jobs.

When INLJOBS is set to the estimated peak workload plus THRESHOLD, the subsystem does not need to start additional jobs unless the actual workload exceeds the estimated peak workload. If your workload has peaks that are relatively high and relatively infrequent, you may wish to set INLJOBS to a lower number.
The procedure given in this topic assumes that the peak load on a typical day is a typical peak load. If you gather more data, you might be able to produce a better estimate of your workload.
You can use the List Job (QUSLJOB) API or the Open List of Jobs (QGYOLJOB) API to periodically sample your workload. For some workloads, it helps to graph the results. You do not need a perfect prediction for the number of prestart jobs. You only need to be close enough to avoid delays and time outs.
If THRESHOLD and INLJOBS are too large, there are active jobs in the subsystem that are not needed. Starting and ending extra jobs takes more time when starting or ending the subsystem or when starting or ending the prestart job entry.
It is better to use values that are slightly higher than what is needed than to use values that are lower than what is needed. Having a few extra jobs is not a problem because these jobs are waiting for work and do not compete for memory or processors.
Because prestart jobs were first used with communications devices, a request for work is called a program start request and the prestart job shows a status of PSRW (waiting for program start request) when it is waiting for work.