Description

Requirements for the caller are:

• The WTOR macro can issue only single-line messages.
• The caller cannot have an EUT FRR established.

Before issuing the WTOR macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

None.

The standard form of the WTOR macro is written as follows:

The parameters are explained as follows:

‘msg’,reply addr,reply length,ecb addr

TEXT=(text addr,reply addr,reply length,ecb addr)

‘msg’ is used to write the message to the operator. The message must be enclosed in apostrophes, which do not appear on the console. It can include any character that can be used in a character (C-type) DC instruction. When a program issues a WTOR macro, the system translates the text; only standard printable EBCDIC characters are passed to the display devices. All other characters are replaced by blanks. A list of these EBCDIC characters is provided in z/OS MVS Programming: Assembler Services Guide. Unless the console has dual-case capability, lowercase characters are converted to uppercase by the display station or printer and displayed or printed as uppercase characters.

The message is assembled as a variable-length record. text addr contains an address that points to a message to be displayed. The message contains a 2-byte text field length followed by the text. The 2-byte message length describes the length of the message text only. There are no boundary requirements.

Note: All WTOR messages are action messages. An indicator is printed before the first character of an action message to indicate a need for operator action. Action messages will cause the audible alarm to sound on operator consoles so-equipped.

reply addr specifies the address in virtual storage of the area into which the system is to place the reply. The reply is left-justified at this address.

reply length specifies the length, in bytes, of the reply message.

ecb addr specifies the address of the event control block (ECB) to be used by the system to indicate the completion of the reply. The value of the ECB data must point to a fullword boundary. The ECB should be zeroed before the WTOR issued. After the system receives the reply, the ECB appears as follows:

Offset	Length(bytes)	Contents
0	1	Completion code

Note: Use RPLYISUR to obtain the 4-byte console ID and console name of the console issuing the reply.

,ROUTCDE=(routing code)

Specifies the routing code or codes to be assigned to the message.

The routing codes are:

The routing codes are:

Code

Meaning

1

Operator Action

The message indicates a change in the system status. It demands action by the operator at the console with master authority.

2

Operator Information

The message indicates a change in system status. It does not demand action; rather, it alerts the operator at the console with master authority to a condition that might require action.

This routing code is used for any message that indicates job status when the status is not requested specifically by an operator inquiry. It is also used to route processor and problem program messages to the system operator.

3

Tape Pool

The message gives information about tape devices, such as the status of a tape unit or reel, the disposition of a tape reel, or a request to mount a tape.

4

Direct Access Pool

The message gives information about direct access storage devices (DASD), such as the status of a direct access unit or volume, the disposition of a volume, or a request to mount a volume.

5

Tape Library

The message gives tape library information, such as a request by volume serial numbers for tapes for system or problem program use.

6

Disk Library

The message gives disk library information, such as a request by volume serial numbers for volumes for system or problem program use.

7

Unit Record Pool

The message gives information about unit record equipment, such as a request to mount a printer train.

8

Teleprocessing Control

The message gives the status or disposition of teleprocessing equipment, such as a message that describes line errors.

9

System Security

The message gives information about security checking, such as a request for a password.

10

System/Error Maintenance

The message gives problem information for the system programmer, such as a system error, an uncorrectable I/O error, or information about system maintenance.

11

Programmer Information

This is commonly referred to as write to programmer (WTP). The message is intended for the problem programmer. This routing code is used when the program issuing the message cannot route the message to the programmer through a system output (SYSOUT) data set. The message appears in the JESYSMSG data set.

12

Emulation

The message gives information about emulation. (These message identifiers are not included in this publication.)

13-20

For customer use only.

21-28

For subsystem use only.

29

Disaster recovery.

30-40

For IBM use only.

41

The message gives information about JES3 job status.

42

The message gives general information about JES2 or JES3.

43-64

For JES use only.

65-96

Messages associated with particular processors.

97-128

Messages associated with particular devices.

If you omit the ROUTCDE, and CONSID or CONSNAME parameters, the system uses the routing code specified on the ROUTCODE parameter on the DEFAULT statement in the CONSOLxx member of SYS1.PARMLIB.

,MCSFLAG=(flag name)

Specifies one or more flag names whose meanings are shown below:

Table 1. MCSFLAG Flag Names for WTOR Macro

Flag Name	Meaning
RESP	The WTOR is an immediate command response.
REPLY	This is a reply to a WTOR.
BRDCST	Broadcast the message to all active consoles.
HRDCPY	Queue the message for hard copy only.
NOTIME	Do not append time to the message.

