If you code LINKAGE=SVC, the requirements for the caller are:

If you code LINKAGE=BRANCH, the requirements for the caller are:

If the LINKAGE=BRANCH parameter is specified, the SYNCH=YES parameter is required.

You can issue a multi-line WTOR only if you specify LINKAGE=BRANCH, SYNCH=YES.

Issue a synchronous message only if your program is in a state in which it cannot issue an ordinary WTOR (LINKAGE=SVC), and you must receive operator input before continuing.

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.

SYNCH=YES causes the calling program to display the message, become disabled, and receive the reply synchronously.

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

line type     text       maximum number
C             31 char    1 C type
L             66 char    2 L type
D             66 char    14 D type
DE            66 char    1 DE type
               or
E             None       1 E type

The parameters are explained as follows:

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

(‘text’,reply addr,reply length,ecb addr)

((‘text’,line type,...‘text’,line type),reply addr,reply length,ecb addr)

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

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

TEXT=(((text addr,line type),...(text addr, line type)),reply addr,reply length,ecb addr)

Specifies the message or multiple-line message to be written to one or more operator consoles.

Use the ‘msg’ parameter to write a single-line message to the operator. Enclose the message in apostrophes. The apostrophes do not appear on the console. You can include any character that can be used in a character (C-type) DC instruction.

To have apostrophes appear in the message text, use two apostrophes to get one to appear. For example, ''Message Off'' would appear on a display as 'Message Off'. When a program issues a WTOR macro, the system translates the text; only standard printable EBCDIC characters are passed to MCS-managed display devices. The EBCDIC characters that can be displayed are listed in “Timing and Communication” in z/OS MVS Programming: Assembler Services Guide. All other characters are replaced by blanks. Unless the console has dual-case capability, lowercase characters are displayed or printed as uppercase characters.

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

Use the parameters (‘text’) and (text addr,line type) to write a multiple-line message to the operator. For an authorized program, the message can be up to fourteen lines long; the system truncates the message at the end of the fourteenth line. The fourteen-line limit does not include the control line (message IEE932I), as explained under line type C below.

Note:

1. You can issue a multi-line WTOR only if you specify SYNCH=YES. See the SYNCH parameter description for information about its use.
2. If you code the parameter (‘text’) without repetition, the message appears as a single-line message.
3. Specify all lines of a multiple-line WTOR consistently with the message text or the TEXT keyword. When coding the TEXT keyword for a multiple-line message, do not exceed the 66-character limit for the macro parameter value.

The line type defines the type of information contained in the ‘text’ field of each line of the message:

C

Indicates that the ‘text’ parameter is the text to be contained in the control line of the message. The control line normally contains a message title. C may be coded only for the first line of a multiple-line message. Control lines are optional.

L

Indicates that the 'text' parameter is a label line. Label lines contain message heading information. Label lines are optional. If coded, lines must either immediately follow the control line or another label line or be the first line of the multiple-line message if there is no control line. Only two label lines may be coded per message.

D

Indicates that the ‘text’ parameter contains the information to be conveyed to the operator by the multiple-line message.

DE

Indicates that the ‘text’ parameter contains the last line of information to be passed to the operator. Specify DE on the last line of text of the WTOR. If there is no text on the last line, specify E.

E

Indicates that the previous line of text was the last line of text to be passed to the operator. The ‘text’ parameter, if any, coded with a line type of E is ignored. Specify E on the last line of the WTOR if that line has no text. If the last line has text, specify DE.

Note: All WTOR messages are action messages. An indicator (* for authorized issuers or @ for unauthorized issuers) appears 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 maximum 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 ECB address must point to a fullword boundary. 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:

Code

Meaning

1

Operator Action

The message indicates a change in the system status. It demands action by the primary operator.

2

Operator Information

The message indicates a change in system status. It does not demand action; rather, it alerts the primary operator 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. If the message issuer is a TSO user, the message is also displayed on the TSO user's screen.

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 keywords, the system uses the routing code specified on the ROUTCODE keyword on the DEFAULT statement in the CONSOLxx member of SYS1.PARMLIB. See z/OS MVS Initialization and Tuning Reference for information about CONSOLxx.

,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 asterisk (*) sign displayed before the first character (WTORs for unauthorized users 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.

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.

,MCSFLAG=(flag name)

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

Table 1. MCSFLAG Flag Names

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.
NOCPY	Do not queue the message for hard copy.

,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.

,CONSID=console id

Specifies a 4-byte field containing the ID of the console to receive a message.

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

,SYSNAME=system name

Specifies an 8-byte input field containing a system name to be associated with this message. You should left-justify SYSNAME and pad with blanks.

The system name is that of the system from which the caller issues the WTOR message. When you specify this parameter in the list form, code it as SYSNAME= with nothing after the equal sign. The system will, by default, set the system name to the system where the message is issued. IBM suggests that you avoid specifying SYSNAME.

,CART=cmd/resp token

Specifies an 8-byte field containing a command and response token to be associated with this message. You can specify any value as a command and response token. 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.

,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.

,JOBID=job id

Specifies an 8-byte input field containing an ID that specifies the issuer of the WTOR message. When you specify this parameter in the list form, code it as JOBID= with nothing after the equal sign.

,JOBNAME=jobname

Specifies an 8-byte input field containing a name that specifies the issuer of the WTOR message. You should left-justify JOBNAME and pad with blanks. When you specify this parameter in the list form, code it as JOBNAME= with nothing after the equal sign.

,LINKAGE=SVC

,LINKAGE=BRANCH

Specifies how control is to pass to the WTOR service.

LINKAGE=SVC indicates the linkage is by a supervisor call. If LINKAGE is not specified, this is the default.

LINKAGE=BRANCH indicates the linkage is by a branch-and-link. You must use SYNCH=YES with this parameter. This parameter is used by programs that require the WTOR request to be handled synchronously.

When you specify this keyword in the list form, code it as LINKAGE= with nothing after the equal sign.

,SYNCH=NO

,SYNCH=YES

Specifies whether the WTOR request processes synchronously with the caller.

SYNCH=NO, the default, indicates that the request is not processed synchronously.

SYNCH=YES indicates the request is to be processed synchronously. This parameter is used in error and recovery environments, when normal message processing cannot be used. The message is sent to the console, and the reply is obtained immediately, before control is returned to the caller. Before return, the reply and reply length are moved to the areas specified by the caller, and the ecb marked “complete.” Copies of the message and reply are queued for transcription to the hardcopy log.

If you specify SYNCH=YES:

• You must specify the parameter LINKAGE=BRANCH.
• Do not specify MCSFLAG=HRDCPY.
• Do not specify RPLYISUR

Your installation can determine which consoles can receive synchronous messages by using the SYNCHDEST parameter in the CONSOLxx member of SYS1.PARMLIB. For additional information on the SYNCHDEST parameter, see z/OS MVS Initialization and Tuning Reference.

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 hexadecimal return codes.