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 is able 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 can display 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 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 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 hardcopy 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 can 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 that are assigned that are assigned that are to a message match any of the routing codes to a console, the message is sent that console.

Disposition of the message is indicated through the descriptor codes that are 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.

Start of changeIf the nonauthorized problem program supplies a descriptor code in the WTO macro, an indicator is inserted at the start of the message. The indicators are an at sign (@) or a blank followed by a plus sign (+). The indicator that is inserted in the message depends on the descriptor code that the user supplies. Table 1 shows the indicator that is used for each descriptor code. End of change

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 memory 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 memory 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 memory dumps.

Start of changeAction messages to the operator can be individually suppressed by the installation. When a program starts WTO or WTOR to send a message, the system determines whether 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 Suppressing messages in z/OS MVS Planning: Operations. End of change

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 on 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 can 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