Newer version of documentation BMC provides a newer version of the documentation for this version of the product. As a result, BMC no longer accepts comments in this space.BMC recommends upgrading to the latest version of the product. To see documentation for that version, see bao8301.

AOEXEC WTO


This command writes single or multiline messages to the system console.

Command

Parameters

AOEXEC WTO

[ROUTCDE(n1[,n2,n2,...nn])]

[DESC(n1[,n2,n2,...nn])]

[CONSOLE(consoleID)]

SS | SSID(subsystemID)

[AOOPTION | AOOPT(ANV, CAO, IAO, IIZ, MAO, QAO, or TSH)]

[TGTJNT()]

[TGTSS(targetSubsystemIdentifier)]

[AOOPTION(productOptions)]

[IDSTAMP(YES|NO|SS)]

[NAME(consoleName)]

[CART(tokenName)]

[TOKEN(tokenName)]

[KEY(keyName)]

[MCSFLAG(xx[,xx,xx,xx,...])]

[TEXT(messageText) | STEM(stemName)]

[AREAID(consoleID)]

The following table describes the parameters.

Parameter

Function

Notes

ROUTCDE

Routing code or codes to associate with the message

Specify one or more routing codes that will control the distribution of this message. If more than one code is specified, the list of codes will be separated by commas.

Up to 16 individual route codes can be specified on a single command.

Refer to Route codes usage for more information if this parameter is not specified.

DESC

Descriptor code or codes to associate with the message

Specify one or more descriptor codes that will control the appearance of this message. If more than one code is specified, separate each code with a comma. Refer to Descriptor codes usage for more information.

If not specified, defaults from the IBM WTO macro are used.

CONSOLE

Specific Console ID of the console to receive the message

No default is provided.

numeric identifier of the console which to send the message

Note

This parameter is mutually exclusive with the NAME() parameter. BMC recommends that you use the NAME() parameter.

This parameter is mutually exclusive with the AREAID keyword.

SSID | SS ()

Specifies the subsystem of a local subsystem

If the TGTSS() parameter is not specified, this SSID is the subsystem where the WTO is executed.

Generic wildcard characters are supported for this keyword. You can specify 1 to 4 asterisks (*) or plus signs (+).

  • If you specify a single asterisk (*), any BBI-SS PAS found on the same LPAR might be used to process the EXEC. You can also specify SS(P*) and the EXEC can be processed by any BBI-SS PAS that begins with P.

  • You can use also the plus sign (+) to indicate a positional wildcard such as SS(+++P). In this example, the EXEC can be processed on any BBI-SS PAS that ends in P.

Use the AOOPTION parameter to further filter on the wildcard value. By specifying a value with AOOPTION, you can route the EXEC to the BMC AMI OpsA BBI-SS PAS that is running a product option or group of product options.

AOOPTION is mutually exclusive with TGTSS and TGTJNT, and it is ignored on a fully qualified SSID specified with SS or SSID parameter.

AOOPTION

Specifies the product options that must be active in the BMC AMI OpsA PAS. The following values are valid: ANV, CAO, IAO, IIZ, MAO, QAO, or TSH.

IIZ represents the BMC AMI OpsA BMC Impact Integration for z/OS product. The stand-alone BMC Impact Integration for z/OS product does not support AOAnywhere.

The specified product option must be active in the BMC AMI OpsA PAS.

The value specified with the AOOPTION parameter is valid only when the SSID parameter specifies a wildcard value.

Note

EXEC processing ignores the AOOPTION parameter when a non-wildcard SSID is specified in the SSID parameter.

AOOPTION cannot be specified if TGTSS or TGTJNT are also specified.

TGTJNT()

A JNT entry that identifies the SSID which processes this request

Use this parameter to specify a different target from the target system where the EXEC is invoked. The specified TGTJNT() should match a TARGET=(tgtname) parameter that is entered in BBPARM member BBIJNT00.

The EXEC is scheduled on the subsystem that corresponds to the subsystem that is specified by the SS | SSID parameter of the JNT entry. The specified TGTJNT() may also be an SSID with which the original subsystem communicates.

This parameter is mutually exclusive with the TGTSS() parameter.

Note

The target subsystem named in the TGTJNT entry must exist within the current sysplex.

TGTSS

If the TGTSS() parameter is specified, the subsystem that is specified by the SS | SSID() parameter is considered a router and the actual function is executed on the subsystem that is specified by TGTSS().

The subsystem named in the TGTSS() parameter must be in the same sysplex as the subsystem named in the SS | SSID parameter and both systems must have the same XCFGROUP specified in BBPARM member BBISSP xx. If not specified, the value for SSID() is used.

IDSTAMP

Appends the subsystem ID to the end of the message

Specify either YES, NO, or SS.

  • If you specify IDSTAMP(YES), the command resolves the last 5 bytes of the value specified with the SS( ) | SSID( ) parameter (which can also contain a generic value) as the SSID. For example, specifying IDSTAMP(YES) and SSID(AB*) resolves the SSID to AB* in the WTO message.

  • If you specify IDSTAMP(SS), the command appends the last 5 bytes of the value specified with the SS( ) | SSID( ) parameter to the SSID of the subsystem where the message originates. For example, if the SSID is AB74, specifying IDSTAMP(SS) and SSID(AB*) resolves to the SSID to AB74.

