POI Command Processors › OPSWTO Command Processor—Issue WTO and WTOR Messages

OPSWTO Command Processor—Issue WTO and WTOR Messages

The OPSWTO command processor issues one line and multiline WTO and WTOR messages from an OPS/REXX program, a TSO/E REXX program or CLIST, or a TSO READY prompt.

Important! Quotes are valid only around text values, as shown here: 'messageline1'. Using quotes around any other keyword value can cause an error.

This command has the following format:

OPSWTO
Specify one keyword from the following required keywords:
{TEXT('messageline1')|TEXT('messageline1' through 'messageline 255')|
TEXTVAR(prefix)}
[AREAID(consoleareaid)]
[CMDRESP(CLIST|REXX)]
[CNNAME|CONNAME(consolenames)]
[DELAY(delaytime)]
[DESC(descriptor codes)]
[HILITE|LOWLITE]
[KEY(amrf key)]
[LINETYPE(linetype)]
[MCSFLAGS(flag values)]
[MSGID(messageid)]
[OUTDELIM(delimstring,YES|NO)]
[PREFIX(prefix)]
[REPLY]
[ROUTE|ROUTECDE(routecodes)]
[SUBSYS(OPSS,ssid)]
[SYSTEM(msfids|ALL|EXT)]
[SYSWAIT(seconds)]
[TOKEN(dom token)]
[UPPERCASE(YES|NO)]
[WAIT|REPLYWAIT(300,seconds)]
[WTOID]

AREAID

(Optional) AREAID specifies the console area ID to display the message. You must use this keyword to specify the console to receive the message. You also must specify the DESC keyword with a value of 8 or 9.

You cannot use the AREAID keyword with the REPLY keyword.

CMDRESP

(Optional) When a CLIST or TSO/E REXX program issues the OPSWTO command processor, the CMDRESP keyword enables you to save the response to a WTO or WTOR message in CLIST or REXX variables. If you specify CMDRESP(CLIST), the response goes into CLIST variables. If you specify CMDRESP(REXX), the response goes into REXX stem variables. The default when executing under a TSO/E REXX or CLIST program is CMDRESP(CLIST). When executing under an OPS/REXX program, the default is to generate no variables.

If you specify a value for CMDRESP, OPSWTO does the following:

• Generates DOMID variables when you issue a WTO message with descriptor codes 1, 2, 3, or 11
• Generates reply variables for WTOR response text

OPS/REXX programs ignore the CMDRESP keyword and place responses to WTOR messages in the external data queue. For WTO messages, you can get the DOMID from the external data queue through the WTOID keyword.

The following lists the DOMID variables that the CMDRESP keyword generates for WTO messages:

• Variable contains the number of DOMID variables created

  CMDRESP(CLIST) Variable Name: DOMID0

  CMDRESP(REXX) Variable Name: DOMID.0

• Variable contains the first DOMID returned

  CMDRESP(CLIST) Variable Name: DOMID (equivalent to DOMID1)

  CMDRESP(REXX) Variable Name: no REXX equivalent

• Variable contains individual DOMID for console

  CMDRESP(CLIST) Variable Name: DOMIDn

  CMDRESP(REXX) Variable Name: DOMID.n

  (n is the count of DOMIDs)

The following lists the REPLY variables that the CMDRESP keyword generates for WTOR messages:

• Variable contains the number of reply lines

  CMDRESP(CLIST) Variable Name: no CLIST equivalent

  CMDRESP(REXX) Variable Name: REPLY.0

• Variable contains the text of the message reply

  CMDRESP(CLIST) Variable Name: REPLY

  CMDRESP(REXX) Variable Name: REPLY.n

  (n is the count of reply lines)

• Variable contains the number of words in the reply

  CMDRESP(CLIST) Variable Name: REPLYW

  CMDRESP(REXX) Variable Name: REPLY.n.0

• Variable contains the mth word of the reply text

  CMDRESP(CLIST) Variable Name: REPLYWm

  CMDRESP(REXX) Variable Name: REPLY.n.m

CNNAME and CONNAME

(Optional) Either the CNNAME keyword or the CONNAME keyword specifies the names of the consoles that receive the WTO or WTOR message. Specify up to 16 alphanumeric console names containing up to eight characters each.

