POI Command Processors › OPSGETV Command Processor—Retrieve Global Variable Value

OPSGETV Command Processor—Retrieve Global Variable Value

The OPSGETV command processor retrieves the value of a global variable that you specify. Depending on the keywords that you specify for your OPSGETV request, CA OPS/MVS either displays the value of the variable on your terminal or stores it in a CLIST or REXX variable.

You can retrieve the entire value of the variable, or only a substring portion of the value.

Note: If the variable that you specify does not exist, CA OPS/MVS returns a null value and no CLIST or REXX variable is created.

In addition to invoking OPSGETV as a TSO command, you can invoke it as an OPS/REXX or TSO/E REXX function. The function will have a single argument equal to the OPSGETV TSO command syntax. The value returned by the function will be the specified value of the variable. The CA OPS/MVS product sets the OPSRC variable to the same return code that would have been generated if you had invoked OPSGETV as a TSO command.

To invoke OPSGETV as a REXX function, use the following format:

OPSGETV
{varname}
[outputvar(ATMSV)]
[CMDRESP(TERMINAL|REXX|CLIST|NOWHERE)]
[DELAY(0,seconds)]
[OFFSET(displacement,length)]
[SUBSYS(OPSS,ssid)]
[SYSTEM(msfids)]
[SYSWAIT(seconds)]
[TOKEN(ATMSVTK,tkvname)]

varname

For the value of varname, specify the complete name of the global variable whose value you want to retrieve. The varname that you specify can be either of the following:

• A valid CA OPS/MVS global variable name beginning with a valid global variable stem prefix (GLOBAL, GLOBALx, GLVTEMPx, or GLVJOBID).
• An Automate-format variable name up to 32 characters in length. CA OPS/MVS looks at the values of the ATMLOCALSCOPEnn and ATMSHAREDSCOPEnn parameters to determine the appropriate global variable stem prefix and adds it internally.

outputvar

(Optional) When the OPSGETV command processor is running in a CLIST or REXX environment, use the outputvar operand to specify the name of the CLIST or REXX variable into which the retrieved variable value should be stored.

Note: If you specify a value for outputvar, it must precede any other optional keywords that you specify.

Default: ATMSV

CMDRESP

(Optional) The CMDRESP keyword specifies how the output from the OPSGETV command processor is handled. Values are:

TERMINAL

Displays the first 100 characters of the retrieved variable value and the update counter token value at the terminal. A plus sign (+) at the end of the retrieved variable value indicates that the value is longer than 100 characters.

REXX

Creates the REXX output variable specified by outputvar and the token variable specified by TOKEN(tkvname). Stores the retrieved variable value in outputvar and the retrieved update counter token value in tkvname.

CLIST

Creates the CLIST output variable specified by outputvar and the token variable specified by TOKEN(tkvname). Stores the retrieved variable value in outputvar and the retrieved update counter token value in tkvname.

NOWHERE

Tells CA OPS/MVS that it should not issue any messages except error messages. This option is provided to eliminate messages in REXX programs.

Default of CMDRESP when you invoke your OPSGETV request as a TSO command: both CMDRESP(TERMINAL) and CMDRESP(CLIST)

Default of CMDRESP when you invoke your OPSGETV request as an OPS/REXX or TSO/E REXX function: CMDRESP(REXX)

Note: Values of CMDRESP(CLIST) and CMDRESP(REXX) are honored only when the appropriate variable creation environment is possible.

DELAY

(Optional) The DELAY keyword indicates the number of seconds that your OPSGETV request waits before it can be processed. The default is 0; you can specify any number of seconds from 1 to 300.

OFFSET

(Optional) To retrieve only a substring portion of the value of a variable, use the OFFSET keyword to indicate two things:

• The substring displacement of the value to be retrieved, relative to 1
• The length of the value to be retrieved

CA OPS/MVS retrieves only the requested portion of the value of the variable. If displacement is outside the current value of the variable, CA OPS/MVS returns a null value. The range for both displacement and length is from 1 to 32,000. The default of displacement is 1; the default of length is the length of the current value of the variable.

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.

Note: You may specify a single system only.

SYSWAIT

(Optional) For a cross-system request, the SYSWAIT keyword specifies the number of seconds that CA OPS/MVS should wait for the remote system to receive and respond to the OPSGETV request. The default is the value of the MSFSYSWAIT parameter; you can specify any number of seconds from 1 to 600.

TOKEN

(Optional) Use the TOKEN keyword to specify the name of the CLIST or REXX variable that is to be set to the value of the update counter token. You can use this token value to perform a serialized update in a subsequent OPSSETV request. CA OPS/MVS sets tkvname only when the OPSGETV command processor is running in a CLIST or REXX program. The token value is only displayed or assigned to a variable when the TOKEN keyword is explicitly specified.

Default: ATMSVTK

Examples: OPSGETV

• This example retrieves the value and update token of the GLOBAL0.XYZ variable. If the command is issued from a CLIST or REXX program, CA OPS/MVS stores the retrieved value of the variable in the OUTVAR variable and stores the retrieved update counter token value in the OUTTK variable. In addition, CA OPS/MVS issues messages indicating the retrieved variable value and update token value:

  OPSGETV GLOBAL0.XYZ OUTVAR TOKEN(OUTTK)
  

• This REXX function finds the current value of the GLOBAL0.XY variable and retrieves the substring portion of the variable beginning at the fifth character of the value of the variable and continuing for a length of eight characters (or until the end of the variable value, whichever comes first). The resulting substring will be stored in the val variable. If the GLOBAL0.XY variable does not exist or an error occurs, the val variable is null. No messages except error messages are produced. The OPSRC variable is set to the same return code that would have been set if you had invoked OPSGETV as a TSO command:

  val = OPSGETV('GLOBAL0.XY OFFSET(5,8) CMDRESP(NOWHERE)')
  

OPSGETV Installation Requirements

OPSGETV Utilization Environments

OPSGETV Sample Coding Statements