Note

Specifying IDSTAMP(YES) or IDSTAMP(SS) reduces the available number of characters for user text in the first line of the WTO by 5 bytes and might cause the overlay of user data if the first text line is near its maximum length.

The SSID is never added to the minor lines of a multiline WTO.

The default value is NO.

NAME

Valid console name to where the message is sent

No default is provided.

When not specified, the WTO is issued from console 0 of the destination LPAR.

Note

This parameter is mutually exclusive with the CONSOLE() parameter.

CART

Command and Response Token to be associated with the message

Specify up to an 8-character value or a 16 character EBCDIC representation of the hex value of an 8-byte field.

Values fewer that 8 characters are padded on the right with blanks.

The command will fail with RC of 16 for invalid syntax of the CART value is 9-15 characters, or greater than 17.

For example:

CART(MYCART) CART(MYCART01) CART(C9E2C6D0840E82)

No default is provided.

TOKEN

Token to be used to identify a group of messages that can be deleted with a DOM macro that specifies the TOKEN parameter

Specify a 4-byte value containing any characters. This value must be unique within the AutoOPERATOR address space.

No default is provided.

KEY

Name of a key to associate with this message

Specify up to an 8-byte value of characters. The key must be EBCDIC if used with the MVS DISPLAY R command for retrieval purposes, but it must not be an asterisk (*). Values fewer that 8 characters are padded on the right with blanks.

No default is provided.

MCSFLAG

Specifies one or more flag names separated by commas

Flag names can be as follows:

  • BRDCST: Broadcast the message to all active consoles.
  • RESP: The WTO is an immediate command response.
  • HRDCPY: Queue the message for hardcopy only.
  • NOTIME: Do not append time to the message.
  • CMD: The WTO is a recording of a system command issued for hardcopy log purposes. If specified, the parameter TEXT() is required.
  • BUSYEXIT: If there are no message or console buffers for either MCS or JES3, or there is a JES3 WTO staging area excess, the WTO is terminated with a 60 return code.

No default is provided.

TEXT

One-line text of the message

When this parameter is specified, a one-line WTO is executed that contains the parameter's text value.

If not specified, it is assumed that a STEM variable is used.

The maximum length of text that can be specified is 126 characters.

Note

This is mutually exclusive with the STEM and AREAID parameters.

STEM

Name of the REXX stem variable array containing the text lines of the multiline WTO

Note

This parameter is mutually exclusive with the TEXT() parameter.

If neither TEXT() nor STEM() parameters are specified, a default STEM variable named LINE is used.

When STEM() is specified, it names the REXX stem variable to be used to pass in the text of the multiline WTO request as described below.

The maximum total number of lines allowed is 255. For more information about message text type codes, refer to the IBM publication MVS Programming: Assembler Services Reference, Volume 2.

  • Line.0: the total number of WTO lines contained in the array
    The maximum value allowed is 255.
  • Line.1: the first line of text
  • Line.Typ.1: optional text type descriptor of C, L, D, DE, or E
    If no descriptor is specified, a value of D is used.
  • Line.2-n: second through n lines of text up to the number specified in the Line.0 variable
  • Line.Typ.2-Typ.n: optional text type descriptor for each line as described above
Example

Set Line.0 to 5 and set variables Line.1 through Line.5 with text values to have a five line WTO issued.

AREAID

Console area ID where the multi-line message is displayed

Specify a 1-character alphabetic console area ID.

Value values are the letters from A through K, and the letter Z.

When you specify the AREAID parameter with a valid console ID, you must also specify the NAME parameter with a valid console name. When you specify the AREAID parameter, the WTO command automatically adds the descriptor codes 8 and 9.

This parameter is valid only when you also specify the STEM parameter or, use the default LINE stem variable.

You must specify the REXX stem variable array with the STEM parameter (or use the STEM parameter default) to capture the WTO message. You must also enter a control line using the LINE.TYP.1 variable with a value of C, or, you will see the IEE932I message as the WTO. The line is limited to 35 characters.

Note

This parameter is mutually exclusive with the TEXT and CONSOLE parameters.

There is no default value for this parameter.

Return Codes from the WTO command are returned in variable IMFRC. The following table describes the possible return codes.

Return code value

Description

See AOEXEC-common-return-codes for a description of return code values that are common to all AOEXEC commands. This table lists additional return codes for this AOEXEC command.

8

The number of lines available for the WTO does not match the value specified.

For example, if the default stem variable LINE is being used and LINE.0 is 10 but only WTO text variables LINE.1 through LINE.5 could be found, IMFCC is set to 8.

12

Value specified for STEM() could not be found in TSO pool.

16

Text line in a stem variable is too long; maximum length allowed is 71 characters

20

