Change Routing Entry (CHGRTGE)

The Change Routing Entry (CHGRTGE) command changes a routing entry in the specified subsystem description. The routing entry specifies the parameters used to start a routing step for a job. The associated subsystem can be active when the changes are made.

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 the subsystem description.

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
SEQNBR	Routing entry sequence number	1-9999	Required, Positional 2
CMPVAL	Comparison data	Single values: SAME, ANY Other values: Element list	Optional, Positional 3
	Element 1: Compare value	Character value
	Element 2: Starting position	1-80, *SAME
PGM	Program to call	Single values: SAME, RTGDTA Other values: Qualified object name	Optional, Positional 4
	Qualifier 1: Program to call	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
CLS	Class	Single values: SAME, SBSD Other values: Qualified object name	Optional
	Qualifier 1: Class	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
MAXACT	Maximum active routing steps	0-1000, SAME, NOMAX	Optional
POOLID	Storage pool identifier	1-10, *SAME	Optional
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 containing the routing entry that is being changed.

This is a required parameter.

Qualifier 1: Subsystem description

name: Specify the name of the subsystem description for the routing 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 name of the subsystem description's library for the routing entry that is being changed.

Routing entry sequence number (SEQNBR)

Specifies the sequence number of the routing entry that is added or changed. Routing data is matched against the routing entry compare values in ascending sequence number order. Searching ends when a match occurs or the last routing entry is reached. Therefore, if more than one match possibility exists, only the first match is processed.

This is a required parameter.

1-9999: Specifies a sequence number between 1 and 9999.

Comparison data (CMPVAL)

Specifies a value that is compared with the routing data to determine whether this routing entry is used for starting a routing step for the job. If the routing data matches the routing entry compare value, that routing entry is used. A starting position in the starting data character string can be used to specify the starting position in the routing data for comparison against the routing entry compare value.

Single values

*SAME: The comparison value and starting position do not change.
*ANY: Any routing data is considered a match. To specify *ANY, the routing entry must have the highest sequence number value of any routing entry in the subsystem description.

Element 1: Compare value

character-value: Specify a value (any character string not exceeding 80 characters) that is compared with routing data for a match. When a match occurs, this routing entry is used to start a routing step.

Element 2: Starting position

*SAME: The starting position does not change.
1-80: Specify a value, 1 through 80, that indicates which position in the routing data character string is the starting position for the comparison. The last character position compared must be less than or equal to the length of the routing data used in the comparison.

Program to call (PGM)

Specifies the name and library of the program called as the first program run in the routing step. No parameters can be passed to the specified program. The program name can be either explicitly specified in the routing entry, or extracted from the routing data. If a program name is specified in a routing entry, selection of that routing entry results in the routing entry program being called (regardless of the program name passed in an EVOKE function). If the program specified in the EVOKE function is called, *RTGDTA must be specified. If the program does not exist when the routing entry is added or changed, a library qualifier must be specified because the qualified program name is kept in the subsystem description.

Single values

*SAME: The program called does not change.
*RTGDTA: The program name is taken from the routing data that was supplied and matched against this entry. A qualified program name is taken from the routing data in the following manner: the program name is taken from positions 37 through 46, and the library name is taken from positions 47 through 56. Care should be used to ensure that routing entries that specify *RTGDTA are selected only for EVOKE functions on jobs that have specified the program name in the correct position in the routing data.

Qualifier 1: Program to call

name: Specify the name of the program that is run from this routing entry.

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 where the named program is located.

Note: If the program does not exist when this routing entry is changed, a library qualifier must be specified because the qualified program name is kept in the subsystem description.

Class (CLS)

Specifies the name and library of the class used for the routing steps started through this routing entry. The class defines the attributes of the routing step's running environment. If the class does not exist when the routing entry is added, a library qualifier must be specified because the qualified class name is kept in the subsystem description.

Single values

*SAME: The class for this entry does not change.
*SBSD: The class having the same name as the subsystem description, specified on the Subsystem description (SBSD) parameter, is used for routing steps started through this entry.

Qualifier 1: Class

name: Specify the name of the class used for routing steps started through this routing entry.

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 used for routing steps started through this entry.

Maximum active routing steps (MAXACT)

Specifies the maximum number of routing steps (jobs) that can be active at the same time through this routing entry. In a job, only one routing step is active at a time. When a subsystem is active and the maximum number of routing steps is reached, any subsequent attempt to start a routing step through this routing entry fails. The job that attempted to start the routing step is ended, and a message is sent by the subsystem to the job's log.

*SAME: The maximum number of routing steps that can be active at the same time does not change.
*NOMAX: There is no maximum number of routing steps that can be active at the same time and processed through this routing entry. This value is normally used when there is no reason to control the number of routing steps.
0-1000: Specify the maximum number of routing steps that can be active at the same time through this routing entry. If a routing step being started would exceed this number, the job is ended.

Thread resources affinity (THDRSCAFN)

Specifies the affinity of threads to system resources.

Single values

*SAME: The thread resources affinity does not change.
*SYSVAL: When a job is started using this routing entry, the thread resources affinity value from the QTHDRSCAFN system value will be used.

Element 1: Group

*NOGROUP: Jobs using this routing entry 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: Jobs using this routing entry 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 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 jobs using this routing 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: Jobs that use this routing entry will not be grouped together.

*YES: Jobs that use this routing 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: Changing Class and Pool ID

CHGRTGE   SBSD(LIB5/ORDER)  SEQNBR(1478)  CLS(LIB6/SOFAST)  POOLID(3)

This command changes routing entry 1478 in the subsystem description ORDER found in library LIB5. The same program is used, but now it runs in storage pool 3 using class SOFAST in library LIB6.

Example 2: Changing the Name of the Program Called

CHGRTGE   SBSD(T7/PGMR)  SEQNBR(157)  PGM(T7/INTDEV)

This command changes routing entry 157 in the subsystem description PGMR found in library T7. The program INTDEV in library T7 is now called whenever this routing entry is selected. The other routing entry parameters are not changed.