Description

Use the WTO macro to write a message to one or more operator consoles. See the information on communication inz/OS MVS Programming: Authorized Assembler Services Guide for more information on using WTO. z/OS MVS Programming: Assembler Services Reference IAR-XCT also contains information on WTO, except for the AREAID, MSGTYP, CONNECT, SYSNAME, JOBID, JOBNAME, LINKAGE, SYNCH, and WSPARM parameters.

Environment

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

Environmental factor Requirement
Minimum authorization:
  • If you specify routing codes in the range 41-128, or specify more than 10 lines of text, or code the CONNECT, SYSNAME, JOBID, and JOBNAME parameters, you need a minimum authorization of either supervisor state with PSW key 0-7 or APF-authorized.
  • For all other cases, you need a minimum authorization of problem state and any 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.

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

Environmental factor Requirement
Minimum authorization: One of the following, depending on the parameters you code:
  • Supervisor state and PSW key 0 - 7.
  • If you code the WSPARM parameter, supervisor state with PSW key 0.
Dispatchable unit mode: Task or SRB.
Cross memory mode: Any PASN, any HASN, any SASN
AMODE: 24- or 31-bit
ASC mode: Primary
Interrupt status: Enabled or disabled for I/O and external interrupts
Locks: The caller may hold locks, but is not required to hold any.
Control parameters: Must be in the primary address space.

Programming requirements

