Change Routing Entry (CHGRTGE)
| Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
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.
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.
| 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 | ||
| 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-32000, *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.
| Top |
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.
| Top |
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.
| Top |
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.
| Top |
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.
| Top |
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-32000
- 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.
| Top |
Storage pool identifier (POOLID)
Specifies the pool identifier of the storage pool in which the program runs. The pool identifier specified here relates to the storage pools in the subsystem description.
- *SAME
- The pool identifier does not change.
- 1-10
- Specify the identifier of the storage pool defined for this subsystem in which the program runs.
| Top |
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.
| Top |
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.
| Top |
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.
| Top |
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.
| Top |