OPS/REXX Built-in Functions › OPSVALUE Function › Actions OPSVALUE Takes

Actions OPSVALUE Takes

OPSVALUE returns a value from the function call, and, in the case of some action codes, also places information in the external data queue.

You can specify the following actioncode values. If you omit the actioncode, then OPS/REXX uses the code V by default.

• 0 (Zero)
  • Obtains the value of a global variable. If the global variable does not exist, then OPS/REXX returns a zero.
  • Does not change the external data queue.

  Note: If you use this function, you cannot differentiate between a global variable that has a value of zero and a global variable that does not exist.

  Example:

  RTVL = OPSVALUE(derivedname,'0')
  

• 6 (Delete single variable)
  • Removes the node that the derived name specifies without removing any of its subnodes.
  • Returns 1 if the node was deleted; returns 0 if the node was not found.
  • Does not change the external data queue.
  • Does not allow other accessors of compound symbols to see partially updated symbol names.

  Example:

  RTVL = OPSVALUE(derivedname,'6')
  

• A (Add)
  • Adds a number that is specified by increment to the existing compound symbol given by derivedname
  • Returns the sum of the compound symbol and the increment.
  • Does not change the external data queue.
  • All references to the compound symbol are serialized during the ADD operation. You can use this function safely to increment a counter that concurrent tasks set.

  Example:

  RTVL = OPSVALUE(derivedname,'A',increment)
  

• C (Compare and update)
  • Updates a compound symbol after verifying its current value. If the node does not exist, then OPS/REXX creates it but assigns no value to it, giving the symbol the same value as its name.
  • Safely updates Global Compound Symbols that are shared by more than one rule or Global Compound Symbols that multiple copies of the same rule may access and update.
  • Does not change the OPS/REXX external data queue.
  • Returns one of the following values:
    • The REXX true value (1), if the comparison found the pre-action value of the symbol to be equal to old value and the compound symbol was updated.
    • The REXX false value (0), if the comparison found unequal values and therefore did not update the value of the compound symbol.
  • Serializes the compare and update operations for global variables.

  Example: To perform the Compare and Update action, four rather than three operands must be used with the 'C' code. The syntax is as follows:

  RTVL = OPSVALUE(derivedname,'C',newvalue,oldvalue)
  

  Usage Example: The following example demonstrates how to initialize a counter in the )PROC section of a rule safely, using the Compare and Update action code. After possible initialization, the counter is incremented using the Add action code. By using serialized OPSVALUE functions to initialize and increment the counter, this example safely allows for the possibility that multiple tasks running in the same address space can issue message IEF13241 concurrently.

  )MSG IEF13241
  )PROC 
  /* Load name of OPS job variable used to hold message */
  count per job. */
  counter='GLVJOBID.IEF13241'
  /*                                                       */
  /* Initialize the counter if it does not exist (i.e.     */
  /* this is the first IEF13241 message to be issued by    */
  /* this job since this rule was enabled.)  To allow for  */
  /* the possibility that another task in this same job    */
  /* has simultaneously issued another "first" IEF13241    */
  /* message and is executing this same rule concurrent    */
  /* to this task, use the serialized OPSVALUE Compare and */
  /* Update function:                                      */
    Temp = OPSVALUE(counter,'C',0,counter) 
  /* We do not care about the success of the above Compare */
  /* and Update. It will succeed only the first time that  */
  /* it is executed by this job.  In that case, since the  */
  /* variable does not yet exist, OPSVALUE will create the */
  /* variable and give it a value of its own name, causing */
  /* the Compare to succeed and the value to be Updated    */
  /* to 0.  The Compare will fail for all subsequent       */
  /* executions by this same job, since the variable will  */
  /* already exist, and its value will not be equal to its */
  /* own name.  In that case, the variable may have been   */
  /* initialized days ago by a task that is no longer      */
  /* attached, or it may have been initialized a           */
  /* microsecond ago by a task that is executing this same */
  /* rule concurrent to this task.  It does not matter.    */
  /* The counter is initialized only once per job.         */
  /*                                                       */
  /* Increment the counter by 1.  To allow for the         */
  /* possibility that another task in this same job has    */
  /* simultaneously issued another IEF13241 message and is */
  /* executing this same rule concurrent to this task, use */
  /* the serialized OPSVALUE Add function:                 */
    temp = OPSVALUE(counter,'A',1)
  RETURN
  

• D (Drop)
  • Performs the OPS/REXX DROP operation on the compound symbol that derivedname specifies. The compound symbol is reset to its uninitialized value; that is, its derived name. If derivedname is the name of a stem, then all compound symbols belonging to that stem are not only dropped, but also rendered nonexistent and the virtual storage that is allocated to them is released.
  • Returns the value of derivedname.
  • Does not change the external data queue.
  • All other references to the derivedname will either see the compound symbol as it existed before the DROP operation began, or as it is after the DROP operation completes.

  Example:

  RTVL = OPSVALUE(derivedname,'D')
  

