$T DEStid

Function

To change the JES2 route code associated with the specified symbolic destination name.

To distinguish between destids that share the same routing, installations should specify PRIMARY=YES for one of them (either on the DESTID(jxxxxxxx) initialization statement or on this command).

For example, the following destids share the same routing. DESTID(JOHN) specifies PRIMARY=YES. JES2 consistently displays the symbolic name JOHN for output routed to this destination.

DESTID(REMOTE5) DEST=R5
DESTID(JOHN) DEST=N1.R5,PRIMARY=YES

PRIMARY=YES is necessary for application products such as SDSF.

Note:

None of the route codes specified on the DEST= of this command are affected by the DESTDEF initialization statement or the $T DESTDEF command.
If any parameters on the DESTDEF initialization statement specify USER and multiple destids can match the routing, then at least one of these multiple destids must specify PRIMARY=YES.

One or more parameters on this command accepts wild cards. Parameter descriptions will note that.

Syntax


>>-$T--DEStid--+-'--xxxxxxxx--'---------------+----------------->
               |    .-,------------------.    |   
               |    V                    |    |   
               '-(----+-xxxxxxxx-------+-+--)-'   
                      '-'--xxxxxxxx--'-'          

>--+---------------------------------+-------------------------->
   '-| Selection limiting keywords |-'   

>--+---------------------------+-------------------------------><
   '-| Modification keywords |-'   

Modification keywords

|--+--------------------------+--+------------------------+-----|
   '-,--DEST--=--+-nodename-+-'  '-,--PRIMARY--=--+-No--+-'   
                 '-Nnnnn----'                     '-Yes-'     

Selection limiting keywords

|--+------------------------------------+-----------------------|
   '-,----/----PRIMARY--+-=--+--+-No--+-'   
                        '-^=-'  '-Yes-'

Parameters

xxxxxxxx

