OPSREPLY Command Processor -- Compare WTOR Messages

The OPSREPLY command processor compares WTOR messages to a specified set of values and issues replies to messages containing matching values.
coema10
The OPSREPLY command processor compares WTOR messages to a specified set of values and issues replies to messages containing matching values.
 
 
This command has the following syntax:
OPSREPLY
You 
must
 choose 
at least one
 of the following keywords:
{IMSID(imsid)} {JOBNAME(jobname)} {JOBNUMBER(jobnum)} {MSGID(mgid)|MSGTEXT(mgtxt)} {REPLYID(replyid)} {STEPNAME(stepname)} In addition, you must specify the following required keyword: {TEXT(msgtext)} [CAPTURE(msgtextlist)] [CMDECHO(YES|NO)] [CMDLOG(YES|NO)] [CMDRESP(destination)] [CMDWAIT(seconds)] [DELAY(delaytime)] [INTERVAL(centiseconds)] [LOG(YES|NO|OFF)] [MAXCMDOUT(number)] [MAXREPLY(replies)|UNIQUE|ALL|ANY] [MFORM(M|J)] [NAME|CONNAME(consolename)] [NOCLIST] [NOSYSPLEX|SYSPLEX] [OUTDELIM(delimstring,YES|NO)] [OUTPUT|NOOUTPUT] [PREFIX(prefix)] [STOPEND(YES|NO)] [STOPMSG(msgtextlist)] [STOPRESP(msgtextlist)] [SUBSYS(ssid)] [SYSID|SYSTEM(msfids|ALL|EXT)] [SYSNAME(sysname)] [SYSWAIT(seconds)] [TRACE] [WAIT(0,waittime)]
The following list describes most of the keywords in the previous preceding syntax diagram. OPSCMD Command Processor provides details about the other keywords.
  •  
    ALL
    (Optional) Specifying the ALL keyword is the same as specifying MAXREPLY(9999). The MAXREPLY, ANY, ALL, and UNIQUE keywords are mutually exclusive.
  •  
    ANY
    (Optional) Specifies that OPSREPLY replies to the first WTOR message that matches the selection criteria, regardless of other WTOR messages that can match it. The ANY keyword is the opposite of the UNIQUE keyword. The MAXREPLY, ANY, ALL, and UNIQUE keywords are mutually exclusive. Specifying the MAXREPLY keyword implies the ANY keyword.
  •  
    CMDWAIT
    (Optional) Defines how long 
    CA OPS/MVS
     waits for response collection to complete.
    Value: 
    0 to 300 seconds
  •  
    DELAY
    (Optional) Defines, in seconds, how long 
    CA OPS/MVS
     suspends processing of the OPSREPLY command processor.
    Value: 1 to 300 seconds
    Default: 
    No default value
    Examples of using the DELAY keyword:
    OPSREPLY MSGID($HASPxxx) TEXT(WARM) DELAY(10) OPSREPLY MSGID(JEC107A) TEXT(U) DELAY(10) SUBSYS(OPSF)
  •  
    IMSID
    Identifies the IMS control region that issued the WTOR. For imsid, specify a region ID of up to four characters. For example, you can specify the following values:
    OPSREPLY IMSID(imsa) OPSREPLY IMSID(imst)
    If you do not also specify the MSGID keyword, OPSREPLY makes sure that the ID of the WTOR message is DFS996I, DFS972A, or DFS810A before determining whether to reply to it.
    The IMS ID strings are assumed to be at offsets of 25, 39, and 79.
  •  
    JOBNAME
    Specifies the name of the batch job, started task, or TSO user that issued the WTOR. A jobname can contain as many as eight characters.
    Unless you specify the ANY keyword, which is described later in this section, OPSREPLY sets a failure return code if several WTORs have the same job name and there is no other way to distinguish between them.
    If the WTOR message to be replied to came from an IMS region, use the IMSID keyword instead of JOBNAME.
  •  
    JOBNUMBER
    Specifies the specific JES job number of the issuer of the WTOR message. Specify only the numeric portion of the job ID; do not include the prefix (such as JOB, STC, or TSU).
    Value: 
    1 to 5 digits
  •  
    MAXREPLY
    (Optional) Specifies the maximum number of replies that OPSREPLY performs. The value of replies can range from 1 to 9999. OPSREPLY replies to all WTOR messages that meet the selection criteria you specify, up to the limit indicated by the MAXREPLY value. The MAXREPLY, ANY, ALL, and UNIQUE keywords are mutually exclusive. Specifying the MAXREPLY keyword implies the ANY keyword.
  •  
    MSGID
    This keyword identifies a specific message ID, which is usually (but not always) the first token in the message. A message ID can contain up to 10 characters. For information about message IDs that exceed ten characters in length, see the example that follows. For example, all of the following are valid message IDs:
    OPSREPLY MSGID(DSI802A) OPSREPLY MSGID(LUK0090A) OPSREPLY MSGID(DFS996I)
    Unless you also specify the ANY, ALL, or MAXREPLY keyword, OPSREPLY sets a failure return code if several WTORs have the same message ID and there is no other way to distinguish between them.
    If the length of the message ID text is 10 characters or less, the text refers to the formal message ID of the WTOR, as it does in AOF message rules. If the message ID text is more than 10 characters, the text is treated as if it was entered using the MSGTEXT keyword, which allows the selection of WTORs based on a leading substring of the message text. You can specify up to 124 characters.
    OPSREPLY MSGID('DSI803A A44IM REPLY') is the same as OPSREPLY MSGTEXT('DSI803A A44IM REPLY').
    The MSGID and MSGTEXT keywords are mutually exclusive.
  •  
    MSGTEXT
    This keyword allows you to select WTORs based on a leading substring of the message text. You can specify up to 124 characters. The first character of the substring comparison is always the message ID portion of the WTOR-the reply ID and special characters are skipped. The comparison text must match exactly, including spaces and delimiters, up to the length of the substring specified for this keyword. The MSGTEXT keyword cannot be abbreviated.
    The MSGID and MSGTEXT keywords are mutually exclusive.
    Examples: MSGTEXT keyword:
    • To reply to a particular NetView VTAM APPLID WTOR, specify:
      OPSREPLY MSGTEXT('DSI803A NETV1') TEXT('CLOSE IMMED')
    • To reply to either DSI802 or DSI803 NetView WTORs, specify:
      OPSREPLY MSGTEXT('DSI80') TEXT('CLOSE IMMED')
  •  
    NOSYSPLEX and SYSPLEX
    (Optional) Use these keywords if your site runs in a sysplex environment:
    •  
      NOSYSPLEX
      (Default) The OPSREPLY command processor limits its search for matching WTOR messages to those WTOR messages that originated on the current system in the sysplex. OPSREPLY ignores WTOR messages that originated from other systems. NOSYSPLEX is the default.
    •  
      SYSPLEX
      The search of the OPSREPLY command processor includes WTOR messages from all systems in the sysplex. Since cross-system REPLY commands can be issued from a sysplex console, specifying SYSPLEX permits WTOR messages that did not originate from the current system to be selected for a cross-system reply. Specifying the SYSNAME keyword implies the SYSPLEX keyword.
  •  
    REPLYID
    Identifies a specific WTOR message by its z/OS reply number. Depending upon the release of z/OS at your site, the value of replyid ranges from 0 to 9999.
  •  
    STEPNAME
    Supplies the z/OS job step name for the address space that issued the WTOR message. For started tasks, this value is the ID from either the z/OS START command or the PROC name.
    You can specify as many as eight characters for stepname. For instance, these step names are valid:
    OPSREPLY STEPNAME(UPDATE) OPSREPLY STEPNAME(DFHINIT)
    If several WTORs have the same job step name and no other criteria distinguish between these messages, OPSREPLY sets a failure return code.
  •  
    SUBSYS
    (Optional) For more information on the SUBSYS keyword, see Specify a Subsystem ID on a POI Command Processor.
  •  
    SYSID/SYSTEM
    (Optional) For more information on the SYSTEM keyword, see Specify an MSF System ID on a POI Command Processor.
     If more than one system is specified or implied, then the NOOUTPUT keyword is implied. Since specifying more than one system results in multiple systems replying to the same reply number, it is unlikely that you will ever specify more than one system. The capability is only included for compatibility with OPSCMD, whose services are used to issue the REPLY command on the target system.
    The SYSID/SYSTEM keywords do not imply that the OPSREPLY command is sent to another system. The checking for a matching WTOR is performed only on the local system. WTORs from other systems in the sysplex are only considered for matching if the SYSPLEX or SYSNAME keywords are also specified. The purpose of the SYSID/SYSTEM keywords is to issue the REPLY command on another system in the MSF complex.
    The SYSID/SYSTEM specified must be part of the same sysplex from where the OPSREPLY command is issued. If there is a need to go to a system outside the sysplex, then use the OPSRMT command processor.
    Example of how to use OPSRMT with OPSREPLY:
    OPSRMT SYSA Command('OPSREPLY MSGID(ABC123) text(u)')
  •  
    SYSNAME
    (Optional) Indicates the name of the z/OS system that issued the WTOR message. The value of sysname can be from one to eight characters, or * (asterisk) to indicate the current system. The SYSNAME refers to the SYSNAME keyword specified in the z/OS IEASYSnn parmlib member.
    Typically, you use this keyword to reply to:
    • (In a sysplex environment) WTOR messages issued by one system and received by another
    • WTOR messages issued by JES3 running on a local processor and received by the JES3 global processor
    If you specify a value for the SYSNAME keyword, the SYSPLEX keyword is implied. This is true unless you explicitly specify the NOSYSPLEX keyword.
     If the matched system name on a JES3 system is not the current system and the current system is the JES3 global processor, OPSREPLY prefixes the reply text with the JES3 SEND command so that it reaches the correct JES3 local processor.
  •  
    TEXT
    Supplies the text of the reply to the WTOR. Use single quotation marks to enclose the text if it contains delimiters and embedded blanks; otherwise, you can omit the quotes. To indicate a single quote in the text string, use a pair of single quotes as shown in the following example:
    OPSREPLY MSGID(RY0002A) TEXT('IN ''QUOTES''')
    Reply text can contain up to 119 characters. If the reply text exceeds the maximum reply length of the current WTOR, OPSREPLY sets a failure return code.
    Here are more examples of using the TEXT keyword:
    OPSREPLY MSGID(IEC107A) TEXT (U) OPSREPLY IMSID(IMSA) TEXT('/DIS ACTIVE') OPSREPLY JOBNAME(RYOSYS) TEXT('SHUTDOWN')
  •  
    TRACE
    Specify the TRACE keyword if you want messages indicating the WTOR selection criteria to appear in OPSLOG. If a reply ID for the WTOR was found, it appears along with the selection criteria.
    If the OPSREPLY command processor finds no WTOR messages that match the selection criteria, OPSLOG contains the selection data for each WTOR message that the OPSREPLY command processor examined in its search.
  •  
    UNIQUE
    (Optional) Specifies that OPSREPLY replies to the WTOR message if and only if one matching WTOR message is found. If more than one WTOR message matches the selection criteria, 
    CA OPS/MVS
     issues an error message. The MAXREPLY, ANY, ALL, and UNIQUE keywords are mutually exclusive. UNIQUE is the default.
  •  
    WAIT
    (Optional) Specifies how many seconds pass before OPSREPLY replies to a WTOR. WAIT enables you to reply to a WTOR that is usually (but not always) outstanding (such as a WTOR to which someone else is replying).
    You can specify a wait time between 1 and 3600 seconds; the default is zero. If the wait time is greater than zero, OPSREPLY looks once each second for a WTOR that matches the values specified with the JOBNAME, STEPNAME, MSGID, or IMSID keywords. It continues trying to respond to the WTOR until the wait time expires.
    Examples
    : Using the WAIT keyword:
    OPSREPLY MSGID(IEC107A) TEXT (U) WAIT(1) OPSREPLY IMSID(IMSA) TEXT('/DIS ACTIVE') WAIT(30)