• E (Existence)
  • Checks to see whether a given global variable exists.
  • Does not change the OPS/REXX external data queue.
  • Returns the status of a given global variable as one of these characters:
• I-Initialized
• U-Uninitialized
• N-does Not exist

  Example:

  RTVL = OPSVALUE('derivedname','E')
  

  Note: For most types of variables, N and U have interchangeable meanings. However, for global variables, N means that no storage exists for a variable; and U means that the variable exists in storage, but is uninitialized and is set to the value of its name.

• F (Find)
  • Checks to see if a given global variable exists. The F action is more efficient and more reliable than using the E and O functions together.
  • Returns the status of a given global variable as one of these characters:

    I-Initialized

    U-Uninitialized

    N-does Not exist

  When the returned value is not N (meaning that the derived name exists), the value of the node is returned on the external data queue. The maximum length of a string pulled from the external data queue is 350 bytes. CA OPS/MVS truncates longer values.

  Example:

  RTVL = OPSVALUE(derivedname,'F')
  

• H (High-level security)
  • Establishes an authorization status for subsequent global variable and SQL access requests made by an OPS/REXX program. This authorization status provides more efficient access to global variables and SQL tables for an OPS/REXX program.

    You can use this function from any environment that supports OPSVALUE, such as REXX programs, rules, GEM, and OPSLINK. However, for this function to be useful for OPSVALUE or ADDRESS SQL, you must use it in an OPS/REXX program.

    For OPSVALUE requests, you must specify one of the following values for the derivedname variable:

    • GLOBAL.READONLY
    • GLOBAL.READWRITE

    For ADDRESS SQL requests, you must specify one of the following values for the derivedname variable:

    • GLOBAL.SQLREADONLY
    • GLOBAL.SQLREADWRITE
  • Returns a value that describes the authorization status of the OPS/REXX program:

    AUTH-The request is permitted.

    NOTAUTH-The request is denied (no error message is issued).

    When the AUTH value is returned, subsequent OPSVALUE or SQL calls from the OPS/REXX program do not create the type of OPSGLOBAL or SQL security events that correspond to the authority level that was obtained on the preceding high-level security call. For example:

• If you specify GLOBAL.READWRITE on the function, and the returned value is AUTH, no subsequent OPSVALUE calls create security events.
• If you specify GLOBAL.READONLY on the function, and the returned value is AUTH, no subsequent OPSVALUE access-type calls create security events.
• If you specify GLOBAL.SQLREADWRITE on the function, and the returned value is AUTH, no subsequent ADDRESS SQL operations create security events.
• If you specify GLOBAL.SQLREADONLY on the function, and the returned value is AUTH, no subsequent ADDRESS SQL access-type operations create security events.
  • Results in an OPSGLOBAL product security event (SEC rule). The SEC.AUGLOPCH is set to H, and the SEC.AUGLRQTY variable is set to one of the following values:

    A (Access)-If you specify GLOBAL.READONLY or GLOBAL.SQLREADONLY

    U (Update)-If you specify GLOBAL.READWRITE or GLOBAL.SQLREADWRITE

  Examples:

  RTVL = OPSVALUE('GLOBAL.READONLY','H')
  

  RTVL = OPSVALUE('GLOBAL.READWRITE','H')
  

  RTVL = OPSVALUE('GLOBAL.SQLREADONLY','H')
  

  RTVL = OPSVALUE('GLOBAL.SQLREADWRITE','H')
  

• I (Information)
  • Returns information about all of the immediate subnodes of the derivedname to the external data queue

    The derivedname value must be a compound symbol node. The return value is the number of immediate subnodes that exist. The external data queue contains two lines per subnode: the first line contains the next segment of the derived name, and the second line contains statistics about the derived name. The second line that is returned for each derived name contains the following information. The first piece of information indicates the word number, the second indicates the length of the word, and the third describes the word.

• 1, 8-The number of subnodes under this subnode
• 2, 10-Creation date (in the form yyyy/mm/dd)
• 3, 8-Creation time (in the form hh:mm:ss)
• 4, 17-Creation ruleset.rule or program name
• 5, 8-Creation Jobname/Taskname/TSO ID
• 6, 10-Last modification date (in the form yyyy/mm/dd)
• 7, 8-Last modification time (in the form hh:mm:ss)
• 8, 17-Last modification ruleset.rule or program name
• 9, 8-Last modification Jobname/Taskname/TSO ID
• 10, 1-This word, which is reserved, always contains the value 0; provides compatibility with programs expecting a numeric value
• 11, 8-Number of updates to this node
• 12,10-Last access date (in the form yyyy/mm/dd) or the string NONE if the variable was created under an older release of the product. This information lets users determine when global variables have not been used in a long time and thus may be eligible for deletion:
  • Returns the number of subnodes that are listed in the external data queue
  • Places two lines per subnode in the external data queue
  • Returns no partially updated symbol names

  Example:

  RTVL = OPSVALUE(derivedname,'I')
  

