POI Command Processors › OPSHFI Command Processor—Store Global Variable Values

OPSHFI Command Processor—Store Global Variable Values

The OPSHFI command processor provides the capability to store values of global variables on an external VSAM key-sequenced data set that can be shared among systems. Using OPSHFI, you can WRITE global variables to the VSAM file, READ variable records from the VSAM file, or DELETE variable records from the VSAM file.

Since global variables are usually checkpointed as their values change over time, you can use the OPSHFI command processor to reset variables to specific initial values at CA OPS/MVS initialization (or as required).

When the VSAM file is shared across systems, values can be propagated to or synchronized with other copies of CA OPS/MVS. This ability is useful when cross-system OPSVALUE function calls can be too voluminous.

In addition to invoking OPSHFI as a TSO command, you can invoke it as an OPS/REXX or TSO/E REXX function. The function has a single argument equal to the OPSHFI TSO command syntax. The value returned by the function is the count of retrieved VSAM records that were selected for processing. The CA OPS/MVS product sets the OPSRC variable to the same return code that would have been generated if you had invoked OPSHFI as a TSO command. When OPSHFI is invoked as a function in an AOF rule in which waits are not allowed, the NOOUTPUT keyword is implied.

Use this format for the OPSHFI command processor:

OPSHFI
{READ|WRITE|DELETE}
{namemask}
[CMDRESP(TERMINAL|NOWHERE)]
[DELAY(0,seconds)]
[GLVRULES(YES|NO)]
[OUTPUT|NOOUTPUT]
[SHARED|LOCAL]
[SMFID(smfid)]
[SUBSYS(OPSS,ssid)]
[SVRULES(YES|NO)]
[SYSTEM(msfids|ALL|EXT)]
[SYSWAIT(120,seconds)]

READ, WRITE, and DELETE

The READ, WRITE, and DELETE keywords indicate the function that you want to perform with this OPSHFI request. Specify any of the following:

READ

Reads every variable record from the VSAM file that meets the following criteria:

• The variable name matches the value of namemask.
• The scope of the variable matches the specified scope criteria.

For each variable record that is selected, the OPSHFI READ command creates a global variable using the variable name and value from the VSAM record. If a global variable was written as a shared variable, then it can be read into memory on any system that shares the VSAM file.

WRITE

Finds all global variables that match the value of namemask and writes their names and values to the VSAM file with the specified scope. The global variables can be written as shared variables or as local variables. Shared variables are made available to any system that shares the VSAM data set; however, local variables are available only to the system that wrote them. Writing global variables to VSAM does not change their values in memory. Likewise, subsequent updates to global variables in memory are not automatically sent to VSAM.

DELETE

Finds all matching variable records on the VSAM file and deletes them from the file. No global variables are altered.

Important! The DELETE keyword does not remove the variables from memory.

namemask

For the value of namemask, specify either a complete variable name or a variable name that includes one or both of the special characters described here. The CA OPS/MVS product searches through the global variables on the specified system and tries to find any names that match namemask.

The namemask can be up to the maximum global variable size in length, and is automatically converted to uppercase.

You can use two special characters in the namemask:

• + - Matches any single character in a variable name.
• * - Used as the last character in the namemask, this wildcard character matches any number of trailing characters in a variable name.

The namemask 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, or GLVTEMPx). Global stem prefix GLVJOBID is not supported by the OPSHFI function.
• An Automate-format variable name up to 32 characters in length. CA OPS/MVS looks at the values of the ATMSHAREDSCOPEnn parameters to determine the appropriate global variable stem prefix and adds it internally.

Guidelines for specifying namemask:

• If your name mask is for CA OPS/MVS global variable names, do not include wildcard characters in the first stem of the namemask value. Name masks for Automate-format variable names can include wildcard characters anywhere in the mask, since CA OPS/MVS adds the appropriate global or shared stem prefix to the mask internally.
• You can specify only global and shared variable names when you specify an Automate-format name mask. Automate built-in and environmental variable names are ignored.

Namemask examples:

GLOBAL0.ABCD*