Be aware of the following when coding the WTO macro:
  • For a multiple-line message, you must clear register 0 on the first WTO issuance if the WTO is being issued from an authorized program. For WTOs issued from problem programs, any data in register 0 is ignored.
  • You must clear register 0 before issuing a multiple-line WTO. The only exception is when you are using register 0 to pass a message identifier to connect multiple-line messages. However, in this case, IBM® suggests you use the CONNECT parameter rather than register 0.
  • If the caller is disabled or issues WTO with the WSPARM parameter, the WTO and LOADWAIT parameter lists must be in fixed storage.
  • When using any parameter with an address, the data being referenced must be accessible by the caller issuing the WTO.
  • If the list and execute forms of the WTO macro are in separate modules, both modules must be assembled or compiled with the same level of WTO.
  • When coding a reentrant program, make sure the WTO parameter list is generated correctly. To ensure this, you must code the same parameters on both forms, only when you code one or more of the following parameters:
    • TEXT=(text addr)
    • CONNECT
    • CONSID
    • CONSNAME
    • SYSNAME
    • CART
    • KEY
    • TOKEN
    • JOBNAME
    • JOBID
    • LINKAGE
    • WSPARM
    On the list form, code only the parameter and the equal sign; do not code a parameter value as well. For example,:
    WTO 'text',CONSID=,MF=L

    If you specify parameter values on the list form, the system issues an MNOTE and ignores the data.

  • For any WTO parameters that allow a register specification, the value must be right-justified in the register.
  • If WSPARM is not equal to zero, the wait state is loaded whether or not the message could be displayed or queued for hardcopy.
  • If you specify the TEXT keyword for a multi-line WTO on the list form, you must omit text addr for each line, but include line type. If you specify text addr, the system ignores the data and issues an MNOTE. On the execute form, omit line type for each line, but include text addr.
  • As of z/OS® 1.4.2, to prevent parameter lists that are not valid from causing system errors, the WTO service records the errors as symptom records in LOGREC. One example of an invalid parameter list is an invalid combination of WTO parameters. The system might also issue a D23 abend for diagnostic purposes only; the program issuing the WTO is not abended. Message processing continues as far as possible using the invalid parameter list.

    These invalid parameter list errors mean that some messages you once were able to process can no longer be processed; your program might also receive different return codes. However, in these cases, the symptom record is always issued, and the diagnostic D23 abend is issued if possible. IBM recommends that you correct all WTO errors, regardless of whether or not the message is actually displayed. For an example LOGREC symptom record, see Example 3.

    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

  • If an SRB-mode or cross-memory mode caller issues WTO without the JOBID or JOBNAME parameter, the resulting message may not contain a job ID or job name.
  • You should issue a synchronous message only in serious system emergencies.
    Important: Use caution when specifying SYNCH=YES. If your installation has not specified a SYNCHDEST console group in the CNGRPxx member of parmlib, the system displays the WTO on the system console, located in the Operating System Messages task on the Hardware Management Console. The message is displayed for up to ten seconds and then control returns to the WTO issuer. All of the system’s CPs may be stopped while the message is being displayed.
  • There are two ways for authorized callers (supervisor state with PSW key 0-7) to issue multiple-line messages:
    1. You can issue a multiple-line WTO message of up to 255 lines with one WTO macro. If you are coding more than one multiple-line message, and you want to connect the messages (and you are not using the recommended CONNECT keyword on the WTO macro), you must ensure that the left-most three bytes of register 0 are set correctly:
      • For the first request (of up to 255 lines), these three bytes must be zero.
      • For subsequent requests, register 0 can contain the message identifier that the WTO service routine returns in register 1 after the first request. Note that you must left-justify the 24-bit identifier when you load it into register 0.
    2. The CONNECT parameter provides a way to connect multiple-line WTO messages. Therefore, an authorized caller actually can issue connect messages that total more than 255 lines.
  • A WTO message with ROUTCDE=11 is sent to the JES2 or JES3 system message data set (SYSMSG) unless LINKAGE=BRANCH is specified. In this case, the message is not sent. If you want the WTO to go to SYSMSG, use LINKAGE=SVC with ROUTCDE=11. Whether you issue LINKAGE=BRANCH or LINKAGE=SVC with ROUTCDE=11, the message appears in the JES2 or JES3 joblog.
  • The caller cannot have an EUT FRR established with LINKAGE=SVC. The caller can have an EUT FRR established with LINKAGE=BRANCH.
  • When using the LINKAGE=BRANCH parameter, the system does not automatically delete a WTO issued by a caller in SRB mode. A caller in SRB mode must issue the DOM macro to explicitly delete any action message when the calling program ends.
  • If you specify LINKAGE=BRANCH, WTO ignores any data in register 0. Therefore, if you are connecting lines of a multi-line WTO, and you specified LINKAGE=BRANCH, you cannot put the CONNECT ID in register 0. You must use the CONNECT keyword.
  • If you are connecting lines of a multi-line WTO, and the end line is not received within a certain time interval from the most recent connect request (the default set by IBM is 30 seconds), the message is truncated. Further attempts to connect to the message are rejected.
  • If you are connecting lines of a multi-line WTO, there is a limit of 65533 total lines allowed in the multi-line message. If you attempt to send more than 65533 total lines, an ABEND X'D23', reason code X'0051' occurs.

Input register information

Before issuing the WTO 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 general purpose registers (GPRs) contain:
Register
Contents
0
Used as a work register by the system.
1
Message identification number if the macro completed normally. You can use this number to delete the message when it is no longer needed. If you are using the CONNECT parameter to connect WTO messages, store this value in the 4-byte CONNECT field and set register 0 to zero before issuing the next WTO. Otherwise, register 1 is 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

SYNCH=YES causes the system to display the message, disable the issuing program and system, wait for up to ten seconds, and then synchronously return to the program. If your installation has not specified a SYNCHDEST console group in the CNGRPxx member of parmlib, the system displays the WTO on the system console, located in the Operating System Messages task on the Hardware Management Console. All of the system’s CPs may be stopped while the message is being displayed (for up to ten seconds).

Syntax

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

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
One or more blanks must precede WTO.
   
WTO  
   
One or more blanks must follow WTO.
   
'msg' msg: Up to 126 characters.
('text') text: Up to 126 characters.
('text',line type) text addr: RX-type address or register (2) - (12).
('text',line type)…,('text',line type) If you code ’msg’ or (’text’...), it must be the first parameter you code.
TEXT=text addr  
TEXT=(text addr,line type)  
TEXT=((text addr,line type),...(text addr,line type))  
  The permissible line type values, text lengths, and maximum numbers of each line type are:
