Add Prestart Job Entry (ADDPJE)

The Add Prestart Job Entry (ADDPJE) command adds a prestart job entry to the specified subsystem description. The entry identifies prestart jobs that may be started when the subsystem is started or when the Start Prestart Jobs (STRPJ) command is entered.

Restrictions:

  1. To use this command, you must have:
    • object operational (*OBJOPR), object management (*OBJMGT), and read (*READ) authority to the specified subsystem description and execute (*EXECUTE) authority to the library containing that subsystem description.
    • object operational (*OBJOPR) and read (*READ) authority to the job description and execute (*EXECUTE) authority to the library containing that job description.
    • use (*USE) authority to the user profile.
  2. Only a user with all object (*ALLOBJ) special authority is allowed to add an entry for which the job description does not exist.

Parameters

Keyword Description Choices Notes
SBSD Subsystem description Qualified object name Required, Positional 1
Qualifier 1: Subsystem description Name
Qualifier 2: Library Name, *LIBL, *CURLIB
PGM Program Qualified object name Required, Positional 2
Qualifier 1: Program Name
Qualifier 2: Library Name, *LIBL, *CURLIB
USER User profile Name, QUSER Optional
STRJOBS Start jobs *YES, *NO Optional
INLJOBS Initial number of jobs 1-9999, 3 Optional
THRESHOLD Threshold 1-9999, 2 Optional
ADLJOBS Additional number of jobs 0-999, 2 Optional
MAXJOBS Maximum number of jobs 1-32000, *NOMAX Optional
JOB Job name Name, *PGM Optional
JOBD Job description Single values: *USRPRF, *SBSD
Other values: Qualified object name		 Optional
Qualifier 1: Job description Name
Qualifier 2: Library Name, *LIBL, *CURLIB
MAXUSE Maximum number of uses 1-1000, 200, *NOMAX Optional
WAIT Wait for job *YES, *NO Optional
POOLID Pool identifier 1-10, 1 Optional
CLS Class Element list Optional
Element 1: Class Single values: *SBSD
Other values: Qualified object name
Qualifier 1: Class Name
Qualifier 2: Library Name, *LIBL, *CURLIB
Element 2: Number of jobs to use class 0-32766, *CALC, *MAXJOBS
Element 3: Class Single values: *NONE, *SBSD
Other values: Qualified object name
Qualifier 1: Class Name
Qualifier 2: Library Name, *LIBL, *CURLIB
Element 4: Number of jobs to use class 0-32766, *CALC, *MAXJOBS
THDRSCAFN Thread resources affinity Single values: *SYSVAL
Other values: Element list		 Optional
Element 1: Group *NOGROUP, *GROUP
Element 2: Level *NORMAL, *HIGH
RSCAFNGRP Resources affinity group *NO, *YES Optional

Subsystem description (SBSD)

Specifies the name and library of the subsystem description to which the prestart job entry is being added. If no library qualifier is given, *LIBL is used to find the subsystem description.

This is a required parameter.

Qualifier 1: Subsystem description

name
Specify the name of the subsystem description to which the prestart job entry is being added.

Qualifier 2: Library

*LIBL
All libraries in the thread's library list are searched until a match is found.
*CURLIB
The current library for the thread is used to locate the object. If no library is specified as the current library for the thread, the QGPL library is used.
name
Specify the subsystem description's library to which the prestart job entry is being added.

Program (PGM)

Specifies the name and library of the program run by the prestart job. This program name is used to match an incoming request with an available prestart job. If the program does not exist when the entry is added, a library qualifier must be specified because the qualified name is kept in the subsystem description.

Note: Two entries with the same program name can exist in a single subsystem description, but they must have different library names.

This is a required parameter.

Qualifier 1: Program

name
Specify the name of the program run by the prestart job.

Qualifier 2: Library

*LIBL
All libraries in the thread's library list are searched until a match is found.
*CURLIB
The current library for the thread is used to locate the object. If no library is specified as the current library for the thread, the QGPL library is used.
name
Specify the library of the program to be run by the prestart job.

