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) [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 | optional 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 | optional 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 | optional No default is provided. numeric identifier of the console which to send the message |
SSID | SS () | specifies the subsystem of a local subsystem | required If the TGTSS() parameter is not specified, this SSID is the subsystem where the WTO is executed. Generic wildcard characters are supported for this parameter. 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 MainView AutoOPERATOR 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. |
TGTJNT() | optional | 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. |
AOOPTION | specifies the product options that must be active in the MainView AutoOPERATOR PAS. The following values are valid: ANV, CAO, IAO, IIZ, MAO, QAO, or TSH. IIZ represents the MainView AutoOPERATOR 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 MainView AutoOPERATOR 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. |
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(). | optional 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 | optional 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 mesage. 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. 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 | optional 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 | optional 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 | optional 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 | optional 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 | optional No default is provided. Flag names can be as follows:
|
TEXT | one-line text of the message | optional 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 | optional 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.
|
AREAID | Console area ID where the multi-line message is displayed | optional There is no default value for this parameter. 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. |
Return Codes from the WTO command are returned in variable IMFRC. The following table describes the possible return codes.
Return code value | Description |
|---|---|
Refer to 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 publication 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 OS/390 platform, review the description of the WTO macro in IBM publication 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 publication 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 OS/390 platforms, refer to the description of the WTO macro in the IBM publication 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)'