line type     text       maximum number
C             35 char    1 C type
L             71 char    2 L type
D             71 char    255 D type
DE            71 char    1 DE type
              or
E             None       1 E type

The maximum total number of lines that can be coded in one instruction is 255.

   
   ,ROUTCDE=(routing code) routing code: Decimal digit from 1 to 128. The routing code is one or more codes, separated by commas, or a hyphen to indicate a range.
   
   ,DESC=(descriptor code) descriptor code: Decimal digit from 1 to 13. The descriptor code is one or more codes, separated by commas.
   
   ,AREAID=id char id char: Alphabetic character A - K, Z.
   
   ,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.
   
   ,MCSFLAG=(flag name) flag name: Any combination of the following, separated by commas:
CMD
HRDCPY
RESP
NOCPY
REPLY
NOTIME
BRDCST
   
   ,CONNECT=connect field connect field: RX-type address or register (2) - (12).
Note: CONNECT is mutually exclusive with the CONSID, CONSNAME, SYSNAME, and SYNCH=YES parameters.
   
   ,CONSID=console id console id: RX-type address or register (2) - (12).
   ,CONSNAME=console name console name: RX-type address or register (2) - (12).
   
   ,SYSNAME=system name system name: RX-type address or register (2) - (12).
   
   ,CART=cmd/resp token cmd/resp token: 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).
   
   ,JOBID=job id job id: RX-type address or register (2) - (12).
   
   ,JOBNAME=jobname jobname: RX-type address or register (2) - (12).
   
   ,LINKAGE=SVC Default: SVC
   ,LINKAGE=BRANCH  
   
   ,SYNCH=NO Default: NO
   ,SYNCH=YES  
   
   ,WSPARM=0 Default: 0
   ,WSPARM=wait state addr wait state addr: RX-type address or register (2) - (12).
   

Parameters

The parameters are explained as follows:

'msg'
('text')
('text',line type)
('text',line type)...,('text',line type)
TEXT=(text addr)
TEXT=(text addr,line type)
TEXT=((text addr,line type),...(text addr,line type))
Specifies the message or multiple-line message to be written to one or more operator consoles.

The 'msg' parameter is used to write a single-line message to the operator. In the format, the message must be enclosed in single quotation marks, which do not appear on the console. It can include any character that can be used in a character (C-type) DC instruction.

To have single quotation marks appear in the message text, use two single quotation marks to get one to appear. For example, ''Message Off'' would appear on a display as 'Message Off'. When a program issues a WTO 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 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. The parameters TEXT=(text addr) and TEXT=(text addr,line type) represent 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.

The ('text') and (text addr,line type) parameters are used to write a multiple-line message to the operator. For a problem-state program, the message can be up to ten lines long; the system truncates the message at the end of the tenth line. The ten-line limit does not include the control line (message IEE932I), as explained under line type C below. The ten-line limit only applies to unauthorized users; for authorized users, the message can be up to 255 lines each time WTO is issued.
Notes:
  1. If the ('text') parameter is coded without repetition, the message appears as a single-line message.
  2. Specify all lines of a multiple-line WTO consistently with the message text or the TEXT keyword.
  3. When coding the TEXT keyword for a multiple-line message:
    • Do not exceed the 71-character limit for the macro parameter value.
    • You can use the CONNECT parameter to connect subsequent lines of a multiple-line message if you cannot fit them into one macro invocation.
  4. For a multiple-line message, you must clear register 0 on the first WTO issuance.
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 only be coded for the first line of a multiple-line message. If this parameter is omitted and descriptor code 9 is coded, the system generates a control line (message IEE932I) containing only a message identification number. The control line remains static while you scroll through all the lines of a multi-line message displayed on an MCS console (provided that the message is displayed in an out-of-line display area). Control lines are optional.
L
Indicates that the 'text' parameter is a label line. Label lines contain message heading information; they remain static while you scroll through all the lines of a multi-line message displayed on an MCS console (provided that the message is displayed in an out-of-line display area). 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. See “Embedding Label Lines in a Multi-line Message” in z/OS MVS Programming: Authorized Assembler Services Guide for additional information about how to include multiple label lines within a message.
D
Indicates that the 'text' parameter contains the information to be conveyed to the operator by the multiple-line message. The data lines are paged while you scroll through all the lines of a multi-line message displayed on an MCS console (provided that the message is displayed in an out-of-line display area).
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 WTO. 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 WTO if that line has no text. If the last line has text, specify DE.
,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 is issued by a TSO user, the message is also sent to 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, DESC, 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.

