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.

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

Top

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

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

The value specified on this parameter must be greater than or equal to the value specified on the Initial number of jobs (INLJOBS) parameter.
The value specified on this parameter must be greater than the value specified on the Additional number of jobs (ADLJOBS) parameter.
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-9999: Specify the maximum number of prestart jobs that can be active at the same time. Valid values range from 1 through 9999.

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

Two classes can be specified for this parameter.
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.