Routing the message

You can route a WTO or WTOR message to a console by specifying one or more of the following keywords:
  • ROUTCDE to route messages by routing code
  • CONSID to route messages by console ID
  • CONSNAME to route messages by console name
  • MCSFLAG to route messages by message type.

The ROUTCDE parameter allows you to specify the routing code or codes for a WTO or WTOR message. The routing codes determine which console or consoles receive the message. Each code represents a predetermined subset of the consoles that are attached to the system, and that are capable of displaying the message. The installation must define which routing codes are being received by each console.

You can also use either the CONSID or CONSNAME parameter to route messages. These mutually exclusive parameters let you specify a 4-byte field or register that contains the ID or the pointer to a name of the console that is to receive the message. When you issue a WTO or WTOR macro that uses either the CONSID or CONSNAME parameters with the ROUTCDE parameter, the message or messages will go to all of the consoles specified by both parameters.

The MCSFLAG parameter specifies various attributes of the message, such as whether the message is:
  • For a particular console
  • For all active consoles
  • A command response
  • For the hard-copy log.

Control is returned to the issuer with a return code of X‘20’ and a reason code in register 0. The reason code is equal to the number of active WTO buffers for the issuer's address space. WTO processing may place the WTP invocation in a wait state until WTO buffers are again available.

Note: For the convenience of the operator, you can associate messages with individual keynames. A keyname consists of 1 to 8 alphanumeric characters, and it appears with the message on the console. The keyname can be used as an operand in the DISPLAY R console command, which operators can issue at the console. Use the KEY parameter on the WTO or WTOR macro for this purpose.

During system initialization, each operator's console in the system is assigned routing codes that correspond to the functions that the installation wants that console to perform. When any of the routing codes assigned to a message match any of the routing codes assigned to a console, the message is sent to that console.

Disposition of the message is indicated through the descriptor codes specified in the WTO macro. Descriptor codes classify WTO messages so that they can be properly presented on, and deleted from, display devices. The descriptor code is not printed or displayed as part of the message text.

If the user supplies a descriptor code in the WTO macro, an indicator is inserted at the start of the message. The indicators are: a blank, an at sign (@), an asterisk (*), or a blank followed by a plus sign (+). The indicator inserted in the message depends on the descriptor code that the user supplies and whether the user is a privileged or APF-authorized program or a non-authorized problem program. Table 1 shows the indicator that is used for each descriptor code.

Table 1. Descriptor Code Indicators
Descriptor Code
Non-Authorized
Problem Program
1
@
2
@
3-10
blank+ 
11
@
12-13
blank+ 

A critical eventual action is an action that the operator must perform, as soon as possible, in response to a critical situation during the operation of the system. For example, if the dump data set is full, the operator is notified to mount a new tape on a specific unit. This is considered a critical action because no dumps can be taken until the tape is mounted; it is eventual rather than immediate because the system continues to run and processes jobs that do not require dumps.

Action messages to the operator, which are identified by the @ or * indicator, can be individually suppressed by the installation. When a program invokes WTO or WTOR to send a message, the system determines if the message is to be suppressed. If the message is to be suppressed, the system writes the message to the hardcopy log and the operator does not receive it on the screen. For more information on suppressing messages, see z/OS MVS Planning: Operations.

If a program issues a message with descriptor code of 1 or 2, the message is deleted at address space or task termination. For more information concerning routing and descriptor codes, see any of the volumes of MVS™ System Messages.

If an application that uses WTO needs to alter a message each time the message is issued, the list form of the WTO macro may be useful. You can alter the message area, which is referenced by the WTO parameter list, before you issue the WTO. The message length, which appears in the WTO parameter list, does not need to be altered if you pad out the message area with blanks.

A sample WTO macro is shown in Figure 1.
Figure 1. Writing to the Operator
Single-line WTO  'BREAKOFF POINT REACHED.  TRACKING COMPLETED.',
format            ROUTCDE=14,DESC=7
 
Multiple-   WTO   ('SUBROUTINES CALLED',C),
line format       ('ROUTINE TIMES CALLED',L),('SUBQUER',D),
(list form)       ('ENQUER',D),('WRITER',D),
                  ('DQUER',DE),
                  ROUTCDE=(2,14),DESC=(7,8,9),MF=L