Note: Routing codes 1, 2, 3, 4, 7, 8, 10, and 42 cause hard copy of the message when display consoles are used, or more than one console is active. All other routing codes may go to hardcopy as a PARMLIB option or as a result of a VARY HARDCPY command.
,DESC=(descriptor code)
Specifies the message descriptor code or codes to be assigned to the message. Descriptor codes 1 through 6, 11 and descriptor code 12 are mutually exclusive. Codes 7 through 10, and 13, can be assigned in combination with any other code.

The descriptor codes are:

Code
Meaning
1
System Failure
The message indicates an error that disrupts system operations. To continue, the operator must reIPL the system or restart a major subsystem. This causes the audible alarm to be issued.
Note:
  • Descriptor code 1 messages are retained if the Action Message Retention Facility (AMRF) is active.
  • Descriptor code 1 messages do not automatically roll off a console in RD mode.
2
Immediate Action Required
The message indicates that the operator must perform an action immediately. The message issuer could be in a wait state until the action is performed or the system needs the action as soon as possible to improve performance. The task waits for the operator to complete the action. This causes the audible alarm to be issued.
Note:
  • When an authorized program issues a message with descriptor code 2, a DOM macro must be issued to delete the message after the requested action is performed.
  • Descriptor code 2 messages are retained if the Action Message Retention Facility (AMRF) is active.
  • Descriptor code 2 messages do not automatically roll off a console in RD mode.
3
Eventual Action Required

The message indicates that the operator must perform an action eventually. The task does not wait for the operator to complete the action.

If the task can determine when the operator has performed the action, the task should issue a DOM macro to delete the message when the action is complete.

Note: Descriptor code 3 messages are retained if the Action Message Retention Facility (AMRF) is active.
4
System Status

The message indicates the status of a system task or of a hardware unit.

5
Immediate Command Response

The message is issued as an immediate response to a system command. The response does not depend on another system action or task.

6
Job Status

The message indicates the status of a job or job step.

7
Task-Related

The message is issued by an application or system program. Messages with this descriptor code are deleted when the job step that issued them ends.

8
Out-of-Line
The message, which is one line of a group of one or more lines, is to be displayed out-of-line. If a message cannot be displayed out-of-line because of the device being used, descriptor code 8 is ignored, and the message is displayed in-line with the other messages.
Note: Multiline messages directed at an OOL area and routed by either the UNKNIDS or INTIDS attributes are forced "inline".
9
Operator's Request

The message is written in response to an operator's request for information by a DEVSERV, DISPLAY, or MONITOR command.

10
Not defined

Descriptor code 10 is not currently in use.

11
Critical Eventual Action Required

The message indicates that the operator must perform an action eventually, and the action is important enough for the message to remain on the display screen until the action is completed. The task does not wait for the operator to complete the action. This causes the audible alarm to be issued.

Avoid using this descriptor code for non-critical messages because the display screen could become filled.

If the task can determine when the operator has performed the action, the task should issue a DOM macro to delete the message when the action is complete.
Note:
  • Descriptor code 11 messages are retained if the Action Message Retention Facility (AMRF) is active.
  • Descriptor code 11 messages do not automatically roll off a console in RD mode.
12
Important Information

The message contains important information that must be displayed at a console, but does not require any action in response.

13
Automation Information

Indicates that this message was previously automated.

Action messages many have an * sign or @ sign displayed before the first character of the message. The * sign indicates that the WTO was issued by an authorized program. The @ sign indicates that the WTO was issued by an unauthorized program.

