Description

The WTOR macro causes a message requiring a reply to be written to one or more operator consoles and the hardcopy log. The macro also provides the information required by the system to return the reply to the issuing program. See z/OS MVS Programming: Assembler Services Guide for more information on using the WTOR macro.

For information about how to select the macro for an MVS/SP version other than the current version, see Compatibility of MVS macros.

Environment

Requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state and any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN=SASN
AMODE:	24- or 31- or 64-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Must be in the primary address space

Programming requirements

Be aware of the following when coding the WTOR macro:

MCSFLAG=REG0 is not supported on z/OS® V1R7 and higher.
If the list and execute forms of the WTOR macro are in separate modules, both modules must be assembled or compiled with the same level of WTOR.
IBM® recommends that you begin the parameter list for WTOR on a fullword boundary.
If the execute form of the macro specifies RPLYISUR, CART, CONSID, CONSNAME, KEY, or TOKEN, the list form, to ensure that the parameter list is generated correctly, must specify the same parameters without data. If you specify parameter values on the list form, the system issues an MNOTE and ignores the data.
For any WTOR parameters that allow a register specification, the value must be right-justified in the register.
As of z/OS 1.4.2, to prevent parameter lists that are not valid from causing system errors, the WTOR service records the errors as symptom records in LOGREC. One example of an invalid parameter list is an invalid combination of WTOR parameters. The system may also issue a D23 abend for diagnostic purposes only; the program issuing the WTOR will not be abended. Message processing will continue as far as possible using the invalid parameter list.
Due to these invalid parameter list errors, you may notice that some messages that once were processed are no longer able to be processed; your program may also receive different return codes. However, in these cases, the symptom record will always be issued, and the diagnostic D23 abend will be issued if possible. IBM recommends that you correct all WTOR errors, regardless of whether or not the message is actually displayed. For an example LOGREC symptom record, see Example 4 in the WTO description.
If a dump is needed along with the diagnostic D23 abend to debug the problem, the following SLIP can be set to cause dumps to be taken:
```
SLIP SET,ENABLE,COMP=D23,ACTION=SVCD,END
```

Restrictions

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

Input register information

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.

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0: Used as a work register by the system.
1: Message identification number if the WTOR macro completed normally (you can use this number to delete the message when it is no longer needed); otherwise, used as a work register by the system.
2-13: Unchanged.
14: Used as a work register by the system.
15: Return code.

When control returns to the caller, the access registers (ARs) contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

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.

Performance implications

None.

Syntax

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

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede WTOR.

WTOR

␢	One or more blanks must follow WTOR.

`‘msg’,reply addr,reply length,ecb addr` TEXT=`(text addr,reply addr,reply length,ecb addr)`	`msg`: Up to 122 characters. `text addr`: RX-type address or register (2) - (12). `reply addr`: A-type address, or register (2) - (12). `reply length`: Symbol, decimal number, or register (2) - (12). The minimum length is 1; the maximum length is 119. `ecb addr`: A-type address, or register (2) - (12).

,ROUTCDE=(`routing code`)	`routing code`: Decimal digit from 1 to 28. The `routing code` is one or more codes, separated by commas, or a hyphen to indicate a range.

,MCSFLAG=(`flag name`)	`flag name`: Any combination of the following, separated by commas: BRDCST HRDCPY RESP REPLY NOTIME

,DESC=(`descriptor code`)	`descriptor code`: Decimal number 7 or 13. If you code both 7 and 13, separate them with commas.

,MSGTYP=`(msg type)`	`msg type`: Any of the following: N SESS,JOBNAMES Y SESS,STATUS SESS JOBNAMES,STATUS JOBNAMES SESS,JOBNAMES,STATUS STATUS Note: IBM recommends that you do not use MSGTYP=Y. See the MSGTYP explanation on page ,MSGTYP=(msg type) for more information.

