Add Prestart Job Entry (ADDPJE)

Add Prestart Job Entry (ADDPJE)

Where allowed to run: All environments (*ALL)
Threadsafe: No Parameters
Examples
Error messages

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.
Notes:

The job associated with an active subsystem can only find objects that exist in the system auxiliary storage pool (ASP) or in a basic user ASP. Therefore, objects that are referenced by this command should exist in the system ASP or in a basic user ASP.

Restrictions:

To use this command, 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.

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

Top

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-9999, *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

Top

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.

Top

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.

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.

Top

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.

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.

Top

Start jobs (STRJOBS)

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

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.

Top

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:

The value of this parameter must be less than or equal to the value of the Maximum number of jobs (MAXJOBS) parameter.
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.

Top

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.

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.

Top

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.

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.

Top

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:

The value of this parameter must be greater than or equal to the value specified on the Initial number of jobs (INLJOBS) parameter.
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-9999

Specify the maximum number of prestart jobs that can be active at the same time. Valid values range from 1 through 9999.

Top

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.

Top

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.

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.

Top

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.

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.

Top

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.

Refer to the CL information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/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.

Top

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.

Top

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.

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.

Top

Thread resources affinity (THDRSCAFN)

Specifies the affinity of threads to system resources.
Element 1: Group
Single values

*SYSVAL

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

*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.

Top

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.

Top

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.

Top

Error messages

*ESCAPE Messages

CPF1691

Active subsystem description may or may not have changed.

CPF1697

Subsystem description &1 not changed.

Top

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-9999, *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