GLOBALV : Rexx Global Variable function. Version 3.0
© Copyright : FadH Software 1989, 1998
This Rexx function enables the TSO/Rexx programmer to define and share
Rexx variables across execs. Using a 'Table' (or pool) mechanism, the
same named variable can be defined multiple times with different values.
Once defined, Rexx variables can be obtained by other execs within your
address space, either individually or by 'Table' name.
All Rexx variables defined are maintained until explicitly deleted or
when you logoff TSO.
GLOBALV uses an MVS/ESA Dataspace to store all the data. This provides a
robust and secure environment for data sharing across Rexx execs.
There are two limits that are set for the usage of GLOBALV.
Firstly, you cannot define more that 255 Tables.
Secondly, each table cannot contain more that 2Mb of variable data
(this includes the variable name itself plus 3 bytes of control
information per variable defined).
Examples of use :-
1) To set a Global variable called DATA in a table called TESTPOOL
!globalv="This is a test record"
rc=globalv("TESTPOOL","SET","DATA")
An alternative method is to pass the variable value as the 4th
parameter, for example :-
rc=globalv("TESTPOOL","SET","DATA","This is a test record")
If you already have a variable containing the data you wish to assign
to a variable, you could do the following,
record1="This is a test record"
rc=globalv("TESTPOOL","SET",data,record1)
Note : The SET parameter can also be specified as ADD
2) To retrieve the above defined variable, you would do the folllowing,
rc=globalv("TESTPOOL","GET","DATA")
If have multiple variables defined within a Table, you can retrieve
them all in one operation, as follows,
rc=globalv("TESTPOOL","GET")
3) To delete a variable within a Table, do the following,
rc=globalv("TESTPOOL","DELETE","DATA")
This would delete the variable called DATA within the Table called
TESTPOOL.
All other variables within the TESTPOOL table are retained.
4) To delete all the variables within a Table, you have to purge the
Table. This is accomplished as follows,
rc=globalv("TESTPOOL","PURGE")
5) To delete all defined pools and the variables within them, use the
PURGEALL parameter.
rc=globalv("PURGEALL")
6) If you wish to check on the existence of a particular Table, you
should do the following,
rc=globalv("TESTPOOL","CHECK")
If the Table exists the rc variable will be set to 0 (zero),
otherwise a return code of 4 (four) is set.
This function only checks for the existence of the Table, not
whether there are any variables defined within it.
7) If you wish to set many unique variables, you should use the STREAM
option as opposed to SET variable.
This is much faster than setting variables individually, as it
creates successive variables without checking for their prior
existence.
If you have many different variables to set, most likely a large
number of stem variables, then you should use the stream option.
For example,
do n=1 for count
other rexx code here
rc=globalv("JCLDECK","STREAM","JCLREC."n,datarec.n)
other rexx code here
end
If during the STREAM option, you set a variable that already exists,
the new value will be added in the table. However, the previous
variable value will also still exist. This causes two different
results when retrieving the variable.
If you request the variable explicitly, you will obtain the first
value set. If you request all the variables within that table, the
value for the variable will be the last one set.
Therefore, due to the possibility of retrieving an incorrect variable
value, you should only use the stream option for many uniquely named
variables.
8) To obtain certain diagnostic information from GLOBALV use the DEBUG
parameter. This will show the Version of GLOBALV running, the address
where it is loaded, the name of the GLOBALV Dataspace and the STOKEN
of the Dataspace.
rc=globalv("DEBUG")
Error messages.
Message - IRXGLO001E Invalid Group name specified
Reason - The table name is invalid.
Message - IRXGLO002E Invalid Variable name specified
Reason - The variable name is invalid (not defined in table).
Message - IRXGLO003E Group name table full, unable to add group grpn
(where grpn is the name of the group)
Reason - You have already defined 255 different Tables.
Message - IRXGLO004E Invalid/Missing Parameter
Reason - A function parameter passed to GLOBALV is invalid/missing.
Message - IRXGLO005E Insufficient storage, variable not added
Reason - There is not enough storage available within the table
to add the new variable.
Message - IRXGLO006E Error using IKJCT441, RC=nnnn
Reason - There was an error using the Rexx variable interface.
The RC shown should be noted for further diagnosis.
Message - IRXGLO007E Error obtaining TCB Token, RC=nnnn
Reason - There was an error obtaining the TCB Token. This token is
required for the Dataspace functions.
The RC shown should be noted for further diagnosis.
Message - IRXGLO008E Error creating Dataspace, RC=nnnn
Reason - There was an error creating the Dataspace.
The RC shown should be noted for further diagnosis.
Message - IRXGLO009E Error creating Access List Entry, RC=nnnn
Reason - There was an error adding the Access List Entry (ALET).
The RC shown should be noted for further diagnosis.
Message - IRXGLO010E Error extending Dataspace, RC=nnnn
Reason - There was an error extending the Dataspace.
The RC shown should be noted for further diagnosis.
The new table requested was not added. Existing tables can
still be accessed.
Message - IRXGLO011E Error creating Name/Token pair, RC=nnnn
Reason - There was an error creating the Name/Token pair.
The RC shown should be noted for further diagnosis.