Specifies the 1 to 8 alphanumeric or special ($, #, or @) character symbolic destination name affected by this statement. You may specify a particular symbolic destination name or wild cards for a generic name (for example, POK* or *). See Using wildcards for additional information.

DEST={nodename|Nnnnn}

Specifies a route code JES2 can use to route data.

When specifying only the node (first-level destination):

nodename|Nnnnn

References only the nodal portion (first-level destination) of a JES2 route code.

nodename: Specify a symbolic node name. For example, if NODE(10) is defined with NAME=ALBANY on the NODE(nnnn) initialization statement, then an installation can create a DESTID(NYCAP) with DEST=ALBANY.
Nnnnn: Specify N followed by a numeric value (1-32767). For example, DESTID(NYCAP),DEST=N10.

When specifying only the destination at a node (second-level destination):

References only the destination at a node (second-level destinations).

When these destids are referenced, users must specify either an explicit first-level destination or allow JES2 to assign a default first-level destination. JES2 determines the first-level destination from one of the following:

/*ROUTE PRT JES2 control statement
/*ROUTE PUN JES2 control statement
The output route code associated with the device through which the job entered the system.

For example, DESTID(REMOTE5),DEST=R5 defines a second-level destination. Using the destids DESTID(NYCAP) DEST=ALBANY and DESTID(NYCAP) DEST=N10 as specified on DESTID(jxxxxxxx) initialization statements, JCL can route a data set to R5 at N10 by specifying DEST=NYCAP.REMOTE5.

However, if the JCL only specifies DEST=REMOTE5, the nodal portion of the destination is obtained from the default routing of the job. (A job submitted from N10 without any /*ROUTE JES2 control statements has a default nodal routing of N10, regardless of where in the network it executes.)

Valid destinations:

LOCAL|ANYLOCAL: Data is not associated with any specific routing.
Rmmmm|RMmmmm|RMTmmmm: Specify R, RM, or RMT, followed by a numeric value (0 - 32767). For example, ‘R17' represents remote work station 17.
Unnnn: Specify U followed by a numeric value that can range from 1 through the value specified on the LOCALNUM= parameter of the DESTDEF initialization statement. For example, ‘U19' represents special local routing 19. Wild cards are not supported.
Use the LOCALNUM= parameter on the DESTDEF initialization statement to specify the highest number for a special local route code. JES2 assumes that numbers beyond this range are userids.
userid: Specify a 1 to 8 character string that is interpreted on the destination node. For example, the string ‘TANYA' represents a userid (assuming that there are no destids that define TANYA at the destination node).

When specifying both the node and a destination at that node (first and second level destinations):

NnnnnRmmmm|node.destination

Allows an installation to define the complete JES2 route code (destination at a specified node). JES2 does not use information from the default routing.

NnnnnRmmmm

Specify ‘N' followed by a numeric value (1 - 32767), then ‘R' followed by a numeric value (0 - 32767). For example, N5R7 indicates remote 7 at node 5.

node.destination

Specify a first-level destination, followed by a period (.), followed by either a second-level destination or a complete destination.

If ‘destination' is a second-level destination, the routing associated with this destid is the composite of ‘node' and ‘destination'.

For the following examples, assume that node 1 is the local node:

‘N1.R3' indicates data routed to remote 3 at the local node.
‘N2.R5' indicates data routed to whatever ‘R5' is at node 2.
‘N5.BOB' indicates data is routed to whatever ‘BOB' is at node 5.

If ‘destination' is a complete destination, the final routing associated with this destid depends on ‘node'.

For the following examples, assume that node 1 is the local node:

‘N2.N2R3' indicates data routed to remote 3 at node 2 because the first-level destination of ‘destination' matches ‘node'.
‘N5.N2R3' indicates data routed to ‘N2R3' at node 5 because the first-level destination of ‘destination' does not match ‘node' and ‘node' is not the local node. If node 5 has not explicitly defined ‘N2R3', node 5 routes the data to destination ‘R3' at node 2.
‘N1.N5R3' results in an error because the first-level destination of ‘destination' does not match ‘node' and ‘node' is the local node.

Note that you can use existing destids to define additional destids. For example, assume that the following destids are defined:

DESTID(ALBANY)  DEST=N10
DESTID(REMOTE5) DEST=R5

You can define on the $T DESTID(jxxxxxxx) command:

DESTID(CAPITOL),DEST=ALBANY.REMOTE5

The routing associated with ‘CAPITOL' is N10.R5.

PRIMARY={No|Yes}

Specifies whether (YES) or not (NO) this destid for job and SYSOUT routing is to be displayed. Use this parameter if multiple destids have the same routing.

When searching for a destid to display for a job's or SYSOUT's routing, JES2 selects:

Node name (destid with STATUS=NODENAME) if routed to a node.
First destid found that specifies PRIMARY=YES.
If only one destid is found, that destid is used.
If multiple destids are found, no destid is used (and routing is displayed explicitly).

If USER is specified for either the Ndest=, Udest=, or R|RM|RMTdest= parameters on the DESTDEF initialization statement and multiple destids can match the routing of a job or SYSOUT data set, then at least one of these multiple destids must specify PRIMARY=YES. If not, products such as SDSF may have problems altering the routing of a job or SYSOUT data set to any of these multiply defined destids.

Because PRIMARY=YES can affect SDSF's security procedures, consult SDSF Guide and Reference before using this parameter.

Authority Required

This command requires system authority. The description of the $T RDRnn command explains how to ensure that the authority of the appropriate MVS™ system command group is assigned.

This command requires control security access authority. For a description of assigning command input authority, see z/OS JES2 Initialization and Tuning Guide, SA32-0991.

Processing Considerations

You cannot alter a destid that is a node name (STATUS=DESTID). (Use the $D DESTID command to display the status of a destid). Change the node name first (to make it inactive) through the $T NODE(nnnn),NAME= command, then change the destid.

Scope

Single member. This command will be in effect for this member only.

Depending on your installation's setup, however, you might want this command to be applied to all members of the MAS (to ensure a consistent environment across the MAS). If so, you can use the MVS ROUTE *ALL command to issue this command to all active members (if the JES2 command character is the same on all members). See z/OS MVS System Commands, SA38-0666 for more information on using the ROUTE *ALL command.

Messages

The $HASP822 message displays the current values of all the parameters on the DEStid initialization statement.

Examples

 1   $t destid(houston),dest=n3

  $HASP822 DESTID(HOUSTON)   DEST=N3,STATUS=DESTID,PRIMARY=NO

Users and operators can use the symbolic destination name “HOUSTON” to refer to any local device at node 3. The STATUS= keyword indicates that the symbolic name HOUSTON does not match the name of a node.

In the installation described for example 2, JES2 displays multiple destid‘s with a DEST= routing of special local 'U3'.

$d destid(*),dest,primary

  $HASP822 DESTID(CLW2Z18)   DEST=N1.U3,PRIMARY=NO
  $HASP822 DESTID(JPK2Z37)   DEST=N1.U3,PRIMARY=NO
  $HASP822 DESTID(RMJ2AA18)  DEST=N1.U3,PRIMARY=NO
  $HASP822 DESTID(SJG2Z19)   DEST=U3,PRIMARY=NO

Note that without specifying ‘PRIMARY=YES' on any of the above, the SYSOUT is displayed (through the $L J command below) with the explicit route code, not with a DESTID:

$DO j55,all

  $HASP686 OUTPUT(NEWJOBS)   OUTGRP=1.1.1,BURST=NO,FCB=****,
  $HASP686                   FLASH=****,FORMS=STD,HOLD=(NONE),
  $HASP686                   HOLDRC=,OUTDISP=KEEP,PAGES=,
  $HASP686                   PRIORITY=144,PRMODE=LINE,QUEUE=X,
  $HASP686                   RECORDS=(72 OF 72),ROUTECDE=U3
  $HASP686                   SECLABEL=SYSHIGH,TSOAVAIL=YES,UCS=****,
  $HASP686                   USERID=BERNER,WRITER=

$t destid(cam2x37),dest=u3,primary=yes

$HASP822 DESTID(CAM2X37)   DEST=U3,STATUS=DESTID,PRIMARY=YES

Users and operators can use the symbolic destination name “CAM2X37” to refer to the special local printer at U3. The STATUS= keyword displayed in the $HASP822 message indicates that the symbolic name CAM2X37 does not match the name of a node.

Note that by specifying PRIMARY=YES, JES2 displays the SYSOUT (through the $L J command) with the destid ‘CAM2X37' as the destination for the SYSOUT:

$DO j55,all

  $HASP686 OUTPUT(NEWJOBS)   OUTGRP=1.1.1,BURST=NO,FCB=****,
  $HASP686                   FLASH=****,FORMS=STD,HOLD=(NONE),
  $HASP686                   HOLDRC=,OUTDISP=KEEP,PAGES=,
  $HASP686                   PRIORITY=144,PRMODE=LINE,QUEUE=X,
  $HASP686                   RECORDS=(72 OF 72),ROUTECDE=CAM2X37
  $HASP686                   SECLABEL=SYSHIGH,TSOAVAIL=YES,UCS=****,
  $HASP686                   USERID=BERNER,WRITER=