,RPLYISUR=`reply console`	`reply console`: RX-type address or register (2) - (12).

,CART=`cmd/resp token`	`cmd/resp token`: RX-type address or register (2) - (12).

,CONSID=`console id`	`console id`: RX-type address or register (2) - (12).
,CONSNAME=`console name`	`console name`: RX-type address or register (2) - (12).

,KEY=`key`	`key`: RX-type address or register (2) - (12).

,TOKEN=`token`	`token`: RX-type address or register (2) - (12).

Parameters

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:

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:

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.
When you code CONSID on the list form of WTOR, code it as CONSID= with nothing after the equal sign.
Do not use both CONSID and register 0 to pass a console ID, because the results are unpredictable.
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.

ABEND codes

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

Return and reason codes

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

Hexadecimal Return Code	Meaning and Action
00	Meaning: Processing completed successfully. Action: None. Be sure to delete the request by issuing the DOM macro.
02	Meaning: Processing was not completely successful. This could be due to inconsistent parameters given to WTOR, or it could be an environmental problem. Action: A D23 abend has been issued for diagnostic purposes only. No dump has been taken; if a dump is needed, you must set a SLIP trap. Correct any inconsistencies in the WTOR invocation.
04	Meaning: Program error. The length of text for a message line was not correct. Action: Make sure your text is properly referenced. If you are using the TEXT parameter, make sure it is pointing to valid data. Make sure your message text is defined correctly. If you are using the TEXT parameter, make sure the first two bytes of data in the area pointed to by the TEXT parameter value contain the length of the message text. In all cases, correct the problem and retry the request.
18	Meaning: Program error. The WPL was invalid and a symptom record was written to LOGREC to describe the error. The message was not processed. Action: Correct the WPL.

Example 1

Issue a WTOR to a console whose ID is in register 4.

         WTOR  'USR902A REPLY YES OR NO TO CONTINUE.',REPLY,L8,REPECB, X
               CONSID=(R4),RPLYISUR=CONINFO
         .
         .
         .
R4       EQU   4
L8       EQU   8
REPLY    DS    CL8
REPECB   DS    F
CONINFO  DS    CL12

Example 2

Issue a WTOR with the TEXT parameter. The message is to go to a specific console whose name is in field TOCON.

R4       EQU   4
LENG72   EQU   72
         .
         .
         .
         LA    R4,CATMSG
         WTOR  TEXT=(CATMSG,REPAREA,LENG72,IDSECB),                    X
               CONSNAME=TOCON,                                         X
               RPLYISUR=IDSAREA
         .
         .
         .
CATMSG   DC    AL2(L'REP99)
REP99    DC    C'USR999A ENTER LIST OF USERIDS.'
TOCON    DC    CL8'ALTCON  '
REPAREA  DS    CL72
IDSECB   DS    F
IDSAREA  DS    CL12

Example 3

Issue a WTOR using the TEXT parameter with the list and execute forms of the macro. The console ID to which the message is to be queued is assumed to be in field MYCONID. On the TEXT parameter for the execute form, commas mark the positions of reply addr and ecb addr; for the list form, a comma marks the position of reply length.

R12      EQU   12
C50      EQU   50                      LENGTH OF REPLY AREA
         USING *,R12
         .
         .
         .
         WTOR  MF=(E,M2,EXTENDED),TEXT=(MESSAGE,,C50,),CONSID=MYCONID, X
               RPLYISUR=MYCONAR
         .
         .
         .
M2       DS    0H
         WTOR  TEXT=(,RAREA,,MYECB),CONSID=,ROUTCDE=(2),RPLYISUR=,MF=L
MYCONID  DS    F
RAREA    DS    CL50
MYECB    DS    F
MYCONAR  DS    CL12
MESSAGE  DC    AL2(L'MTEXT)
MTEXT    DC    C'USR930A REQUEST IS AMBIGUOUS. RESPECIFY DEVICE.'
         END