|
|
|
Use either of the following formats when using the ADDRESS OPER host command environment. Use format 1 when you do not want to specify any additional keywords.
ADDRESS OPER "keywords" {text}
ADDRESS OPER "keywords" [BMPCMDOUT(OPSLOG|WTO|NONE)] [COMMAND(text)] [CAPTURE(msgtextlist)] [CMDECHO(YES|NO)] [CMDLOG(YES|NO)] [CMDRESP(REXX)] [CMDWAIT(seconds)] [CONTYPE(ANY|EXTCONS|SSCONS|XTRACONS)] [DELAY(seconds)] [IMSID(name|*|list)] [IMSPLEX(name|*)] [IMSREPLY] [INTERVAL(centiseconds)] [LOCALONLY] [LOG(YES|NO|OFF)] [MAXCMDOUT(number)] [NAME|CONNAME(consolename)] [OUTPUT|NOOUTPUT] [PREFIX(name)] [PROPRESP] [STOPEND(YES|NO)] [STOPMSG(msgtextlist)] [STOPRESP(msgtextlist)] [SYSID|SYSTEM(systemids)] [SYSWAIT(seconds)] [VERBOSE(YES|NO)] [WAIT(seconds)] [XML(YES|NO)]
(Optional) Controls echoing of the current IMS command output. This keyword only applies if you are using an IOF BMP for issuing IMS commands. Possible values are:
Echoes all output associated with the current IMS command back to OPSLOG as trace messages. This results in a small amount of additional overhead to the command (assuming that the number of lines of output is not large). No output is sent back to any z/OS console or to the subsystem interface.
Echoes all output associated with the current IMS command as Write To Operator messages to the z/OS console. Note that using this option can add a significant amount of overhead to IMS command processing and has the potential of flooding the consoles with command output messages.
Sends IMS commands to the BMP and returns the responses to the issuing program (if so requested). This recommended approach results in the lowest amount of overhead.
The use of this keyword does not affect the way in which the IMS command output is returned to the command issuer.
(Optional) Indicates the text of the operator command you want to issue.
Note: If you specify the COMMAND keyword, it must precede any other keywords you specify.
(Optional) Captures command responses that are not internally routed back to the CA OPS/MVS console that issued the command. For correct usage of this keyword, see Utilizing the ADDRESS OPER Host Environment.
The CAPTURE keyword captures command response messages based on text segments matching the first characters (starting with column 1) of the messages. The command response messages captured by specification of this keyword are in addition to the usual command response messages captured by ADDRESS OPER, based on other specified keywords. You can specify up to ten message text segments with this keyword, and each text segment can be up to 124 characters.
For example:
CAPTURE(xyz, jbstr0004,IST02)
captures these messages:
xyz003 xyztest xyZ7 Fred is at lunch xyztest This is a test jbstr0004AX10 ist02test ist02job IST02 Today is Wednesday
If a text segment contains blanks, commas, quotes, or parentheses, you must enclose that segment in quotes. For example, the second segment in the following list contains blanks, so it is enclosed in single quotes:
CAPTURE(IST02,' JOBS M/S TS')
All message text segments specified on this keyword will match both uppercase and lowercase text in potential matching messages. For example, this segment:
CAPTURE('OPX0996I END OF')
Matches both of these messages:
OPX0996I end of exec OPX0996I END OF JOB
The CAPTURE keyword accepts the wildcard character *. If you specify CAPTURE(*), all messages are trapped.
Use the CAPTURE keyword to trap command responses that are not directed to the console where the command was issued. You can specify the CAPTURE keyword with either the STOPMSG keyword or the STOPRESP keyword.
(Optional) Instructs ADDRESS OPER to capture or omit the command echo line from the command response. You can specify either YES, which is the default, or NO.
Default: YES
(Optional) Determines whether the echo line from the command issued by ADDRESS OPER goes into the SYSLOG data set and the command response. You can specify either YES, which is the default, or NO.
Default: YES
When used to issue an IMS Type 2 message, CMDRESP(REXX)can be specified to create REXX variables. If CMDRESP is omitted, the output will be written to the EDQ. This option is only valid if IMS Type 2 message syntax is used.
For more information, see the section REXX Output from IMS Type 2 Message Reponses.
(Optional) Specifies, in seconds, how long ADDRESS OPER waits for command output collection to complete. ADDRESS OPER examines the number of lines collected every few hundredths of a second, based on the value specified with the INTERVAL keyword. If no new output lines are forthcoming after at least two output lines have been received, ADDRESS OPER terminates the response before the CMDWAIT period expires. The CMDWAIT period can be 1 to 600 seconds.
If the ADDRESS OPER includes the STOPEND(YES) keyword, the end line of a multi‑line WTO message also stops response collection. The main difference between the CMDWAIT and WAIT keywords is that WAIT specifies an unconditional wait period, while CMDWAIT specifies a conditional wait based on a continuous, timely collection of response lines. For correct usage of this keyword, see the 'Utilizing the Address Oper' and the 'Examples' section.
Default: The value of the CA OPS/MVS OCWAIT parameter.
When used in IMS Type 2 message syntax, the CMDWAIT and WAIT keywords are identical, and specify the maximum wait time in seconds for message completion. IBM documentation on IMSPLEX usage implies that the delay in gathering results from multiple IMS systems can be considerable, and should be considered normal. The default if omitted is 120, or 2 minutes.
(Optional) Specifies the appropriate type of console for the command you are issuing. The default for CONTYPE is the current value of the OCCONTYPE parameter. Values are:
CA OPS/MVS selects the first available console to issue the command. CA OPS/MVS selects consoles in the order listed here. The search order may change in a future release.
CA OPS/MVS selects the first available extended console. Extended consoles are controlled by the EXTENDEDCONSOLES parameter.
CA OPS/MVS selects the first available subsystem console. Subsystem consoles are controlled by the SUBSYSDEFAULT parameter.
CA OPS/MVS selects the first available extra extended console. Extra extended consoles are controlled by the EXTRAEXTCONSOLES parameter.
Notes:
(Optional) Specifies, in seconds, how long ADDRESS OPER pauses before processing the current system command. You can specify any number of seconds between 1 and 300.
This keyword can only be used within AOF rules. If logically possible, avoid using long delay values. Utilize dynamic AOF rules within automated applications that require a long delay or wait to occur prior to the issuing of a command or after the command has been issued. For examples of using dynamic TOD rules (time interval delay or wait) and dynamic MSG rules (event triggered delay wait), see the sample OPS/REXX programs SHUTCA7, SHUTDB2, and SHUTIMS in the hlq.SAMPLES CA OPS/MVS dsn.
Default: There is no default.
(Optional) If you use the IMS Operation Facility at your site, you can use the ADDRESS OPER command processor to issue IMS commands.
If you are running only one copy of IMS on the system where you issue the ADDRESS OPER command processor, you can omit the IMSID keyword. However, if several copies of IMS (such as a production version and a test version) reside on the system, use the IMSID keyword to specify the IMS control region that should receive the command.
IMS IDs can contain from one to four characters. IBM ships IMS with a default IMS ID of IMSA. If you do not know the IMS ID of the IMS you want CA OPS/MVS to control, ask your systems management department.
When used in IMS Type 2 message syntax, the command is issued to the IMSPLEX manager, and distributed from there. The IMSID is used to establish eligibility of participating IMS systems to receive the command. If the IMSID is omitted, the first IMS system capable of responding will receive the command. If IMSID is specified as a wildcard *, all participating IMS systems will receive the command. IMSID can also be specified as a list, separated by spaces or commas, of specific IMS system names to receive the command. The IMSID wildcard * should not be used unless the IMSPLEX keyword is specified with an explicit name.
Note: A list or a wildcard in the IMSID keyword may only be used in communication with the IMSPLEX manager. The IMSPLEX keyword must be specified in order for the command to be issued to more than one IMS.
The presence of the IMSPLEX keyword implies IMS Type 2 message syntax. It can be specified as a specific IMSPLEX name, in which case the IMSID keyword controls selection of participating IMS systems. IMSPLEX can also be specified as a wildcard *, meaning the IMSID determines the IMSPLEX name. In this case, the IMSID cannot be specified as a wildcard *, but must contain a valid IMS system name. The IMSID, or the first of a list, will be used to locate the name of its associated IMSPLEX.
(Optional) Causes the current IMS command to be issued using the IMS WTOR instead of the BMP. This keyword applies only if you use the IOF BMP to issue IMS commands. Other IMS commands issued using OPSCMD or ADDRESS OPER without this keyword will still go to the BMP.
Note: If the keyword is used for non-IMS commands, it is ignored. It will also be ignored when the IOF BMP facility is not in use. In that case, the IMS WTOR is already being used to issue IMS commands; therefore, the keyword is meaningless.
(Optional) Specifies, in centiseconds, how frequently ADDRESS OPER tests for command response lines to see if the response has ended. The INTERVAL value temporarily overrides the value of the CA OPS/MVS OCINTERVAL parameter.
The default for INTERVAL is the value of the OCINTERVAL parameter, but you can specify any number between 10 and 300, or a value of 0 to bypass interval testing.
For correct usage of this keyword, see the "Utilizing the Address Oper" and the "Examples" section.
(Optional) Indicates that only messages from the local system are considered as potential command response candidates.
This keyword should be used in conjunction with the CAPTURE and STOPMSG keywords to prevent output from other systems possibly being returned as command output.
(Optional) Determines whether response lines from the command issued by ADDRESS OPER go into the SYSLOG and/or OPSLOG data sets. Valid options are:
(Default) Command responses and command echo will be logged in both SYSLOG and OPSLOG.
SYSLOG will only contain the command echo, responses will not be logged. OPSLOG will contain both the command echo and command responses.
Command echo and command responses will not be logged to the SYSLOG. OPSLOG will contain the command responses, command echo will not be logged. If command output is being collected within an OPS/REXX program, the command echo will be omitted.
Command echo and command responses will not be logged in both SYSLOG and OPSLOG. If command output is being collected within an OPS/REXX program, the command echo will be omitted.
Default: YES
Notes:
(Optional) Defines how many command output lines ADDRESS OPER collects before terminating the command response. If the command output contains more lines than the MAXCMDOUT value, ADDRESS OPER stops collecting command output. You can specify any value between 1 and 32767 for MAXCMDOUT.
If the command is issuing IMS Type2 messages and generating REXX variables, the amount of output can become heavy when the VERBOSE option is specified in a busy IMSPLEX environment, and all participating systems respond. This parameter can limit the REXX output volume to a maximum of 32K variables.
Default: The value of the CA OPS/MVS OCMAXMSG parameter. If used to control REXX output from IMS Type 2 messages, the default is 16384.
(Optional) The NAME keyword and its equivalent keyword, CONNAME, define the name of the console to receive the command that ADDRESS OPER issues. The console name you provide can contain as many as eight characters. The NAME or CONNAME keyword and the ID keyword are mutually exclusive.
You can retrieve command output when the specified console is allocated to CA OPS/MVS. If the console is not allocated or does not exist, ADDRESS OPER issues a return code of 190.
(Optional) The mutually exclusive OUTPUT and NOOUTPUT keywords determine whether you receive output from the command issued by ADDRESS OPER.
Default: OUTPUT
The NOOUTPUT keyword requests that no command output be returned. ADDRESS OPER executes the specified command but creates no output variables and displays no command output lines. The NOOUTPUT and WAIT keywords are mutually exclusive. For correct usage of this keyword, see Utilizing the ADDRESS OPER Host Environment.
(Optional) Defines a prefix name for created variables.
Default prefix name: IMSTYP2
(Optional) This keyword is useful only when ADDRESS OPER is used in CMD rules. In all other environments, this keyword is ignored. When used in CMD rules, this keyword causes the console name and CART (Command and Response Token) associated with the command that triggered the CMD rule to be propagated to the CMD being issued by ADDRESS OPER. Use this keyword when you want the output of the command being issued through ADDRESS OPER to be associated with the original command that triggered the CMD rule.
(Optional) Determines whether the end line of a multiline WTO message stops ADDRESS OPER from collecting further command output. For correct usage of this keyword, see Utilizing the ADDRESS OPER Host Environment.
(Default)The command response terminates at the first end line of a multiline WTO message or at the time specified through the CMDWAIT keyword or the OCWAIT parameter.
ADDRESS OPER continues collecting command output until one of the following occurs:
Default: YES
(Optional) Specifies a list of one to ten message text segments matching the first characters (starting with column 1) of the messages that terminate the collection of command response lines. When ADDRESS OPER detects any of these text segments, it stops collecting response lines. The message segment or segments you specify need not be directed to the console receiving the command response. Each item in the list of message text segments you specify can contain no more than 124 characters.
All message text segments specified on this keyword will match both uppercase and lowercase text in potential matching messages. For correct usage of this keyword, see Utilizing the ADDRESS OPER Host Environment.
Note: STOPMSG does not work with IMS Type 2 commands.
(Optional) Specifies a list of one to ten message text segments matching the first characters (starting with column 1) of the messages that terminate the collection of command response lines. The message segments you specify must be directed to the console receiving the command response, and each item in the segment list can contain no more than 124 characters. You can use the STOPRESP keyword to terminate the collection of a long command response once the desired response line is found.
All message text segments specified on this keyword will match both uppercase and lowercase text in potential matching messages.
The STOPRESP and STOPMSG keywords are mutually exclusive. For correct usage of this keyword, see Utilizing the ADDRESS OPER Host Environment.
(Optional) For more information on the SYSID or SYSTEM keywords, see Specifying an MSF System ID on a POI Command Processor in this chapter.
Note: If more than one system is specified or implied, then the NOOUTPUT keyword is implied.
(Optional) Usually, when ADDRESS OPER issues a command to a remote system, the total wait time for a response to the command is the sum of two values:
The SYSWAIT keyword specifies a value, in seconds, that temporarily overrides the MSF delay time. You can specify a value from 1 to 600.
(Optional) Generates individual REXX variables to identify individual elements of the structured response and header data returned when an IMS Type2 command is issued. This option can lead to considerable volume in cases when several IMS systems under IMSPLEX control all respond to a command.
Default: NO
(Optional) Specifies that the ADDRESS OPER is to unconditionally wait for a period of time to receive output from the current command. In most cases a conditional wait using the CMDWAIT keyword in conjunction with the INTERVAL and various STOPxxxx keywords can be used to effectively collect command responses, thus eliminating the need for a unconditional WAIT. For details of how to successfully collect command response traffic, see Utilizing the ADDRESS OPER Host Environment.
When used in IMS Type 2 message syntax, the WAIT keyword is identical to CMDWAIT, and described there.
IMS Type 2 responses are all returned as text units within XML framing. The XML keyword can be specified as NO to strip both leading and trailing framing XML characters, or YES to include them with the output.
Default: NO
Usage Notes:
Keep these things in mind when you issue a command through the ADDRESS OPER host command environment:
| Copyright © 2011 CA. All rights reserved. | Tell Technical Publications how we can improve this information |