Internal error occurred.

24

Mutually exclusive parameters were coded.

60

WTO processing has been terminated because it would have caused a wait state, and BUSYEXIT was specified.

This error corresponds to a return code of x'20’ from the actual WTO macro call.

64

BUSYEXIT was not specified and WTO processing has been terminated.

Processing the WTO might have caused a WTO buffer shortage that would require a re-IPL. If this WTO was part of a multiple line WTO, the multiple line WTO is ended.

This error corresponds to a return code of x'24’from the actual WTO macro call.

68

When a ROUTCDE of 11 is specified, this value indicates that a required resource was not available and the request was ignored.

For any other routing code specification, the request was processed but one or more of the required resources was not available.

This error corresponds to a return code of x'30’ from the actual WTO macro call.

2048

When a value greater than 2048 is returned, this value indicates an unexpected return code was returned by the WTO macro call.

To decode the return code, subtract 2048, convert to hexadecimal, and look up the remaining value in the return codes list for the WTO macro in the IBM documentation MVS Programming: Authorized Assembler Services Reference, Volume 4.

Route codes usage

If you omit the ROUTCDE, DESC, and CONSOLE or NAME parameters on the AOEXEC WTO command, the system uses the routing code that is specified on the ROUTCODE parameter on the DEFAULT statement in the CONSOL xx member of SYS1.PARMLIB.

Note

Routing codes 1, 2, 3, 4, 7, 8, 10, and 42 cause hardcopy 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.

For complete details of the ROUTCDE values available on a specific MVS platform, review the description of the WTO macro in IBM documentation MVS Programming: Assembler Services Reference, Volume 2.

Descriptor codes usage

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 symbol indicates a need for operator action. These action messages cause an audible alarm to sound on operator consoles that are equipped with this feature. On operator consoles that support color, descriptor codes determine the color of the displayed messages. A specific color can indicate the type of action that the operator needs to take. The colors used for different descriptor codes are described in the IBM documentation z/OS MVS System Commands.

The system holds messages with descriptor codes 1, 2, 3, or 11 until the operator deletes them. When the messages with descriptor codes 1, 2, 3, or 11 are no longer needed, delete those messages by using delete operator message (DOM). If messages with descriptor codes 1, 2, 3, or 11 also have descriptor code 7, the system deletes them automatically at task termination. The system adds descriptor code 7 to all messages with descriptor code 1 or 2.

For more information about the DESC parameter values available for specific MVS platforms, see the description of the WTO macro in the IBM documentation MVS Programming: Assembler Services Reference, Volume 2.

Examples

Send a three line WTO that uses all defaults to the console of the current system by using the PAS on the current system. REXX EXEC code is as follows:

Line.0 = 3
Line.1 = 'This is the first line of the wto text'
Line.2 = 'that will continue onto this line and'
Line.3 = 'then onto this line before it is done'
'AOEXEC WTO SSID(DL63)'

Send a five-line WTO consisting of a control line, a label line, and three data lines to the console named CONS1. Use a stem variable named 'DATA' to pass in the WTO information. The WTO will be sent only to hardcopy and does not appear on any consoles. The REXX code is as follows:

Data.0 = 5
Data.1 = 'Performance Overview'
Data.Type.1 = 'C'
Data.2 = 'JobCnt    Messages   CPU    Steps'
Data.Type.2 = 'L'
Data.3 = '  6          25     10.33     12'
Data.Type.3 = 'D'
Data.4 = '  9         144      5.06      3'
Data.Type.4 = 'D'
Data.5 = '  22         17     12.53      4'
Data.Type.5 = 'DE'
'AOEXEC WTO STEM(DATA) NAME(CONS1) MCSFLAG(HRDCPY) SSID(DL63)'

Send a five-line WTO consisting of a control line, a label line, two data lines, and an end-of-wto null line to the console named CONS1. Use a stem variable named 'DATA' to pass in the WTO information. The REXX code is as follows:

/* rexx */
Data.0 = 5
Data.1 = "Performance Overview"
Data.Type.1 = "C"
Data.2 = "JobCnt Messages     CPU  Steps"
Data.Type.2 = "L"
Data.3 = " 6           25   10.33     12"
Data.Type.3 = "D"
Data.4 = " 9          144    5.06      3"
Data.Type.4 = "D"
Data.5 = " 5           62   15.06      2"
Data.Type.5 = "E"
"AOEXEC WTO STEM(DATA) NAME(CONS1) SSID(DL63)"

After issuing a WTOR, the operator responded by using Console CONS1. The variable IMFCONNM contains the name of the console. To send a single line WTO reply to the console named CONS1, the REXX code is as follows:

"AOEXEC WTO TEXT('here is the confirmation') NAME('imfconnm') MCSFLAG(resp) SSID(DL63)"

To send a single line WTO to the master console (route code 2) and all printer consoles (route code 7), the REXX code is as follows:

My_Text = 'start printing'
"AOEXEC WTO TEXT(''My_Text'') ROUTCDE(2,7) SSID(DL63)"

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*