Change Prestart Job Entry (CHGPJE)

The Change Prestart Job Entry (CHGPJE) command changes a prestart job entry in the specified subsystem description.

The subsystem may be active when the prestart job entry is changed. Changes made to the entry when the subsystem is active are reflected over time. Any new prestart jobs started after the command is issued use the new job-related values. This command identifies prestart jobs that are started when the subsystem is started or when the Start Prestart Jobs (STRPJ) command is issued.

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 change 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, *SAME Optional
STRJOBS Start jobs *SAME, *YES, *NO Optional
INLJOBS Initial number of jobs 1-9999, *SAME Optional
THRESHOLD Threshold 1-9999, *SAME Optional
ADLJOBS Additional number of jobs 0-999, *SAME Optional
MAXJOBS Maximum number of jobs 1-32000, *SAME, *NOMAX Optional
JOB Job name Name, *SAME, *PGM Optional
JOBD Job description Single values: *SAME, *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, *SAME, *NOMAX Optional
WAIT Wait for job *SAME, *YES, *NO Optional
POOLID Pool identifier 1-10, *SAME Optional
CLS Class Element list Optional
Element 1: Class Single values: *SAME, *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, *SAME, *CALC, *MAXJOBS
Element 3: Class Single values: *SAME, *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, *SAME, *CALC, *MAXJOBS
THDRSCAFN Thread resources affinity Single values: *SAME, *SYSVAL
Other values: Element list
Optional
Element 1: Group *NOGROUP, *GROUP
Element 2: Level *NORMAL, *HIGH
RSCAFNGRP Resources affinity group *SAME, *NO, *YES Optional

Subsystem description (SBSD)

Specifies the name and library of the subsystem description that contains the prestart job entry being changed.

This is a required parameter.

Qualifier 1: Subsystem description

name
Specify the name of the subsystem description of the prestart job entry that is being changed.

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 of the prestart job entry that is being changed.

Program (PGM)

Specifies the name and library of the program that identifies the prestart job entry that is changed. This program name is used to match an incoming request with an available prestart job. Two entries with the same program name can exist in a single subsystem description, but they must have different library names. 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.

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

*SAME
The value of this parameter does not change.
name
Specify the name of the user profile used for the prestart job.

Start jobs (STRJOBS)

Specifies whether the prestart jobs are started at the time the subsystem is started.

*SAME
The start prestart jobs value does not change.
*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 is 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 specified on this parameter must be less than or equal to the value specified on the Maximum number of jobs (MAXJOBS) parameter.
  2. The value specified on this parameter must be greater than or equal to the value specified on the Threshold (THRESHOLD) parameter.
*SAME
The number of prestart jobs that are started when the subsystem is started does not change.
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 a 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. This number is checked after a prestart job is attached to a procedure start request.

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

*SAME
The value of this parameter does not change.
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 of this parameter must be less than the value specified on the Maximum number of jobs (MAXJOBS) parameter.

*SAME
The additional number of prestart jobs that are started does not change.
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.

Notes

  1. The value specified on this parameter must be greater than or equal to the value specified on the Initial number of jobs (INLJOBS) parameter.
  2. The value specified on this parameter must be greater than the value specified on the Additional number of jobs (ADLJOBS) parameter.
  3. If the value specified on this parameter is changed, the value specified on the Class (CLS) parameter might also need to be changed.
*SAME
The number of prestart jobs that can be active at the same time does not change.
*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.

*SAME
The job name does not change.
*PGM
The job name is the program name specified on the Program (PGM) parameter.
name
Specify the name of the prestart job.

Job description (JOBD)

Specifies the name and library of the job description that is used for the prestart job. If the job description does not exist when the entry is changed, 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

*SAME
The job description does not change.
*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 before the subsystem ends the job in a controlled manner by issuing an End Job (ENDJOB) command with a value of *CNTRLD on the How to end (OPTION) parameter.

*SAME
The value does not change.
*NOMAX
There is no maximum number of program start requests that a prestart job can handle. The job is not ended by the subsystem.
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 manual for the communications type being used to determine the timing considerations for program start requests.

*SAME
The value for this parameter does not change.
*YES
Program start requests wait until there is an available prestart job, or until a prestart job is started, to handle the request.
*NO
Program start requests are rejected if a prestart job is not immediately available when the procedure start request is received.

Pool identifier (POOLID)

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

*SAME
The subsystem pool identifier in which prestart jobs run does not change.
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 should run using 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, then jobs are started using the second class. If the class does not exist when the entry is added, a library qualifier must be specified because the qualified class name is kept in the subsystem description.

Notes

  1. Two classes can be specified for this parameter.
  2. If the value specified on the Maximum number of jobs (MAXJOBS) parameter is changed, the value for the number of jobs specified on this parameter might need to be changed. If *CALC or *MAXJOBS is specified, the system recalculates the value for the number of jobs to use the specified class.

Element 1: Class

Single values

*SAME
The class does not change.
*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

*SAME
The number of jobs to use this class does not change.
*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

*SAME
The second class, if previously specified, does not change.
*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

*SAME
The number of jobs to use the second class does not change.
*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

*SAME
The thread resources affinity does not change.
*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.

*SAME
The resources affinity group does not change.
*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

CHGPJE   SBSD(QGPL/PJSBS)  PGM(QGPL/PGM1)  STRJOBS(*NO)
         THRESHOLD(1)  ADLJOBS(1)

This command changes the prestart job entry for the PGM1 program in the QGPL library in the PJSBS subsystem description contained in the QGPL library. The prestart jobs associated with this entry are not started the next time the PJSBS subsystem description in the QGPL library is started. The STRPJ command is needed to start the prestart jobs. When more jobs need to be started, one additional job is started.

Error messages

*ESCAPE Messages

CPF1619
Subsystem description &1 in library &2 damaged.
CPF1691
Active subsystem description may or may not have changed.
CPF1697
Subsystem description &1 not changed.