All WTO messages with descriptor codes 1, 2, or 11 are action messages that have an asterisk (*) sign displayed before the first character of the message. This indicates a need for operator action. These action messages cause the audible alarm to sound on operator consoles so-equipped. On operator consoles that support color, descriptor codes determine the color in which a message should be displayed. Colors can indicate the type of action you need to take depending on your installation setup. The colors used for different descriptor codes are described in z/OS MVS System Commands.

The system holds messages with descriptor codes 1, 2, 3, or 11 until you delete them. When you no longer need messages with descriptor codes 1, 2, 3, or 11, you should delete those messages using the DOM macro. If messages with descriptor codes 1, 2, 3, or 11 also have descriptor code 7, the system deletes them automatically at task termination. For unauthorized issuers of WTOs, the system adds descriptor code 7 to all messages with descriptor code 1 or 2. The system also adds descriptor code 7 to all WTORs.

If descriptor code 7 is specified, the system deletes the message automatically when the job step that issued it ends.

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.

,AREAID=id char
Specifies a display area of the console screen on which a multiple-line message is to be written.
Valid area IDs are A through K and Z. A through K refer to out-of-line areas defined on an MCS console by the CONTROL A command. The character Z designates the message area (the screen's general message area, rather than a defined display area); it is assumed if nothing is specified. The areas are explained in z/OS MVS System Commands.
Notes:
  1. WTO ignores this keyword on single-line invocations.
  2. When you specify AREAID, you must specify descriptor codes 8 and 9.
  3. If you specify this parameter, the area could be overlaid by a currently running dynamic display. Support for queuing messages with descriptor code 8 is by console ID only. You must specify a console explicitly using the CONSID or CONSNAME parameters on WTO.
  4. You can use the CONVCON macro to syntactically validate an area ID.
,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 those consoles that requested the information.

For Y, the message type describes what functions (MONITOR SESS, MONITOR JOBNAMES, and MONITOR STATUS) are wanted. 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 WTO without any of the following parameters:
  • KEY
  • TOKEN
  • CONSID
  • CONSNAME
  • TEXT
  • CART
  • LINKAGE
  • SYNCH

IBM recommends that you do not use MSGTYP=Y.

,MCSFLAG=(flag name)
Specifies one or more flags whose meanings are shown below:
Table 1. MCSFLAG Flag Names
Flag Name Meaning
RESP The WTO is an immediate command response.
REPLY This WTO is a reply to a WTOR.
BRDCST Broadcast the message to all active consoles.
HRDCPY Queue the message for hardcopy only.
NOTIME Do not append time to the message.
NOCPY Do not queue the message for hardcopy.
CMD The WTO is a recording of a system command issued for hardcopy log purposes.
Notes:
  1. MCSFLAG=HRDCPY and SYNCH=YES are mutually exclusive.
  2. Use DESC=5 rather than specifying MCSFLAG=RESP for WTO messages that are immediate command response.
,CONNECT=connect field
Specifies a field containing the 4-byte message ID of the previous WTO to which this WTO is to be connected. This message ID is obtained as an output parameter (returned in register 1) from the previous WTO. If a register is used, it contains the address of the message ID.

CONNECT is valid only for continuation of multiple-line messages. When you specify this parameter in the list form, code it as CONNECT= with nothing after the equal sign.

This parameter is mutually exclusive with the CONSID, CONSNAME, and SYSNAME parameters.

Note: If you specify LINKAGE=SVC, you can still use register 0, as mentioned at the beginning of the WTO macro description, to connect WTO messages. If you specify both register 0 and CONNECT, however, the system uses the CONNECT parameter. IBM suggests that you use the CONNECT parameter.
,CONSID=console id
Specifies a 4-byte field containing the ID of the console to receive a message.
Notes:
  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 WTO, code it as CONSID= with nothing after the equal sign.
  3. CONSID is mutually exclusive with the CONNECT, CONSNAME, and SYSNAME parameters.
,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. When you specify this parameter in the list form, code it as CONSNAME= with nothing after the equal sign.

This parameter is mutually exclusive with the CONSID, CONNECT, and SYSNAME parameters.

,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 WTO. When you specify this parameter in the list form, code it as SYSNAME= with nothing after the equal sign. If SYSNAME is omitted, the system uses the name of the system where the WTO is issued. IBM suggests that you avoid using the SYSNAME parameter.

This parameter is mutually exclusive with the CONNECT parameter.

,CART=cmd/resp token
Specifies an 8-character input 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. You can supply any value as a command and response token. When you specify this parameter in the list form, code it as CART= with nothing after the equal sign.
,KEY=key
Specifies an input 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 you specify this parameter in the list form, code it as KEY= with nothing after the equal sign.
,TOKEN=token
Specifies an input 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 parameter in 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 identifies the issuer of the WTO 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 identifies the issuer of the WTO 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 WTO service.

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

LINKAGE=BRANCH indicates that the linkage is by a branch-and-link. This parameter is used by programs that run at times when an SVC cannot be issued, and by programs that require the WTO request to be handled synchronously.

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

If you specify LINKAGE=BRANCH, you cannot put the CONNECT value in register 0. You must use the CONNECT keyword.

,SYNCH=NO
,SYNCH=YES
Specifies whether the WTO request processes synchronously with the caller.

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

SYNCH=YES indicates that 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 a console, where it is held on the screen for up to ten seconds, before control is returned to the caller. A copy of the message is queued for transcription to the hardcopy log.

If you specify SYNCH=YES:
  • You must specify the parameter LINKAGE=BRANCH.
  • The message text must be 14 lines or less.
  • The following parameters are mutually exclusive: CONNECT, AREAID, and MCSFLAG=HRDCPY.
Important: Use caution when specifying SYNCH=YES. If your installation has not specified a SYNCHDEST console group in the CNGRPxx member of parmlib, the system displays the WTO on the system console, located in the Operating System Messages task on the Hardware Management Console. All of the system’s CPs may be stopped while the message is being displayed (for up to ten seconds). See the Display of Synchronous Messages topic in z/OS MVS Planning: Operations for more information about how z/OS displays these messages.

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.

,WSPARM=0
,WSPARM=wait state addr
Specifies whether a wait state is associated with this message.

A value of zero indicates that there is no wait state associated with this message. If you do not specify WSPARM, this is the default.

A nonzero value indicates either the address of a LOADWAIT parameter list or a register containing a pointer to the parameter list. The LOADWAIT macro generates the LOADWAIT parameter list. When you specify this parameter in the list form, code it as WSPARM= with nothing after the equal sign.

This parameter requires the SYNCH=YES and LINKAGE=BRANCH parameters.

ABEND codes

WTO 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 WTO macro returns control to your program, GPR 15 contains one of the following hexadecimal return codes.

Table 2. Return codes for the WTO macro
Return Code Meaning and Action
00 Meaning: Processing completed successfully.

Action: None.

02 Meaning: Processing was not completely successful. This could be due to inconsistent parameters given to WTO, 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 WTO 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.

08 Meaning: Program error. The connecting message ID (passed in register 0 or as specified by the CONNECT parameter value) does not match any on the queue. The request was ignored.

Action: Verify the connect ID value, 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.

30 Meaning: Environmental error. For routing code 11, the required resource was not available and the request was ignored. For any other routing code, the request was processed.

Action: Retry the request when the resource you need is available.

40 Meaning: Environmental error. WTO was issued with LINKAGE=BRANCH; insufficient storage was available to queue the message for delayed issue. If SYNCH=NO was specified, the message was not queued for delayed issue. If SYNCH=YES was specified, the message was delivered for display, but not queued for hardcopy.

Action: If you want the message to be delivered to the destination you requested, reissue the request. If the message was an action message that was not displayed, a DOM request is not required.

44 Meaning: Environmental error. WTO was issued with LINKAGE=BRANCH, SYNCH=YES, or was issued during IPL processing; no usable console was available. The message was only queued for hardcopy.

Action: If the message was issued during IPL, do not reissue the message. If after IPL and you want the message to be delivered to the destination you requested, reissue the request. If the message was an action message that was not displayed, a DOM request is not required.

48 Meaning: Environmental error. WTO was issued with LINKAGE=BRANCH, SYNCH=YES, or was issued during IPL processing; no usable console was available and insufficient storage was available to queue the message for delayed issue. The message was not delivered for display, nor queued for hardcopy.

Action: If the message was issued during IPL, do not reissue the message. If after IPL and you want the message to be delivered to the destination you requested, reissue the request. If the message was an action message that was not displayed, a DOM request is not required.

4C Meaning: Environmental error. WTO was issued with LINKAGE=BRANCH; no storage was available for the use of WTO processing. If WSPARM=0, no processing was done. If WSPARM does not equal zero, WTO loaded the wait state, but performed no other processing.

Action: If you want the message to be delivered to the destination you requested, reissue the request. If the message was an action message that was not displayed, a DOM request is not required.

50 Meaning: Environmental error. The message could not be fully processed because of insufficient space. The message might not appear in the hardcopy log and it might not be displayed on any consoles.

Action: Retry the request.

54 Meaning: Environmental error. The message could not be fully processed because of a hardcopy failure. The message might not appear in the hardcopy log.

Action: Issue a D C,HC to display any active hardcopy mediums. Verify that SYSLOG and OPERLOG are active and functioning correctly and then retry the request.

58 Meaning: Environmental error. The message could not be fully processed because of an error that occurred while sending it. The message might not appear in the hardcopy log and it might not be displayed on any consoles.

Action: Retry the request.

5C Meaning: Environmental error. The message could not be fully processed because of a failure freeing storage. The message might not appear in the hardcopy log and it might not be displayed on any consoles.

Action: Retry the request.

60 Meaning: Environmental error. The message could not be fully processed because of an error that occurred while calculating its size. The message might not appear in the hardcopy log and it might not be displayed on any consoles.

Action: Retry the request.

64 Meaning: Environmental error. The message could not be fully processed because of an error that occurred while building the message. The message might not appear in the hardcopy log and it might not be displayed on any consoles.

Action: Retry the request.

68 Meaning: The WTO environment is not yet available. The message was not delivered for display, nor was it queued for hardcopy.

Action: Issue the request again when WTO processing is available.

Example 1

Issue an important information message to a console whose name is defined in field MYCONS. This message is issued using the branch-entry option.
       WTO     'USR123I DO NOT SUBMIT JOBS REQUESTING THREE OR MORE TAPX
               ES DURING FIRST SHIFT',
               DESC=(12),CONSNAME=MYCONS,LINKAGE=BRANCH,SYNCH=NO
       .
       .
       .
MYCONS DC     CL8'SCHDCONS'

Example 2

Issue a multi-line message using the TEXT parameter. This is an important information message which does not have a timestamp and is not sent to the hardcopy log.
       WTO     TEXT=((REMIND1,D),(REMIND2,D),(REMIND3,DE)),          X
               DESC=(12),MCSFLAG=(NOTIME,NOCPY)
       .
       .
       .
REMIND1 DC   AL2(L'RMD1TXT)
RMD1TXT DC   C'USR003I REMINDER:  THE SYSTEM IS NOT AVAILABLE FOR USEX
              ON THIRD SHIFT'
REMIND2 DC   AL2(L'RMD2TXT)
RMD2TXT DC   C'FOR SPECIAL REQUESTS CONTACT SYSTEM SUPPORT'
REMIND3 DC   AL2(L'RMD3TXT)
RMD3TXT DC   C'CALL THE STATUS DESK FOR FURTHER INFORMATION'

Example 3

To prevent parameter lists that are not valid from causing system errors, the WTO service records the errors as symptom records in LOGREC. This is a sample symptom record:
THE SYMPTOM RECORD DOES NOT CONTAIN A SECONDARY SYMPTOM STRING.               
FREE FORMAT COMPONENT INFORMATION:                                            
    KEY = F000     LENGTH = 000024 (0018)                                     
    +000    C9D5C3D6    D9D9C5C3    E340E6E3    D640C9D5    |INCORRECT WTO IN|
    +010    E5D6C3C1    E3C9D6D5                            |VOCATION        |
    KEY = F000     LENGTH = 000010 (000A)                                     
    +000    C1E4E3C8    D6D9C9E9    C5C4                    |AUTHORIZED      |
    KEY = F000     LENGTH = 000009 (0009)                                     
    +000    C1E2C9C4    61F0F0F0    F1                      |ASID/0001       |
    KEY = F000     LENGTH = 000016 (0010)                                     
    +000    D1D6C2D5    C1D4C561    5CD4C1E2    E3C5D95C    |JOBNAME/*MASTER*|
    KEY = F000     LENGTH = 000025 (0019)                                     
    +000    C9D5E5D6    D2C5D961    C9C5C5C3    C2F9F9F9    |INVOKER/IEECB999|
    +010    4EF0F0F0    F0F4C5C4    F2                      |+00004ED2       |
    KEY = F000     LENGTH = 000032 (0020)                                     
    +000    C5D5C4D3    C9D5C540    C4C5E3C5    C3E3C5C4    |ENDLINE DETECTED|
    +010    40C2C5C6    D6D9C540    E6D7D3D3    C9D5C5E2    | BEFORE WPLLINES|
    KEY = F000     LENGTH = 000017 (0011)                                     
    +000    C3E4D9D9    C5D5E340    D3C9D5C5    61F0F0F0    |CURRENT LINE/000|
    +010    F2                                              |2               |
    KEY = F000     LENGTH = 000003 (0003)                                     
    +000    E6D7D3                                          |WPL             |
    KEY = FF00     LENGTH = 000216 (00D8)                                     
    +000    00480050    F0F0F2F2    40C5D5C1    C2D3C5C4    |...&0022 ENABLED|
    +010    4040F0F0    F2F340C5    D5C1C2D3    C5C44040    |  0023 ENABLED  |
    +020    F0F0F2F4    40C5D5C1    C2D3C5C4    4040F0F0    |0024 ENABLED  00|
    +030    F2F540C5    D5C1C2D3    C5C44040    F0F0F2F6    |25 ENABLED  0026|
    +040    40C5D5C1    C2D3C5C4    0400007C    10000000    | ENABLED...@....|
    +050    00000000    00000000    000004D2    00000000    |...........K....|
    +060 LENGTH(0048) ==> ALL BYTES CONTAIN X'00'.                            
    +090    00000000    40404040    40404040    00000000    |....        ....|
    +0A0 LENGTH(0032) ==> ALL BYTES CONTAIN X'00'.                            
    +0C0    00000000    2000C103    00103000    F0F0F2F7    |......A.....0027|
    +0D0    40C5D5C1    C2D3C5C4                            | ENABLED        |
    KEY = F000     LENGTH = 000010 (000A)                                     
    +000    D4C1D1D6    D940E3C5    E7E3                    |MAJOR TEXT      |
    KEY = F000     LENGTH = 000034 (0022)                                     
    +000    40C9C5C5    F7F3F5C9    40F1F74B    F2F74BF3    | IEE000I 17.27.3|
    +010    F940C4E4    D4D4E840    C4C9E2D7    D3C1E840    |9 DUMMY DISPLAY |
    +020    F2F3F4                                          |234             |
This symptom record indicates that this is a WTO error. It also indicates whether the WTO issuer was authorized. The symptom record also contains the following information:
  • The ASID, job name, program name, and an offset into the program that issued the WTO. You can use this information to help identify the issuer.
  • A description of the error.
  • The message line number where the error was detected.
  • The text of the first line, if the message is a multi-line WTO.

Once you diagnose the reason for the error, correct the WTO invocation to issue the message properly, or contact the owner of the application that is issuing the WTO to have it corrected.