User profile (USER)

Specifies the name of the user profile under which the prestart job is initiated. In addition, the current user profile of the prestart job is set to this user whenever the job waits for a request to handle.

Note: When a prestart job is given a request to handle, the current user profile of the job is updated. Refer to the Work Management guide for information on how this profile is determined. This change in current user profile is for authority checking only. None of the other attributes of the user profile, such as the current library (CURLIB) or the initial program to call (INLPGM), are given to the prestart job.

QUSER
The IBM-supplied QUSER user profile is used.
name
Specify the name of the user profile used for the prestart job.

Start jobs (STRJOBS)

Specifies whether the prestart jobs should be started at the time the subsystem is started.

Note: Changing this value when the subsystem is active will produce no effect until the subsystem is ended and started again.

*YES
The prestart jobs are started at the time the subsystem is started.
*NO
The prestart jobs are not started at the time the subsystem is started. The Start Prestart Jobs (STRPJ) command must be used to start these prestart jobs.

Initial number of jobs (INLJOBS)

Specifies the initial number of prestart jobs that are started when the subsystem specified on the Subsystem description (SBSD) parameter is started.

Notes:

  1. The value of this parameter must be less than or equal to the value of the Maximum number of jobs (MAXJOBS) parameter.
  2. The value of this parameter must be greater than or equal to the value of the Threshold (THRESHOLD) parameter.
3
Three prestart jobs are started when the subsystem is started.
1-9999
Specify the number of prestart jobs that are started when the subsystem is started. Valid values range from 1 through 9999.

Threshold (THRESHOLD)

Specifies when additional prestart jobs are started. When the pool of available jobs (jobs available to service requests) is reduced below this number, more jobs (specified on the Additional number of jobs (ADLJOBS) parameter) are started and added to the available pool.

Note: The value of this parameter must be less than or equal to the value specified on the Initial number of jobs (INLJOBS) parameter.

2
When one prestart job is available, the number of jobs specified on the Additional number of jobs (ADLJOBS) parameter are started.
1-9999
Specify the minimum number of prestart jobs that must be available before additional prestart jobs are started. Valid values range from 1 through 9999.

Additional number of jobs (ADLJOBS)

Specifies the additional number of prestart jobs that are started when the number of prestart jobs drops below the value specified on the Threshold (THRESHOLD) parameter.

Note: The value specified on this parameter must be less than the value specified on the Maximum number of jobs (MAXJOBS) parameter.

2
Two additional prestart jobs are started.
0-999
Specify the number of additional prestart jobs to start. Valid values range from 0 through 999.

Maximum number of jobs (MAXJOBS)

Specifies the maximum number of prestart jobs that can be active at the same time for this prestart job entry. This value includes prestart jobs that are servicing a procedure start request, prestart jobs that are waiting to service a procedure start request, and prestart jobs that are being started as a result of reaching the value specified on the Threshold (THRESHOLD) parameter.

Notes:

  1. The value of this parameter must be greater than or equal to the value specified on the Initial number of jobs (INLJOBS) parameter.
  2. The value of this parameter must be greater than the value specified on the Additional number of jobs (ADLJOBS) parameter.
*NOMAX
There is no maximum number of prestart jobs that can be active at the same time.
1-32000
Specify the maximum number of prestart jobs that can be active at the same time. Valid values range from 1 through 32000.

Job name (JOB)

Specifies the name of the prestart job that is started. Prestart jobs are automatically started when the subsystem, specified on the Subsystem description (SBSD) parameter, is started if STRJOBS(*YES) is specified.

*PGM
The job name is the same as the program name specified on the Program (PGM) parameter.
job-name
Specify the name of the prestart job.

Job description (JOBD)

Specifies the qualified name of the job description used for the prestart job. If the job description does not exist when the entry is added, a library qualifier must be specified because the qualified job description name is kept in the subsystem description.

