Add Routing Entry (ADDRTGE)

The Add Routing Entry (ADDRTGE) command adds a routing entry to the specified subsystem description. Each routing entry specifies the parameters used to start a routing step for a job. For example, the routing entry specifies the name of the program to run when the routing data that matches the compare value in this routing entry is received.

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.

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

This is a required parameter.

Qualifier 1: Subsystem description

name: Specify the name of the subsystem description to which the routing entry is 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 name of the subsystem description's library to which the routing entry is being added.

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

This is a required parameter.

Single values

*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

1: The comparison between the compare value and the routing data begins with the first character in the routing data character string.
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.

This is a required parameter.

Single values

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

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

*SBSD: The class having the same qualified 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 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.

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

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.

1: Storage pool 1 of this subsystem is the pool in which the program runs.
1-10: Specify the identifier of the storage pool defined for this subsystem in which the program runs.

Thread resources affinity (THDRSCAFN)

Specifies the affinity of threads to system resources.

Element 1: Group

Single values

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

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

*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: Adding to the Routing Portion of a Subsystem Description

ADDRTGE   SBSD(ORDLIB/PERT)  SEQNBR(46)  CMPVAL(WRKSTN2)
          PGM(ORDLIB/GRAPHIT)  CLS(MYLIB/AZERO)  MAXACT(*NOMAX)
          POOLID(2)

This command adds routing entry 46 to the subsystem description PERT in the ORDLIB library. To use routing entry 46, the routing data must start with the character string WRKSTN2 starting in position 1. Any number of routing steps can be active through this entry at any one time. The program GRAPHIT in the library ORDLIB is to run in storage pool 2 by using class AZERO in library MYLIB.

Example 2: Adding to the Subsystem Description

ADDRTGE   SBSD(QGPL/ABLE)  SEQNBR(5)  CMPVAL(XYZ)
          PGM(QGPL/REORD)  CLS(LIBX/MYCLASS)  MAXACT(*NOMAX)

This command adds routing entry 5 to the subsystem description ABLE in the QGPL library. The program REORD in library QGPL is started and uses the class MYCLASS in LIBX when a compare value of XYZ (starting in position 1) is matched in the routing data. The program runs in storage pool 1, and there is no maximum on the number of active routing steps allowed.