Parameters

sysname

The system name (1 to 8 characters) that will receive and process the command.

MVS™ returns the command response to the issuing console (inline area for an MCS, HMCS or SMCS console) unless redirected by the L= parameter on the routed command.

text

The system command and specific operands of the command being routed. Do not code any leading blanks before the text.

T=

Specifies an optional timeout interval. T= is valid with *ALL, *OTHER, sysgrpname, or a list of system names or sysgrpnames. You can specify a value from 0 to 999. This value indicates the maximum number of seconds MVS waits for responses from each system before aggregating the responses.

If you specify T=0, MVS does not aggregate command responses, but individually sends responses to the originator.

Note:

IBM® recommends that you specify T=0 when you are routing the START and STOP commands to multiple systems. This is because the system does not collect aggregate responses for routed START and STOP commands. If you attempt to do so (if T= is nonzero), the system states that there is “no response” from all of the systems, and all the START and STOP command responses are displayed inline.
IBM does not recommend that you specify T=0 for most DISPLAY commands. Command responses from most DISPLAY commands appear in an out-of-line display area, and the responses from multiple DISPLAY commands can be written into the same area one right after the other, so that only the last one is readable. If there is no display area defined, or if L=Z is used, the responses are inline, but will probably roll off the console. Responses from ROUTE with T=0 and a DISPLAY command specified could be useful to an automation program and as a hardcopy record, but not for a human operator.

*ALL

Specifies that the command is to be routed to all systems in the sysplex.

*OTHER

Specifies that the command is to be routed to all systems in a sysplex except the system on which the command is entered.

If you enter a ROUTE *OTHER command on a system that is not a member of a sysplex, or if you enter ROUTE *OTHER from a system that is a member of a sysplex in which no other systems are active, MVS issues message IEE413I.

sysgrpname

Specifies that the command will be routed to a subset of systems in the sysplex. The sysgrpname can be 1 to 8 characters and represents the set of systems to which the command is to be routed. System group names are defined by the installation. For information on defining system group names, see z/OS MVS Planning: Operations.

(sysname[,sysgrpname,sysname...])

Specifies that the command is to be routed to a list of systems or system groups, or both. System group names are defined by your installation.

If you route a command to a list of systems or system groups, and none of the systems or system groups is active, the system issues message IEE413I.

L=a, name, or name-a

Specifies the display area (a), console name (name), or both (name-a) where the display will appear.

For the ROUTE command, you can specify the L= operand as follows:

When routing a command to only one system, you can specify the L= operand only if supported by the routed command. For example, the following is valid because the D C command supports the L= operand:
```
RO sys1,D C,L=con1
```
The following is not valid because the D T command does not support the L= operand:
```
RO sys1,D T,L=con1
```
When routing a command to all systems, or to a named subset of systems, the L= operand is supported if aggregation of responses occurs (the timeout interval is not zero). For example, the following is valid:
```
RO T=20,*ALL,D T,L=con1
```

If you do not specify the L= option, the system displays the command responses in the first available display or message area of the console on which you entered the ROUTE command.

Note: Do not use system symbols on the L= parameter when aggregating command responses. For more information about specifying system symbols when routing commands, see Using system symbols in ROUTE commands.

Example 1:

To route a DISPLAY UNITS command for device 320 on system SY4 and have the response returned to the issuing console, enter:

ROUTE SY4,D U,,,320,1

Example 2:

To route a DISPLAY UNITS command to system SY1 and have the response returned to the console named CON1A, enter:

ROUTE SY1,D U,L=CON1A

Example 3:

To change the OPNOTIFY value on all systems in the sysplex, enter:

ROUTE *ALL,SETXCF COUPLE,OPNOTIFY=15

Example 4:

To start JES2 on all systems in the sysplex, enter:

ROUTE T=0,*ALL,S JES2

Note: The system does not aggregate command responses for routed START and STOP commands. If you attempt to do so (if T= is nonzero), the system states that there is “no response” from all of the systems, and all the START and STOP command responses are displayed inline.

Example 5:

After JES3 initialization completes on the global, to start JES3 on all local processors in the sysplex, from a console associated with the global, enter:

