&WTO

This verb issues an MVS or VM WTO.

The verb lets an NCL procedure issue an MVS WTO. Optional parameters allow specification of routing and descriptor codes, special MCS flags, and system console ID.

In z/VM, the &WTO verb writes a message to the GCS console.

This verb has the following format:

&WTO [ CONSOLE={ nn | name } ] 
     [ DESC={ NONE | list } ] 
     [ MCSFLAG=( [ RESP ] [ ,REPLY ] [ ,BRDCST ] [ ,HRDCPY ] ) ] 
     [ ROUTCDE={ NONE | list } ] 
     [ LINETYPE={ NO | C | L | D | DE | E } ]  
       DATA=message text

Operands:

CONSOLE={ nn | name }

Specifies the ID of the system console to which to queue the message. The operand uses the REG0 MCSFLAG to queue the WTO conditionally to the nominated console. If this parameter is used with the ROUTCDE parameter, then the message is queued to consoles based on routing code and the specified console ID.

On z/OS, you can use CONSOLE=name (name being a valid console name).

DESC={ NONE | list }

Allows specification of a list of MVS descriptor codes. The list is a single code, from 1 to 16, or a list of codes and ranges, as shown:

DESC=5 DESC=(1,7,8-12)

If no descriptor codes are specified, MVS typically supplies a default of 7.

Some MVS descriptor codes (for example, 1, 2, or 11) cause the message to become Non-Roll-Delete (NRD). The message remains on MVS (and system) consoles until deleted by an MVS DOM (which the &DOM verb produces). Take care when using these descriptor codes, as overuse could lead to system console buffer shortages.

MCSFLAG=( [ RESP ] [ ,REPLY ] [ ,BRDCST ] [ ,HRDCPY ] )

Allows specification of MCSFLAG values. If only a single value is required, MCSFLAG=flag is used. If more than one is required, the list must be enclosed in brackets and separated by commas, for example, MCSFLAG=(flag,flag...).

The allowable MCSFLAG options are:

RESP: Indicates that this WTO is a command response.
REPLY: Indicates that this WTO is an echo of a reply to a WTOR.
BRDCST: Broadcasts this WTO to all consoles, irrespective of routing codes.
HRDCPY: Indicates that this WTO is to be a hardcopy-only WTO; that is, to be logged to SYSLOG, but not sent to any console.

The only other MCSFLAG values that &WTO uses are the ROUTCDE/DESC present flag, and the REG0 flag, set if CONSOLE= is specified.

ROUTCDE={ NONE | list }

Allows specification of a list of MVS routing codes. ROUTCDE values are from 1 to 128.

A single value is specified as ROUTCDE=n. Multiple values and ranges are specified as follows:

ROUTCDE=(4,13,27)
ROUTCDE=(1-5,16,40-55)

LINETYPE={ NO| C | L | D | DE | E }

Allows specification of a multiline WTO.

The operand has the following values:

NO generates a single-line WTO.
C (Control) starts the multiline WTO.
L (Label) specifies a label line.
D (Data) specifies the body of the multiline WTO.
DE specifies a data line that also ends the multiline WTO.
E ends the multiline WTO when no more data exists.

Values other than NO allow you to build up a multiline WTO, one line at a time. The multiline WTO is complete when a data-end (DE) or end (E) line is sent. &ZDOMID contains the same value after each line of a multiline WTO. You can write a single-line WTO during generation of a multiline WTO.

All other &WTO operands except DATA are ignored when specified on the second and subsequent lines of a multiline WTO.

The DATA operand is not mandatory for LINETYPE=E.

&RETCODE is set to the WTO macro return code after an &WTO when LINETYPE is other than NO.

Default: NO

DATA=message text

Specifies the text of the message to WTO. Maximum length of the message is 126 characters.

Examples: & WTO

&WTO DATA=AOM IS HERE!!!! 
&WTO CONSOLE=1 DESC=1 DATA=HELP!!!! 
&WTO ROUTCDE=(1,2,11) +
        DATA=Note: Configuration file updated.

Notes:

When using &WTO, consider these recommendations:

Always provide a message identifier at the start of the message. Use this identifier to establish some connection with the issuer of the &WTO.
Avoid using descriptor codes 1, 2, or 11. These descriptor codes cause the messages to become Non-Roll-Delete (NRD) and can lead to excessive numbers of NRD messages being displayed.
Excessive use of &WTO can lead to console buffer shortages.

Following &WTO, the system variable &ZDOMID contains the MVS-assigned message identification or DOMID, as an eight-hexadecimal digit value. This value is used in a subsequent &DOM verb to delete the message. This is important if descriptor codes that make the message NRD are used (typically 1, 2, and 11).

The &WTO verb generates an MVS WTO. Thus, the message is seen and processed like any other WTO message.

While z/VM supports the WTO macro, only the text parameter is used.

The &RETCODE variable is set to the MVS WTO return code when a multiline WTO is issued.

Note: For more information about MCSFLAG values, see the IBM publication MVS Programming Authorized Assembler Services Reference.

More information:

&WTOR

&DOM