The WTO macro allows you to write messages to one or more operator consoles. See z/OS MVS Programming: Assembler Services Guide for more information on using WTO.
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. |
WTO 'USR001I FOR SPECIAL REQUESTS CONTACT SYSTEM SUPPORT',CONSID=,MF=L
If you specify parameter values on the list form, the system issues an MNOTE and ignores the data.
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 WTO errors, regardless of whether or not the message is actually displayed. For an example LOGREC symptom record, see Example 4.
SLIP SET,ENABLE,COMP=D23,ACTION=SVCD,END
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:
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=text addr | text addr: RX-type address or register (2) - (12). |
TEXT=(text addr,line type) | Note: If you code ‘msg’ or (‘text’...),
it must be the first positional parameter.
|
TEXT=((text addr,line type),...(text addr,line type)) | |
The permissible line types,
text lengths, and maximum numbers of each line type are shown below:
|
|
The maximum total number of lines that can be coded in one instruction is 10. | |
,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:
|
,DESC=(descriptor code) | descriptor code: Decimal number from 1 to 13. The descriptor code is one or more codes, separated by commas. |
,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). |
,CONSID=console id |
console id: RX-type address or register (2) - (12). |
The parameters are explained as follows:
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 routing codes are:
The message indicates a change in the system status. It demands action by the operator at the console with master authority.
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.
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.
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.
The message gives tape library information, such as a request by volume serial numbers for tapes for system or problem program use.
The message gives disk library information, such as a request by volume serial numbers for volumes for system or problem program use.
The message gives information about unit record equipment, such as a request to mount a printer train.
The message gives the status or disposition of teleprocessing equipment, such as a message that describes line errors.
The message gives information about security checking, such as a request for a password.
The message gives problem information for the system programmer, such as a system error, an uncorrectable I/O error, or information about system maintenance.
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.
The message gives information about emulation. (These message identifiers are not included in this publication.)
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.
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. |
The descriptor codes are:
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.
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.
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.
The message indicates the status of a system task or of a hardware unit.
The message is issued as an immediate response to a system command. The response does not depend on another system action or task.
The message indicates the status of a job or job step.
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.
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.
The message is written in response to an operator's request for information by a DEVSERV, DISPLAY, TRACK, or MONITOR command.
Descriptor code 10 is not currently in use.
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.
The message contains important information that must be displayed at a console, but does not require any action in response.
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.
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:
Hexadecimal 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:
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. |
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. |
WTO 'USR001I CRITICAL RESOURCE SHORTAGE DETECTED', X
ROUTCDE=(1,10), X
DESC=(2)
R0 EQU 0
R4 EQU 4
R5 EQU 5
.
.
.
LA R4,MYMSG ADDRESS OF MESSAGE AREA
L R5,SAVECNID CONSOLE ID
XR R0,R0 CLEAR REGISTER 0
WTO TEXT=(R4),CONSID=(R5),CART=SAVECART, X
DESC=(5)
.
.
.
MYMSG DC AL2(L'CATTXT)
CATTXT DC C'USR100I PROCESSING COMPLETE, NO ERRORS.'
SAVECART DS CL8
SAVECNID DS F
R0 EQU 0
.
.
.
XR R0,R0 CLEAR REG0 BEFORE MULTILINE
WTO TEXT=((MESSAG1,D),(MESSAG2,D),(MESSAG3,DE)), X
DESC=(7,12)
.
.
.
MESSAG1 DC AL2(L'MSG1TXT)
MSG1TXT DC C'USR005I ALL JOBS REQUIRING MORE THAN 2 TAPES MUST BE RUNX
ON THIRD SHIFT'
MESSAG2 DC AL2(L'MSG2TXT)
MSG2TXT DC C'JOBS REQUIRING 2 TAPES MAY BE RUN ON SECOND SHIFT'
MESSAG3 DC AL2(L'MSG3TXT)
MSG3TXT DC C'OR ON FIRST SHIFT WITH THE OPERATOR'S PERMISSION.'
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.