PIPE ROUTE

Syntax

ROUTE

Command Description

The ROUTE stage sends messages to another task. The target task is identified by a standard NetView® label or by the authorized receiver (AUTHRCVR), as specified by the previous ASSIGN command.

If you use the label syntax, the target task can be local (in the same NetView program) or remote (in another NetView program). For a remote target, the message is routed similarly to a RMTCMD response by SNA or by TCP/IP, depending on the domain name. For more information on the domain name specification, see the RMTSYN statement in the CNMSTYLE member.

If an argument is not specified, ROUTE reads target specifications from the secondary input. One message is read from the secondary input for each message routed. If the message read from the secondary has multiple lines, a single message from the primary stream is routed to each target specified.

The message is also written to an output stream under the following conditions:

If the routing is successful, the message is written to the primary output stream, if connected.
If the routing is not successful, the message is written to the secondary output, if defined and connected. If no secondary output was defined, the message is written to the primary output, if connected.

Note: When multiple targets are specified, the operation is regarded as successful if any one of the message routings is successful. For a remote target, the routing is successful if SNA or IP routing methods accept the message for routing. A subsequent failure (for example the domain is inactive or security prevents the session from being established), is reported by messages to the authorized receiver.

Streams

Stream Type	Number Supported
Input	2
Output	2

Termination Conditions

ROUTE terminates when the primary input stream disconnects.

If an argument is not specified and the target is from the secondary input stream, ROUTE ends when either the primary or secondary input stream disconnects.

Operand Descriptions

label:

Specifies a valid label. A label can be supplied to the ROUTE stage as a parameter or as input from the secondary input stream. The label is defined and used the same way as command labels used with CORRCMD stage with the following exceptions:

An asterisk (*) supplied for the operator name denotes the current operator ID when the ROUTE takes place.
An asterisk (*) supplied for the netid denotes the current netid that is used as the destination.
If any value is supplied for the netid, even an asterisk (*), the value supplied for the domain after the period (.) and before the slash (/) is not interpreted as a RMTALIAS. Therefore, to have the value supplied for the domain to be interpreted as a RMTALIAS, do not specify the netid value or the subsequent period.
A percent sign (%) can be used in place of the oper_id to indicate to send the message to the authorized receiver at the target domain, as indicated by the netid and luname.
An exclamation (X'5A') can be used in place of the oper_id to indicate that the message becomes a bulletin at the target domain, as indicated by the netid and luname.

AUTHRCVR

Indicates the messages are sent to the authorized receiver in the local domain.

BULLETIN

Indicates a copy of the message is sent to every operator and autotask currently logged on. A copy of the message is also issued to every operator who subsequently logs on. The message type (HDRMTYPE) of each line of the message is set to HDRTYPBL (lower case 'b').

You can cancel a bulletin message by issuing a DOM command against it. For example, from an operator station that still has a copy of the message (ABC123E), issue the following command:

PIPE HELDMSG | LOCATE /ABC123E/ | NETV DOM CURMSG

Note: The extent of automation of BULLETIN messages is controlled by the AUTOBLTN keyword on the DEFAULTS command. Refer to the DEFAULTS command documentation for more information.

Usage Notes

To send messages to a remote domain over IP, the IP address of the domain must be defined using the RMTSYN statement in the CNMSTYLE member.
The authorized receiver is determined by the individual message. For more information, see the online help for the ASSIGN command (PRI and SEC keywords).

Example: Sending a Message to OPER1

To send a message to OPER1, enter:

PIPE LITERAL /Hello/ | ROUTE /OPER1:

Example: Sending Multiple Messages

To send multiple messages to operators OPER1, OPER2, and NETOP1 from a REXX Exec:

    dest.1 = '/OPER1:'
    dest.2 = '/OPER2:'
    dest.3 = '/NETOP1:'
    dest.0 = 3
    'PIPE (END &)',
    '| NETVIEW LIST TASK', /* generate "a few" messages         */
    '| A: ROUTE ',         /* route to destination read from    */
                  ,        /* below end of main pipeline        */
    '& STEM dest.',        /* read in the three labels          */
    '| COLLECT',           /* MLWTO ->"route one message to all"*/
    '| DUP *',             /* make copies until next stg disc   */
    '| A:'                 /* feed msgs with labels up to ROUTE */

Example: Sending a Message to the Authorized Receiver

To send a message to the authorized receiver at CNM02, enter:

PIPE LITERAL /ABC123I more and more/ | ROUTE CNM02/%: