HLVVALUE API function

Use the HLVVALUE function to manipulate global variables.

For example, use the HLVVALUE function to use compound symbols as a type of database. Use this function in a rule that performs special interrogation or serialization processing.

Under normal circumstances, you can use a REXX language statement to reference or set the value of a global variable. The following code shows an example of using a REXX statement to

SAVENAME = GLOBAL.COMPANY.NAME
GLOBAL.COMPANY.NAME = "Keroct Software"
GLVEVENT.MYDATA = "ABC"

Syntax

val = HLVVALUE(derivedname, actioncode, newval, oldvar)

where:

derivedname is the name of the symbol that receives the action. When you use this parameter without quotation marks, simple symbols (case sensitive) following the stem are replaced by their values.
actioncode is the action to take on the symbol.
newval is the new value to assign to the symbol.
oldval is the value of the symbol before the action is taken.

Return values

HLVVALUE returns a value from the function call, and for some action codes, places information in the external data queue.

Action codes

The following table describes the actions that are performed for each action code and the values that are returned.

Table 1. Action Codes and return values
Action code	Description	Return value	Description
A (Add)	Adds a number, which is specified by increment, to the existing compound symbol given by `derivedname`. All references to the compound symbol are serialized during the add operation, so you can use this function to increment a counter that is set by concurrent tasks.	`val = HLVVALUE (derivedname'A' increment)`	Returns 1 (true) if the comparison finds the pre-action value to be equal to the old value and the compound symbol was updated. Returns 0 (false) if the comparison finds unequal values and does not update the value of the compound symbol. Does not change the external data queue.
C (Compare and update)	Verifies the value of a compound symbol and then updates its value. Safely updates global symbols that more than one rule uses or global symbols that multiple copies of the same rule might access and update. Serializes the compare and update operations for global values.	`val = HLVVALUE (derivedname,'C', newval,oldval)`	Returns 1 (true) if the comparison finds the pre-action value to be equal to the old value and the compound symbol was updated. Returns 0 (false) if the comparison finds unequal values and does not update the value of the compound symbol. Does not change the external data queue.
D (Drop)	Drops the compound symbol that is specified by `derivedname`. Resets the compound symbol to its uninitialized value or derived name. If `derivedname` specifies a stem, all compound symbols that belong to that stem are dropped and the virtual storage that is allocated to them is released. All other references see the compound symbol as it existed before the drop operation started or as it is after the drop operations finishes.	`val = HLVVALUE (derivedname,'D')`	Returns the value of `derivedname`. Does not change the external queue.
E (Existence)	Determines whether a global variable exists.	`val = HLVVALUE (derivedname,'E')`	Returns one of the following values for the status of the global variable: I: Initialized U: Uninitialized. The variable exists in storage, but it is uninitialized so it is set to the value of its name. N: Does not exist. The variable does not exist in storage. Does not change the external data queue.
F (Find)	Determines whether a global variable exists. The maximum length for a string pulled from the external data queue is 350 bytes. Longer strings are truncated.	`val = HLVVALUE (derivedname,'F')`	Returns one of the following values for the status of the global variable: I: Initialized U: Uninitialized. The variable exists in storage, but it is uninitialized so it is set to the value of its name. N: Does not exist. The variable does not exist in storage. When the return value is I or U, the value of the node is returned in the external data queue.
I (Information)	Returns information about all of the immediate subnodes of the `derivedname`.	`val = HLVVALUE (derivedname, 'I')`	For each subnode, places two lines in the external data queue. The first line contains the next segment of the `derivedname`. The second line contains the following information about the `derivedname`: Word 1, length 8: Number of subnodes under this node. Word 2, length 8: Create date, in the form yy/mm/dd. Word 3, length 8: Create time, in the form hh:mm:ss. Word 4, length 17: Create rule or program name. Word 5, length 8: Create job name, task name, or TSO ID. Word 6, length 8: Last modification date. Word 7, length 8: Last modification time. Word 8, length 17: Last modification rule or program name. Does not return partially updated symbol names.
L (List)	Lists the derived name of each subnode of the `derivedname`.	`val= HLVVALUE (derivedname, 'L')`	Returns the number of subnodes that are listed in the external data queue. Returns dropped symbols, but does not return removed symbols.
O (Obtain)	Obtains the value of a global variable.	`val = HLVVALUE (derivedname, 'O')`	Returns the value of a global variable. If the global variable does not exist, returns an error. Does not change the external data queue.
R (Remove)	Removes the specified node and all of its subnodes. After a node is removed, it ceases to exist.	`val = HLVVALUE (derivedname, 'R')`	Returns the number of subnodes that were removed. Does not change the external data queue. Does not allow other accessories of compound symbols to see partially updated symbols.
S (Subtree)	Lists the entire global variable name of all subnodes of the `derivedname`.	`val = HLVVALUE (derivedname,'S')`	Returns the entire global variable name of all of the subnodes in the external data queue. Returns the number of subnodes that exist, as listed in the external data queue. Does not return partially updated symbol names.
T (Subtree and information)	Lists the entire global variable name and all subnodes of the `derivedname`.	`val = HLVVALUE (derivedname,'S')`	Returns the entire global variable name and two lines for each subnode in the external data queue. The first line contains the next segment of the `derivedname`. The second line contains the information., as described for the Information code, for each `derivedname`. Does not return partially updated symbol names.
U (Update)	Assigns `newval` as the value of the compound symbol that is specified by `derivedname`. If the compound does not exist, the compound is created and assigned the new value. Use Update to prevent others who access compound symbols from seeing partially updated symbols.	`val = HLVVALUE (derivedname,'U',newval)`	Returns the variable that is specified by `newval`. Does not change the external data queue.
V (Value)	Returns the value of the specified compound symbol. Use Value to prevent the issuer of SDVALUE from seeing partially updated symbols.	`val = HLVVALUE (derivedname,'V')`	Returns the current value of the node. If the node does not exist, it is created but it is not assigned a value. Instead, it is given the same value as its name. Does not change the external data queue.