Matches all CA OPS/MVS global variable names with 12 or more characters that begin with GLOBAL0.ABCD, such as GLOBAL0.ABCDEF.

TAPE_+++_STATUS

Matches all Automate-format variable names with 15 characters, where the sixth through eighth characters can be any character and the other characters are equal to those in the mask, such as TAPE_280_STATUS.

+++

Matches all Automate-format variable names composed of three characters.

+++*

Matches all Automate-format variable names composed of three or more characters.

GLVTEMP1.*

Matches all CA OPS/MVS global variable names that begin with the stem GLVTEMP1.

CMDRESP

(Optional) The CMDRESP keyword specifies how output is to be handled when OPSHFI executes.

Values are:

TERMINAL

Displays the response at the terminal.

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.

When you invoke your OPSHFI request as a TSO command, the default of CMDRESP is CMDRESP(TERMINAL).

When you invoke your OPSHFI request as an OPS/REXX or TSO/E REXX function, the default of CMDRESP is CMDRESP(NOWHERE).

DELAY

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

GLVRULES

(Optional) The GLVRULES keyword is an alias of the SVRULES keyword. Both keywords perform the same function. For details, see SVRULES Keyword in this chapter.

OUTPUT and NOOUTPUT

(Optional) If you specify OUTPUT, the following occur:

• The request is queued to the shared file server task in the CA OPS/MVS main product address space
• The command waits for the request to complete
• The command returns the count of variable records that were selected for processing

If you specify NOOUTPUT, no value is returned and return code 2 is set.

SHARED and LOCAL

(Optional) If you specify LOCAL, CA OPS/MVS sets the SMF ID to the SMF ID of the system on which the OPSHFI request executes.

If you specify SHARED, the SMF ID is blank. Only records with a blank SMF ID suffix are processed.

When the value of namemask begins with a stem (in other words, it is a
CA OPS/MVS-format name mask), the default is LOCAL. When the value of namemask is an Automate-format name mask, the default is LOCAL and SHARED because the Automate prefix tables are used to determine the correct scope.

SMFID

(Optional) Use the SMFID keyword to specify the SMF ID suffix that CA OPS/MVS should append to the VSAM variable name record key. If your OPSHFI request specifies the READ or DELETE keyword, CA OPS/MVS processes only those records having this SMF ID suffix. If your request specifies the WRITE keyword, CA OPS/MVS appends the specified SMF ID to each variable record that is written. There is no default.

SUBSYS

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

SVRULES

(Optional) The SVRULES keyword indicates whether you want the variables that OPSHFI changes to be processed by global variable rules. Values are:

• YES - Indicates that you want rules to process the variables.
• NO - (Default) Indicates that you do not want rules to process the variables.

Note: The SVRULES keyword applies only when you are requesting a READ of the VSAM file.

SYSTEM

(Optional) For more information on the SYSTEM keyword, 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.

SYSWAIT

(Optional) The SYSWAIT keyword specifies the number of seconds that CA OPS/MVS should wait for a response to the OPSHFI request on either the local system or a remote system. The default is 120; you can specify any number of seconds from 1 to 600. The default is high due to the possibility of reserve contention for control of the VSAM file among multiple systems.

Examples: OPSHFI

• This example reads every variable record from the VSAM file that meets these criteria:
  • The variable name matches the mask.
  • The variable record specifies the SMF ID of the local system.

  For each variable record that is selected, CA OPS/MVS creates or updates the corresponding global variable with the value in the record:

  OPSHFI READ GLOBAL0.XYZ+ABC* LOCAL
  

• This REXX function searches the global variable pool for matching names. For any matches it finds, it adds a record to the VSAM file (or updates a record already in the VSAM file) with the current value of the global variable. A blank SMF ID is appended to the variable name key. The number of VSAM records added or updated is returned in the cnt variable. The OPSRC variable is set to the same return code that would have been set if you had invoked OPSHFI as a TSO command:

  cnt = OPSHFI('WRITE GLOBAL0.SHARED.XYZ* SHARED')