• J (Immediate subtree count)

  Returns a count of all the immediate subnodes of derivedname.

  This action returns the same result value as the I or L action codes. However, the external data queue is not modified.

  Example:

  RTVL = OPSVALUE(derivedname,'J')
  

• K (subtree count)

  Returns a count of all the subnodes of the derivedname

  The result value that this action returns is the same value that the S or T action code returns. However, the external data queue is not modified.

  Example:

  RTVL = OPSVALUE(derivedname,'K')
  

• L (List)
  • Lists the derived names of all the immediate subnodes of derivedname by placing them on the external data queue

    The results of this action illustrate the difference between dropped symbols (processed by action D) and removed symbols (processed by action R). Dropped symbols still exist, so the List action can find them. The List action does not return removed symbols.

  • Returns the number of subnodes that are listed in the external data queue
  • Places a list of subnodes of the specified nodes in the external data queue
  • Returns no partially updated symbol names

  Example:

  RTVL = OPSVALUE(derivedname,'L')
  

• N (Null)
  • Obtains the value of a global variable. If the global variable does not exist, then OPS/REXX returns a null string.
  • Does not change the external data queue.

  Note: If you use this function, you cannot differentiate between a global variable that has a null string as its value and a global variable that does not exist.

  Example:

  RTVL = OPSVALUE(derivedname,'N')
  

• O (Obtain)
  • Obtains the value of a global variable. If the global variable does not exist, OPS/REXX returns an error
  • Does not change the external data queue

  Example:

  RTVL = OPSVALUE(derivedname,'O')
  

• R (Remove)
  • Removes the node that is specified by derivedname and all of its subnodes. Once a node is removed, it ceases to exist.
  • Returns the number of subnodes that are removed.
  • Does not change the external data queue.
  • Does not allow other accessors of compound symbols to see partially updated symbols.

  Example:

  RTVL = OPSVALUE(derivedname,'R')
  

• S (Subtree)
  • Lists the derived names of all the subnodes of derivedname in the external data queue. Action code S is similar to code L with two differences:
• OPS/REXX places the entire global variable name in the external data queue.
• All subnodes of the derived name are listed.
  • Returns the number of subnodes that are listed in the external data queue.
  • Places the entire global variable name in the external data queue.
  • Returns no partially updated symbol names.

  Example:

  RTVL = OPSVALUE(derivedname,'S')
  

• T (subTree/info)
  • Returns to the external data queue information about all the subnodes of the derivedname

    The derivedname value parameter must be a compound symbol node. The return value is the number of subnodes that exist. The external data queue contains two lines per subnode: the first line contains the next segment of the derived name, and the second line contains statistics about the derived name. The second line contains the following information, in which the first piece of information indicates the word number, the second indicates the length of the word, and the third describes the word.

    • 1, 8-The number of subnodes under this subnode (always contains a zero)
    • 2, 10-Creation date (in the form yyyy/mm/dd)
    • 3, 8-Creation time (in the form hh:mm:ss)
    • 4, 17-Creation ruleset.rule or program name
    • 5, 8-Creation Jobname/Taskname/TSO ID
    • 6, 10-Last modification date (in the form yyyy/mm/dd
    • 7, 8-Last modification time (in the form hh:mm:ss)
    • 8, 17-Last modification ruleset.rule or program name
    • 9, 8-Last modification Jobname/Taskname/TSO ID
    • 10, 8-This word, which is reserved, always contains the value 0; provides compatibility with programs expecting a numeric value
    • 11, 8-Number of updates to this node
    • 12,10-Last access date (in the form yyyy/mm/dd) or the string NONE if the variable was created under an older release of the product; permits users to determine when global variables have not been used in a long time and thus can be eligible for deletion.

    Action code T resembles code I with three differences:

    • The entire global variable name goes into the external data queue.
    • All subnodes of the derived name are listed.
    • The Number of Subnodes field on the second line of the pair of messages in the external data queue for each node always contains zero.
  • Returns the number of subnodes that are listed in the external data queue
  • Places in the external data queue two lines per subnode and the entire Global Variable name
  • Returns no partially updated symbol names

  Example:

  RTVL = OPSVALUE(derivedname,'T')
  

• U (Update)
  • Assigns newvalue as the value of the compound symbol that is specified by derivedname. If the compound does not exist, OPS/REXX creates it then gives it the new value.
  • Returns the value that is specified by newvalue
  • Does not change the external data queue
  • Prevents others accessing compound symbols from seeing partially updated symbols

  Example:

  RTVL = OPSVALUE(derivedname,'U',newvalue)
  

• V (Value)
  • Returns the current value of the node that is specified by derivedname. If the node does not exist, OPS/REXX creates it but assigns it no value. This assignment gives the symbol the same value as its name.
  • Does not change the external data queue.
  • Prevents the issuer of OPSVALUE from seeing partially updated symbols.

  Example:

  RTVL = OPSVALUE(derivedname,'V')