Note: Only a user with all object (*ALLOBJ) special authority is allowed to add or change an entry for which the job description does not exist.

Single values

*USRPRF
The job description name entered in the user profile specified on the User profile (USER) parameter is used.
*SBSD
The job description having the same name as the subsystem description named on the Subsystem description (SBSD) parameter is used.

Qualifier 1: Job description

name
Specify the name of the job description being used for this prestart job.

Qualifier 2: Library

*LIBL
All libraries in the thread's library list are searched until a match is found.
*CURLIB
The current library for the thread is used to locate the object. If no library is specified as the current library for the thread, the QGPL library is used.
name
Specify the job description's library name.

Maximum number of uses (MAXUSE)

Specifies the maximum number of requests that can be handled by each prestart job in the pool before the job is ended.

200
A prestart job for this entry can service a maximum of 200 requests before it is ended and another prestart job is started to take its place.
*NOMAX
There is no maximum number of program start requests that a prestart job can handle. The job is not ended by the subsystem.

Note: Avoid having jobs exist for long periods of time since this can cause the job log to exceed the maximum size. Also avoid situations in which jobs can create more than the maximum number of spooled files, or can exceed the maximum processing unit time or the maximum temporary storage allocation.

1-1000
Specify the maximum number of requests that a prestart job can handle before it is ended. Valid values range from 1 through 1000.

Wait for job (WAIT)

Specifies whether program start requests wait for a prestart job to become available or are rejected if a prestart job is not immediately available when the procedure start request is received.

Note: Refer to the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/ to determine the time-out considerations for the communications type being used.

*YES
Program start requests wait until there is an available prestart job or a prestart job is started to service the request.
*NO
Program start requests are rejected if there is no prestart job immediately available when the procedure start request is received.

Pool identifier (POOLID)

Specifies the subsystem pool identifier that the prestart jobs will run in.

1
The prestart jobs run in pool 1.
1-10
Specify the subsystem pool identifier in which the prestart jobs run. Valid values range from 1 through 10.

Class (CLS)

Specifies the name and library of the classes that the prestart jobs run under and how many prestart jobs run under each class. Jobs start by using the first class specified until the number of jobs specified for the first class is reached. After the number of jobs specified for the first class is reached, jobs are started under the second class. If the class does not exist when the prestart job entry is added, a library qualifier must be specified because the qualified class name is kept in the subsystem description.

Note: Two classes can be specified on this parameter.

Element 1: Class

Single values

*SBSD
The class having the same name as the subsystem description, specified on the Subsystem description (SBSD) parameter, is used for prestart jobs.

Qualifier 1: Class

name
Specify the name of the class being used for prestart jobs.

Qualifier 2: Library

*LIBL
All libraries in the thread's library list are searched until a match is found.
*CURLIB
The current library for the thread is used to locate the object. If no library is specified as the current library for the thread, the QGPL library is used.
name
Specify the library name of the class being used for prestart jobs.

Element 2: Number of jobs to use class

*CALC
The system calculates how many prestart jobs use this class. If only one class is specified and *CALC is specified, all of the jobs use that class. If two classes are specified and *CALC is specified for both, the first class is the value specified on the Maximum number of jobs (MAXJOBS) parameter divided by two, and the second class is the value of the MAXJOBS parameter minus the value calculated for the first class. If a specific number of jobs is specified for either class and *CALC is specified for the other class, the system calculates the difference between MAXJOBS and the specific number of jobs for the *CALC designation.
*MAXJOBS
All of the prestart jobs use the specified class.
0-32766
Specify the number of jobs that use this class. The sum of the values specified for both classes must total the value specified on the MAXJOBS parameter.

Element 3: Class

Single values

*NONE
Specify this value if only one class is used for this prestart job entry.
*SBSD
The class having the same name as the subsystem description, specified on the Subsystem description (SBSD) parameter, is used for prestart jobs.

Qualifier 1: Class

name
Specify the name of the class being used for prestart jobs.

Qualifier 2: Library