How OPSREPLY Determines Which WTORs Receive Replies
OPSREPLY evaluates these message characteristics when selecting the WTOR to which it will reply:
  • The message origin, specified using these keywords: JOBNAME, MSGID, or IMSID
  • The job step of the program that issued the WTOR, specified using the STEPNAME keyword
You can specify more than one keyword. If you do, 
CA OPS/MVS
 evaluates all of their values as if you had specified them with a Boolean AND function.
If you specify the UNIQUE keyword or allow it to default, OPSREPLY compares the selection criteria to all WTOR messages. If more than one WTOR message meets the selection criteria, OPSREPLY issues an error message and does not perform the reply. If you specify the ANY keyword, OPSREPLY replies to only the first WTOR message that meets the selection criteria. If you specify the ALL keyword, OPSREPLY replies to all the WTOR messages that meet the criteria.
You can use the MAXREPLY keyword to specify the maximum number of WTOR messages OPSREPLY performs.
Considerations for Issuing OPSREPLY
Keep this information in mind when issuing the OPSREPLY command processor:
  • The OPSREPLY command processor internally calls the OPSCMD command processor to issue the z/OS reply command when:
    • You specify one or more OPSCMD command processor keywords in the text of the OPSREPLY command processor.
    • You specify a cross-system keyword (for example, SYSNAME or SYSPLEX) in the text of the OPSREPLY command processor.
    • OPSREPLY works across systems that are part of the same sysplex.
    The internal call to OPSCMD provides these benefits:
    • It enables OPSREPLY to take advantage of the cross-system capabilities of OPSCMD
    • It permits users to specify the CMDRESP(
      destination
      ,REPLY) keyword of OPSCMD to obtain the response to the reply command that will be issued. Variable output is also available; for example, you can specify CMDRESP(REXX,REPLY) to specify the generation of a series of REXX stem variables to hold the output.
  •  
    CA OPS/MVS
     converts the values of all keywords, including reply text, to uppercase characters.
  • In a JES3 environment, local WTOR messages appear on the global ORE chain as foreign OREs. Specifying the SYSPLEX or SYSNAME keyword can cause these OREs to be selected. When the reply must be routed to the local processor, the REPLY command is prefixed with the following:
    *T sysname
  • Whenever you specify an OPSCMD command processor keyword in the text of the OPSREPLY command processor, OPSREPLY links to OPSOSCMD. For a description of the OPSCMD command processor, see OPSCMD Command Processor.
  • In coded automation procedures, such as CLISTs or OPS/REXX programs, always specify the complete text of the OPSREPLY command processor and its keywords and operands. Doing so avoids syntax ambiguity in the future as we add new command processors to the 
    CA OPS/MVS
     product.
    If you are invoking the OPSREPLY command processor online, as you would during an interactive TSO session, you can use the shortest unique abbreviations. Be aware that the shortest unique abbreviation of a command processor, keyword, or operand can change from release to release.
OPSREPLY Return Codes
OPSREPLY produces these return codes:
 
Return Code
 
 
Message Number
 
 
Message Text
 
0
OPS1300
REPLY COMPLETED NORMALLY
4
OPS1301
JOBNAME, MSGID, AND IMSID MISSING
8
OPS1302
REPLY TEXT KEYWORD MISSING
12
OPS1303
WTOR NOT FOUND
16
OPS1304
AUTHORIZATION CHECK FAILED
20
OPS1305
MATCHING WTOR COUNT GREATER THAN MAX
24
OPS1306
REPLY TEXT LENGTH GREATER THAN MAX
80
OPS1320
TSO/E NOT INSTALLED
84
OPS1321
COMMAND BUFFER PARSE ERROR
88
OPS1322
COMMAND PROCESSOR NOT AUTHORIZED
92
OPS1323
AUTHORIZATION USER EXIT ABENDED
96
OPS1324
REPLY CONTROL BLOCK LOOP ERROR
100
OPS1325
SERIOUS SYSTEM MACRO ERROR
104
OPS1326
SERIOUS CONTROL BLOCK ERROR
n/a
OPS1350
WRITE CURRENT REPLY REQUEST ONTO THE SYSTEM LOG