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 |
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 (+).
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. 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. |
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.
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. |
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:
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. |
STEM | Name of the REXX stem variable array containing the text lines of the multiline WTO | 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.
|
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. 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.
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.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.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:
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:
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:
"AOEXEC WTO TEXT('"My_Text"') ROUTCDE(2,7) SSID(DL63)"
Related topic