ADDRTGE (Add Routing Entry)

ADDRTGE Command syntax diagram

 

Purpose

The Add Routing Entry (ADDRTGE) command adds a routing entry to the specified subsystem description. The associated subsystem can be active at the time. Each routing entry specifies the parameters used to start a routing step. 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.

Restriction: To use this command, the user must have object operational and object management authorities for the subsystem description.

 

Required Parameters

SBSD

Specifies the qualified name and library of the subsystem description to which the routing entry is added.

The name of the subsystem description can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

subsystem-description-name: Specify the name of the subsystem description to which the routing entry is added.

SEQNBR

Specifies the sequence number of the routing entry that is added. 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 compared. Therefore, if more than one match possibility exists, only the first match is processed. Specify a unique sequence number (ranging from 1 through 9999) that identifies the routing entry.

CMPVAL

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

Element 1: Comparing Values with Routing Data

*ANY: Any routing data is considered a match. To specify *ANY, the routing entry must have the highest SEQNBR value of any routing entry in the subsystem description.

compare-value: Specify a value (any character string not exceeding 80 characters in length) that is compared with routing data for a match. When a match occurs, this routing entry is used to start a routing step. A starting position in the routing data character string can be specified for the comparison; if no position is specified, 1 is assumed.

Element 2: Starting Position

1: The comparison between the compare value and the routing data begins with the first position in the routing data character string.

starting-position: Specify a value, ranging from 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.

PGM

Specifies the qualified name 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, PGM(*RTGDTA) must be specified in the routing entry. If the program does not exist when the routing entry is added, a library qualifier must be specified because the qualified program name is retained in the subsystem description.

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

The name of the program can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

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

 

Optional Parameters

CLS

Specifies the qualified name of the class used for the routing steps started through this routing entry. The class defines the attributes of the running environment for processing the routing step associated with this routing entry. If the class does not exist when this routing entry is changed, a library qualifier must be specified because the qualified class name is retained in the subsystem description. More information is in Commonly used parameters.

*SBSD: The class having the same qualified name as the subsystem description specified by the SBSD parameter is used for routing steps started through this entry.

The name of the class can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

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

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 attempts to start a routing step through this routing entry fails. If the routing data is entered interactively, an error message is sent to the user. Otherwise, the job is ended, and a message is sent by the subsystem to the job's log. More information on this parameter is in Commonly used parameters.

*NOMAX: There is no maximum number of routing steps that can be active at the same time and be processed through this routing entry. This value is normally used when there is no reason to control the number of routing steps.

maximum-active-jobs: Specify the maximum number of routing steps that can be active at the same time and be processed through this routing entry. If a routing step being started would exceed this number, the job is implicitly ended.

POOLID

Specifies the pool identifier of the storage pool in which the program runs.

1: Storage pool 1 of this subsystem is the pool in which the program runs.

pool-identifier: Specify the identifier of the storage pool defined for this subsystem in which the program runs. Valid values range from 1 through 10.

Examples for ADDRTGE

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 routing portion of 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 the general purpose library 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.

Error messages for ADDRTGE

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