Description

Requirements for the caller are:

• You can issue a WTO of up to 10 lines. A WTO over 10 lines produces a return code of 04. The return code indicates that only 10 lines will be processed and the rest are ignored.
• The caller cannot have an EUT FRR established.

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.

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 WTO macro is written as follows:

line type    text        maximum number
C            34 char     1 C type
L            70 char     2 L type
D            70 char     10 D type
DE           70 char     1 DE type
             or
E            None        1 E type

The parameters are explained as follows:

‘msg’

(‘text’)

(‘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 parameter 'msg' is used to write a single-line message to the operator. In the format, the message must be enclosed in apostrophes, which do not appear on the console. 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'. The message text can include any character that can be used in a character (C-type) DC instruction. 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. The message 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 parameters ('text') and (text addr,line type) are used to write a multiple-line message to the operator. The text is one line of the multiple-line message. Inline text consists of a character string enclosed in apostrophes (which do not appear on the operator console). Any character valid in a C-type DC instruction can be coded. The maximum number of characters depends on which line type is specified. 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 IEE9321I), as explained under line type C below.

Note:

1. If the parameter (‘text’) is coded without repetition, for example, (‘text’), the message appears as a single-line message.
2. All lines of a multiple-line WTO must be consistently specified with the message text or the TEXT keyword. When coding the TEXT keyword for a multiple-line message:
   • You can specify a maximum of 10 lines.
   • Do not exceed the 70-character limit for the macro parameter value.
3. For a multiple-line message, you must clear the three high-order bytes of register 0.

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

D

Indicates that the “text” parameter contains the information to be conveyed to the operator by the multiple-line message. While you scroll through all lines of a multiple-line message displayed on an MCS console, the data lines are paged.

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

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

Note: Routing codes 1, 2, 3, 4, 7, 8, and 10 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 hard copy as a PARMLIB option or as a result of a VARY HARDCPY command.

,MCSFLAG=(flag name)

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

Table 1. MCSFLAG Flag Names for WTO Macro

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 hard copy only.
NOTIME	Do not append time to the message.
CMD	The WTO is a recording of a system command issued for hardcopy log purposes.

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

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.

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.

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.

9

Operator's Request

The message is written in response to an operator's request for information by a DEVSERV, DISPLAY, TRACK, 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.

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 may 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. These action messages will cause the audible alarm to sound on operator consoles so-equipped.

All WTO messages with descriptor codes of 1, 2, or 11 are action messages that have an @ sign printed before the first character. This indicates a need for operator action.

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 job step. The system adds descriptor code 7 to all messages with descriptor code 1 or 2.

On operator consoles that support color, descriptor codes determine the color in which a message should be displayed. The colors used are described in z/OS MVS System Commands.

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.

,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 ‘*’. 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.

,CONSID=console id

Specifies a 4-byte field containing the ID of the console to receive a message. If you specify a 4-byte console ID, or if you specify a console ID for an extended MCS console, you must use CONSID. To view a list of valid console IDs, issue the DISPLAY CONSOLES command.

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

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

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             |

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.