DELAY

(Optional) The DELAY keyword defines how long OPSWTO suspends processing before executing the current command.

Specify any delay time between 1 and 300 seconds. DELAY has no default value.

DESC

(Optional) Use the DESC keyword to specify message descriptor codes for the current message. Descriptor codes are numbers between 1 and 16; codes 1 through 6 and descriptor code 11 are mutually exclusive.

You can assign codes 7 through 10 in combination with any other code, but each code must be unique. If you specify more than one code, separate them with commas as shown in the following example:

DESC(1,7) 

You can also enter any of the following descriptor code words:

• SYSFAIL - Equivalent to descriptor code 1
• IMEDACTN - Equivalent to descriptor code 2
• EVENACTN - Equivalent to descriptor code 3
• SYSSTAT - Equivalent to descriptor code 4
• IMEDCMD - Equivalent to descriptor code 5
• JOBSTAT - Equivalent to descriptor code 6
• APPLPRGM - Equivalent to descriptor code 7
• OOLMSG - Equivalent to descriptor code 8
• OPERREQ - Equivalent to descriptor code 9
• DYNSTAT - Equivalent to descriptor code 10
• CRITEVET - Equivalent to descriptor code 11
• HILITE - Equivalent to descriptor code 1

Notes:

• If numeric descriptor codes are used, leading zeros are not permitted.
• There is no support for descriptor codes when issuing a WTO with REPLY. Use of the DESC keyword and the REPLY keyword together results in an error condition and return code 12.

HILITE and LOWLITE

(Optional) These keywords determine how the WTO or WTOR message displays on the console that receives it. Specify HILITE to send a high-intensity, non-scrollable WTO or WTOR, or specify LOWLITE to make the message scrollable and displayed in low intensity.

KEY

(Optional) The KEY keyword specifies a key name that can be used to display messages that the z/OS AMRF feature retains (messages with descriptor codes 1, 2, 3, and 11). You can display AMRF messages using the following z/OS command:

D R,KEY=keyname

Note: The value of amrf key must consist of 1 to 8 EBCDIC characters. It will be left-justified and padded with blanks to create an 8-character key value. The value of amrf key cannot be an asterisk (*).

LINETYPE

(Optional) Use the LINETYPE keyword to designate control and label lines in a multiline WTO or WTOR message. Possible values for this keyword are:

• C - Message line 1 is a control line.
• CL - Message line 1 is a control line and line 2 is a label line.
• CLL - Message line 1 is a control line and lines 2 and 3 are label lines.
• L - Message line 1 is a label line.
• LL - Message lines 1 and 2 are label lines.

MCSFLAGS

(Optional) Use this keyword to enter MCS flag values, which are passed to the operating system. Each MCS flag is a unique character string. Following are sample MCS flags:

MCSFLAGS(REG0)
MCSFLAGS(BRDCST)

You can specify any of these flag values:

• RESP - The WTO is an immediate command response.
• REPLY - The 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.
• NOCPY - If a program in the supervisor state issues the WTO or WTOR macro instruction, do not queue the message for hard copy. Otherwise, ignore this flag.
• CMD - The WTO is a recording to a system command issued for hard copy log purposes. You can use the CMD flag only with MVS/XA or MVS/ESA, which are operating systems no longer supported by IBM.

MSGID

(Optional) This keyword defines the message ID that prefixes the WTO or WTOR text. If you omit the MSGID keyword, the OPSWTO command processor uses a default message ID, OPS1371I. Other message IDs can contain up to 10 characters. Message IDs are not padded with blanks.

OUTDELIM

(Optional) Use this keyword to specify two values:

• The delimiter string used to generate tokens for words in WTOR response text
• YES or NO, depending on whether you want delimiter strings to generate word tokens

A blank is always a delimiter. The defaults are YES and any of the following delimiter characters:

'( ) / = , '

Separate the two OUTDELIM operands with a comma, as shown in the following example:

OUTDELIM('@',NO)

PREFIX

(Optional) This keyword defines a prefix that becomes part of the names of variables generated when you specify the CMDRESP keyword, and you are issuing a highlighted message or a WTOR message. The default prefix for highlighted messages is DOMID. The default prefix for WTOR messages is REPLY.

