SWSVALUE Function for Shadow/REXX
Related Topics
 |
May be used in Shadow/REXX |
| |
May be used from Other REXX Interpreters (see SWSVALUE For Other REXX interpreters) |
| |
High-level language interface available |
Using this function, you can manipulate Global Variables in ways which are not possible in standard Shadow/REXX. For example, the SWSVALUE function lets you use compound symbols as a kind of data base.
 |
This Shadow/REXX intrinsic function has been exported for use by other REXX
interpreters (see Invoking Other REXX interpreters for additional information). However, the exported functionality differs considerably from the functionality described here, by allowing other REXX interpreters to access WWW Event-Related and GLVEVENT. Variables. Consult the page SWSVALUE For Other REXX interpreters for information on using this function from other REXX interpreters. The information on this page applies only to the Shadow/REXX implementation! |
Use this function to access only Global Variables. Do not use this function to access WWW. Event-Related Variables or GLVEVENT. Temporary Variables.
You need use this function only when some special interrogation or serialization processing is required by your Shadow/REXX procedure. Under normal circumstances, you can reference or set the value of a Global variable, simply by using it within a normal REXX-language statement, as in the following:
SAVENAME = GLOBAL.COMPANY.NAME
GLOBAL.COMPANY.NAME = "NEON Systems, Inc."
GLVEVENT.MYDATA = "ABC"
You should not create too many global variables under a single global variable stem. If you do, you will no longer be able to view them using the SWS/IPSF 7.1 Option, nor access them using the SWSVALUE function.
The absolute product limit is 32,768 variables under a single global variable stem. However, in practice, we strongly recommend that no more than 10,000 global variables exist at any given instant under a single global variable stem.
SWSVALUE Syntax
The SWSVALUE function has this format:
var = SWSVALUE(derivedname, actioncode, newval, oldval)
The arguments to the function are specified as follows:
- derivedname
- This argument gives the name of the symbol to be acted on. When you use this argument without quotation marks, simple symbols (which are case sensitive) following the stem are replaced by their values.
- actioncode
- Specifies the action to be taken on the symbol. The table below indicates what actions are taken.
- newval
- Supplies the new value (if any) to assign to the symbol.
- oldval
- Fetches the value of the symbol before the action takes place.
Return Values
SWSVALUE returns a value from the function call, and, in the case of some action codes, also places information in the external data queue.
The Chart below shows what actions are performed for each of the action codes values, and what values are returned.
| Action Code | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| A (Add) | Adds a number 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. That is, you can use this function safely to increment a counter that is set by concurrent tasks. Syntax Example: val = SWSVALUE(derivedname,'A',increment) |
||||||||||||||||||||||||||||||||||||
| C (Compare and Update) | Updates a compound symbol after verifying its current value. Safely updates Global symbols shared by more than one event procedure or symbols that multiple copies of the same rule might access and update. Does not change the Shadow/REXX external data queue. Returns the REXX "true" value (1), if the comparison found the symbol's pre-action value to be equal to old value and the compound symbol was updated, or 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. Syntax Example: val = SWSVALUE(derivedname,'C',newval,oldval) |
||||||||||||||||||||||||||||||||||||
| D (Drop) | Performs the Shadow/REXX DROP operation on the compound symbol specified
by derivedname. 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 just dropped, but also rendered "nonexistent" and the virtual storage allocated to them is released. Returns the value of derivedname. Does not change the external data queue. All other references either see the compound symbol as it existed before the DROP operation began, or as it is after the DROP operation completes. Syntax Example: val = SWSVALUE(derivedname,'D') |
||||||||||||||||||||||||||||||||||||
| E (Existence) | Checks to see whether a given global variable exists. Does not change the Shadow/REXX external data queue. Returns the status of a given global variable as one of these characters:
Syntax Example: val = SWSVALUE(derivedname,'E') Note: For normal REXX symbols N and U would 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 so 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:
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. Longer values are truncated. Syntax Example: val = SWSVALUE(derivedname,'F') |
||||||||||||||||||||||||||||||||||||
| I (Information) | Returns to the external data queue information about all of the immediate
subnodes of the derivedname. 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 returned for each derived name contains the information shown below:
Returns the number of subnodes listed in the external data queue. Places two lines per subnode in the external data queue. Returns no partially-updated symbol names. Syntax Example: val = SWSVALUE(derivedname,'I') |
||||||||||||||||||||||||||||||||||||
| 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 listed in the external data queue. Places a list of subnodes of the specified nodes in the external data queue. Syntax Example: val = SWSVALUE(derivedname,'L') |
||||||||||||||||||||||||||||||||||||
| O (Obtain) | Obtains the value of a global variable. If the global variable does not
exist, Shadow/REXX returns an error. Does not change the external data queue. Syntax Example: val = SWSVALUE(derivedname,'O') |
||||||||||||||||||||||||||||||||||||
| R (Remove) | Removes the node specified by derivedname and all of its subnodes. Once a
node is removed, it ceases to exist. Returns the number of subnodes removed. Does not change the external data queue. Does not allow other accessors of compound symbols to see partially-updated symbols. Syntax Example: val = SWSVALUE(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:
Returns the number of subnodes listed in the external data queue. Places the entire global variable name in the external data queue. Returns no partially-updated symbol names Syntax Example: val = SWSVALUE(derivedname,'S') |
||||||||||||||||||||||||||||||||||||
| T (Subtree/Info) | Returns to the external data queue information on 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 information in the format shown for the I actioncode. Action code T resembles code I with three differences:
Returns the number of subnodes 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 Syntax Example: val = SWSVALUE(derivedname,'S') |
||||||||||||||||||||||||||||||||||||
| U (Update) | Assigns newvalue as the value of the compound symbol specified by
derivedname. If the compound does not exist, Shadow/REXX creates it and gives it the new
value. Returns the variable specified by newvalue. Does not change the external data queue Prevents others accessing compound symbols from seeing partially-updated symbols Syntax Example: val = SWSVALUE(derivedname,'U',newval) |
||||||||||||||||||||||||||||||||||||
| V (Value) | Returns the current value of the node specified by derivedname. If the
node does not exist, Shadow/REXX creates it but assigns it no value (giving the symbol the
same value as its name). Returns the value of the specified compound symbol Does not change the external data queue Prevents the issuer of SWSVALUE from seeing partially-updated symbols Syntax Example: val = SWSVALUE(derivedname,'V') |