Previous Topic
Table Of Contents
Parent Topic
Next Topic

SWSVALUE Function for Shadow/REXX

Related Topics

Web Server API Function Index


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:

I
Initialized
U
Uninitialized
N
Does not exist

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:

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. 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: 

Word Length Description
1 8 Number of subnodes under this subnode
2 8 Create date (in the form yy/mm/dd)
3 8 Create time (in the form hh:mm:ss)
4 17 Create event procedure or program name
5 8 Create jobname, taskname, or TSO ID
6 8 Last modification date
7 8 Last modification time
8 17 Last modification event procedure or program name
9 8 Last modification jobname, taskname or TSO ID
10 8 Number of access to this node
11 8 Number of updates to this node

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:
  1. Shadow/REXX places the entire global variable name in the external data queue.
  2. All subnodes of the derived name are listed.

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:

  1. The entire global variable name goes into the external data queue.
  2. All subnodes of the derived name are listed.
  3. The "Number of Subnodes" field on the second line of pair of messages in the external data queue for each node always contains zero.

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')


Top