REPLY

(Optional) Including this keyword in an OPSWTO command causes it to issue a WTOR message rather than a WTO. OPSWTO waits for the operator to respond (for the time specified with the WAIT keyword) and echoes any reply made with the TSO PUTLINE service. This is done so that a CLIST can pick the reply up using the TSO SYSOUTTRAP mechanism.

OPSWTO issues a return code showing whether it timed out or received a reply. The maximum reply length is 119 characters.

Notes:

• There is no support for descriptor codes when issuing a WTO with REPLY. Use of the DESC keyword and the REPLY keyword together results in an error condition and return code 12.
• The REPLY keyword and the TEXTVAR keyword are mutually exclusive.

ROUTE and ROUTECDE

(Optional) Use either keyword to enter route codes for the message. You can specify as many as 16 route codes, separated by commas.

A route code is any number between 1 and 128 or one of the following character strings:

SUBSYS

(Optional) For more information on the SUBSYS keyword, see Specifying a Subsystem ID on a POI Command Processor in this chapter.

SYSTEM

(Optional) For more information on the SYSTEM keyword, see Specifying an MSF System ID on a POI Command Processor in this chapter. See also the description of the SYSWAIT keyword.

SYSWAIT

(Optional) With this keyword, you can specify a number of seconds (from 1 to 300) of wait time to accommodate communication delays across systems. The CA OPS/MVS product adds the value of the SYSWAIT keyword to the MSFSYSWAIT value.

Note: See also the description of the SYSTEM keyword.

TEXT

This keyword specifies the text of a one line or multiline WTO or WTOR message.

To specify a one-line message, the text must meet these criteria:

• Contains up to 124 characters for a WTO or 124 characters for a WTOR message minus the length of the MSGID keyword.
• Uses a pair of quotes to indicate a single quote in the message text

Following are some sample text strings:

TEXT('this is a test value')
TEXT('put quotes in ''double'' quotes')

You can insert the contents of a REXX variable into the message text. For example, the following example inserts the contents of variable FIELDA into the message text as a text string:

TEXT('"||FIELDA||"')

To specify a multiline message, the text must meet these criteria:

• Contains as many as 255 lines of message text, each using as many as 70 characters
• Each text string must be enclosed in quotes and separated by blanks or a comma

TEXTVAR

This keyword provides a REXX variable name prefix for a set of variables, each variable containing one line of a multiline WTO message.

OPSWTO appends an ascending index number (beginning with 1) to the value you specify for prefix. For example, if you specify TEXTVAR(PREFIX_DATA), the names of variables storing your WTO are PREFIX_DATA1, PREFIX_DATA2, and so on.

OPSWTO stops reading variables when it encounters a null variable value.

If the OPSWTO command processor is executing in a TSO/E REXX or CLIST environment, you can use this keyword instead of the TEXT keyword. You cannot use the TEXTVAR keyword if the command processor is executing in the OPS/REXX environment; use the ADDRESS WTO host environment instead.

Note: The TEXTVAR keyword and the REPLY keyword are mutually exclusive.

TOKEN

(Optional) This keyword specifies a one- to four-character name or a four-byte hexadecimal value, such as ABCD or X'0A204200'. This token value can be used in delete-operator-message (DOM) processing to delete all messages with the same token value.

UPPERCASE

(Optional) This keyword determines whether the message text specified with the TEXT keyword is converted to uppercase characters. YES is the default.

WAIT and REPLYWAIT

(Optional) The WAIT and REPLYWAIT keywords are identical. Each determines how long OPSWTO waits for a WTOR reply or for a timer to expire. OPSWTO terminates with a failure code if it does not receive a WTOR reply before the wait time expires. As soon as the wait time expires, OPSWTO deletes all WTOR messages.

Specify any wait time between 1 and 3600 seconds; the default is 300 seconds (five minutes).

WTOID

(Optional) This keyword causes CA OPS/MVS to issue message OPS1349I, which displays the message number assigned by z/OS. This message number is the delete-operator-message ID (DOMID) of the message in X'01234567' format; it is also the last word of the WTO or WTOR message.