ROUTE T=0,*OTHER,S JES3

Example 6:

To issue D A on system SY1 and system SY4, where TEST is a system group name representing both system SY1 and system SY4, enter:

ROUTE TEST,D A

Example 7:

To issue D A on the systems represented by TEST and have the aggregated responses received within 10 seconds, enter:

ROUTE T=10,TEST,D A

Example 8:

To issue D T (DISPLAY TIME) to be processed on system SYS1, enter:

ROUTE SYS1,D T

The system returns this information:

SYS1  IEE136I LOCAL: TIME=09.59.49 DATE=1993.257  GMT: TIME=13.59.43
     DATE=1993.257

Example 9:

To route the command D T (DISPLAY TIME) to be processed on all systems (SYS1, SYS2, and SYS3), enter:

ROUTE T=0,*ALL,D T

The system returns the following information:

SYS1  IEE136I LOCAL: TIME=10.00.59 DATE=1993.257  GMT: TIME=14.00.59
 DATE=1993.257
SYS3  IEE136I LOCAL: TIME=10.00.59 DATE=1993.257  GMT: TIME=14.00.59
 DATE=1993.257
SYS2  IEE136I LOCAL: TIME=10.00.59 DATE=1993.257  GMT: TIME=14.00.59
 DATE=1993.257

Note:

Because T=0 is specified, the information is not aggregated, but individually returned.
Most DISPLAY commands produce multi-line command responses in an out-of-line display area on the console. Such command responses are written into the same area. IBM does not recommend specifying such DISPLAY commands on the ROUTE command when T=0 is in effect. However, because the D T (DISPLAY TIME) command produces a single-line command response, you can successfully specify the D T command on the ROUTE command, as shown in this example.

Example 10:

To route the command D T (DISPLAY TIME) to all systems and receive an aggregated response, use the T= parameter and enter:

ROUTE T=5,*ALL,D T

The system returns the following aggregated information:

IEE421I RO *ALL,D T                  FRAME LAST   F      E   SYS=SYS1
SYSNAME  RESPONSES ---------------------------------------------------
SYS1     IEE136I LOCAL: TIME=10.06.48 DATE=1993.257  GMT:
        TIME=14.06.48 DATE=1993.257
SYS2     IEE136I LOCAL: TIME=10.06.48 DATE=1993.257  GMT:
        TIME=14.06.48 DATE=1993.257
SYS3     IEE136I LOCAL: TIME=10.06.48 DATE=1993.257  GMT:
        TIME=14.06.48 DATE=1993.257

Example 11:

This example illustrates what can happen when the timeout interval occurs before all the command responses are received for aggregation. If you issue the ROUTE command to vary device 414 offline on all systems:

ROUTE T=1,*ALL,V 414,OFFLINE

and system SYS2 does not respond within one second (the timeout interval) MVS cannot include the command response from SYS2 with the other command responses.

First, MVS lists the systems from which no response was received in time for aggregation.

IEE421I RO *ALL,V 414,OFFLINE        
NO RESPONSE RECEIVED FROM THE FOLLOWING SYSTEM(S):
SYS2

After the operator scrolls forward to the second frame of message IEE421I, MVS displays the aggregated response:

IEE421I RO *ALL,V 414,OFFLINE        
SYSNAME  RESPONSES ---------------------------------------------------
SYS1     IEF281I 0414 NOW OFFLINE
SYS3     IEE303I 0414     OFFLINE

Example 12:

Route the $SPRT1 command to all systems in a sysplex except the system on which the command is entered:

ROUTE *OTHER,$SPRT1

Example 13:

Quiesce systems S0 and S9 from system S1:

RO (S0,S9),QUIESCE

Example 14:

Quiesce systems S0 and the subset of systems represented by system group name G8:

RO (S0,G8),QUIESCE

If the ROUTE *OTHER command is issued on a system which is not a member of a SYSPLEX, or a system that is a member of a sysplex but no other systems are active members in the sysplex, a message is issued (see messages section for details). This same message will be issued if a list of systems/groups is specified and none of the systems/groups represent at least one active system.