,DESC=(descriptor code)

Specifies the message descriptor code or codes to be assigned to the message. Valid descriptor codes for the WTOR macro are:

7

Retain action message for life-of-task

13

Message previously automated

All WTOR messages are action messages that have an @ sign displayed before the first character. This indicates a need for operator action.

The system adds descriptor code 7 to all WTOR messages. The system holds all WTOR messages until one of the following events occurs:

• The system deletes the WTOR message when the reply is received.
• You delete the WTOR message using the DOM macro. You should delete any unanswered WTOR messages that are no longer current.
• The system deletes the WTOR message at task termination.

The message processing facility (MPF) can suppress messages. For MPF to suppress messages, the hardcopy log must be active. The suppressed messages do not appear on any console; they do appear on the hardcopy log.

,MSGTYP=(msg type)

Specifies how the message is to be routed to consoles on which the MONITOR command is active. If you specify anything other than MSGTYP=N, which is the default, your message is routed according to your specification on MSGTYP, and the ROUTCDE parameter is ignored.

For SESS, JOBNAMES, or STATUS, the message is to be routed to the console that issued the MONITOR SESS, MONITOR JOBNAMES, or MONITOR STATUS command, respectively. When the message type is identified by the operating system, the message is routed to only those consoles that requested the information.

For Y or N, the message type describes what functions (MONITOR SESS, MONITOR JOBNAMES, and MONITOR STATUS) are desired. N, or omission of the MSGTYP parameter, indicates that the message is to be routed as specified in the ROUTCDE parameter. Y creates an area in the WTO parameter list in which you can set message type information if you are coding a WTOR without any of the following parameters:

• KEY
• TOKEN
• CONSID
• CONSNAME
• TEXT
• RPLYISUR
• CART
• LINKAGE
• SYNCH

IBM recommends that you do not use MSGTYP=Y.

,RPLYISUR =reply console

Specifies a 12-byte field where the system will place the 8-byte console name and the 4-byte console ID of the console through which the operator replies to this message. When you specify this keyword in the list form, code it as RPLYISUR= with nothing after the equal sign.

,CART=cmd/resp token

Specifies an 8-byte field containing a command and response token to be associated with this message. The command and response token is used to associate user information with a command and its command response. When you specify this keyword in the list form, code it as CART= with nothing after the equal sign.

,CONSID=console id

Specifies a 4-byte field containing the ID of the console to receive a message. To view a list of valid console IDs, issue the DISPLAY CONSOLES command. Use this ID in place of a console ID in register 0. If you specify a 4-byte console ID, or if you specify a console ID for an extended MCS console, you must use CONSID instead of register 0. If you specify a 1-byte console ID, you must right-justify it and pad to the left with zeros.

Note:

1. If you code the CONSID parameter using a register, the register must contain the console ID itself, rather than the address of the console ID.
2. When you code CONSID on the list form of WTOR, code it as CONSID= with nothing after the equal sign.
3. Do not use both CONSID and register 0 to pass a console ID, because the results are unpredictable.
4. CONSID is mutually exclusive with the CONSNAME parameter.

,CONSNAME=console name

Specifies an 8-byte field containing a 2- through 8- character name, left-justified and padded with blanks, of the console to receive a message. This parameter is mutually exclusive with the CONSID parameter. When you specify this keyword in the list form, code it as CONSNAME= with nothing after the equal sign. Do not use CONSNAME to pass a console name, together with register 0 to pass a console ID, because the results are unpredictable. Be sure to clear the low-order byte of register 0 if you add the CONSNAME parameter to an existing invocation of WTOR.

,KEY=key

Specifies a field containing an 8-byte key to be associated with this message. The key must be EBCDIC if used with the MVS™ DISPLAY R command for retrieval purposes, but it must not be ‘*’. The key must be left-justified and padded on the right with blanks. If a register is used, it contains the address of the key. When this keyword is specified in the list form, it must be coded as KEY= with nothing after the equal sign.

,TOKEN=token

Specifies a field containing a 4-byte token to be associated with this message. This field is used to identify a group of messages that can be deleted by a DOM macro that includes TOKEN. The token must be unique within an address space and can be any value. When you specify this keyword on the list form, code it as TOKEN= with nothing after the equal sign.

Note: When you code the TOKEN parameter using a register, the register must contain the token itself, rather than the address of the token.

WTOR might abnormally terminate with abend code X'D23'. See z/OS MVS System Codes for an explanation and programmer response for this code.

When the WTOR macro returns control to your program, GPR 15 contains one of the following return codes.