*LIBL
All libraries in the thread's library list are searched until a match is found.
*CURLIB
The current library for the thread is used to locate the object. If no library is specified as the current library for the thread, the QGPL library is used.
name
Specify the library name of the class being used for prestart jobs.

Element 4: Number of jobs to use class

*CALC
The system calculates how many prestart jobs use this class. If only one class is specified and *CALC is specified, all of the jobs use that class. If two classes are specified and *CALC is specified for both, the first class is the value specified on the Maximum number of jobs (MAXJOBS) parameter divided by two, and the second class is the value of the MAXJOBS parameter minus the value calculated for the first class. If a specific number of jobs is specified for either class and *CALC is specified for the other class, the system calculates the difference between MAXJOBS and the specific number of jobs for the *CALC designation.
*MAXJOBS
All of the prestart jobs use the specified class.
0-32766
Specify the number of jobs that use this class. The sum of the values specified for both classes must total the value specified on the MAXJOBS parameter.

Thread resources affinity (THDRSCAFN)

Specifies the affinity of threads to system resources.

Single values

*SYSVAL
When the prestart job is started, the thread resources affinity value from the QTHDRSCAFN system value will be used.

Element 1: Group

*NOGROUP
Prestart jobs will have affinity to a group of processors and memory. Secondary threads running under the job will not necessarily have affinity to the same group of processors and memory.
*GROUP
Prestart jobs will have affinity to a group of processors and memory. Secondary threads running under the job will all have affinity to the same group of processors and memory as the initial thread.

Element 2: Level

*NORMAL
A thread will use any processor or memory in the system if the resources it has affinity to are not readily available.
*HIGH
A thread will only use the resources it has affinity to, and will wait until they become available if necessary.

Resources affinity group (RSCAFNGRP)

Specifies whether or not prestart jobs using this entry will be grouped together having affinity to the same system resources (processors and memory). A value of *YES for this parameter will take precedence over the QTHDRSCAFN system value when set to *NOGROUP.

*NO
Prestart jobs that use this entry will not be grouped together.
*YES
Prestart jobs that use this entry will be grouped together such that they will have affinity to the same system resources. Jobs that share data in memory may perform better if they have affinity to the same resources.

Examples

Example 1: Specifying Additional Prestart Jobs 

ADDPJE   SBSD(QGPL/PJSBS)  PGM(QGPL/PGM1)  INLJOBS(15)
         THRESHOLD(5)  ADLJOBS(10)  WAIT(*NO)

This command adds a prestart job entry for the PGM1 program in the QGPL library to the PJSBS subsystem description contained in the QGPL library. The entry specifies that 15 prestart jobs (program PGM1 in the QGPL library) are started when subsystem PJSBS in the QGPL library is started. When the pool of available prestart jobs is reduced to four (because the prestart jobs are servicing requests specified for program PGM1 in the QGPL library), ten additional jobs are started. If no prestart jobs are available for this entry when a request is received, the request is rejected.

Example 2: Specifying Maximum Number of Prestart Jobs 

ADDPJE   SBSD(QGPL/PJSBS)  PGM(QGPL/PGM2)  USER(PJUSER)
         MAXJOBS(100) CLS(QGPL/CLS1 75 QGPL/CLS2 *CALC)
         MAXUSE(50)

This command adds a prestart job entry for the PGM2 program in the QGPL library to the PJSBS subsystem description contained in the QGPL library. The entry specifies that the prestart job for this entry runs under the PJUSER user profile. The maximum number of prestart jobs that can be active at the same time for this entry is 100. Each prestart job in the pool can handle 50 requests before the job is ended. If 100 prestart jobs are active at the same time for this entry, 75 of them would use CLS1 in the QGPL library, and 25 of them would use CLS2 in the QGPL library. If 50 prestart jobs are active at the same time for this entry, all 50 of them would use class CLS1 in the QGPL library.

Error messages

*ESCAPE Messages

CPF1691
Active subsystem description may or may not have changed.
CPF1697
Subsystem description &1 not changed.