Application programs can use the Rexx Variable Pool Interface to manipulate the variables of a currently active Rexx procedure.
Three of the Variable Pool Interface functions (set, fetch, and drop) have dual interfaces.
The symbolic interface uses normal Rexx variable rules when interpreting variables. Variable names are valid Rexx symbols (in mixed case if desired) including compound symbols. Compound symbols are referenced with tail substitution. The functions that use the symbolic interface are RXSHV_SYSET, RXSHV_SYFET, and RXSHV_SYDRO.
The direct interface uses no substitution or case translation. Simple symbols must be valid Rexx variable names. A valid Rexx variable name:
Does not begin with a digit or period.
Contains only uppercase A to Z, the digits 0 - 9, or the characters _, ! or ? before the first period of the name.
Can contain any characters after the first period of the name.
Compound variables are specified using the derived name of the variable. Any characters (including blanks) can appear after the first period of the name. No additional variable substitution is used. RXSHV_SET, RXSHV_FETCH, and RXSHV_DROP use the direct interface.
Only the main thread of an application can access the Rexx variable pool. Applications can create and use new threads, but only the original thread that called RexxStart can use RexxVariablePool.
Executable Windows modules called from a Rexx procedure execute in a new process. Because the modules do not use the same process and thread as the Rexx procedure, the modules cannot use RexxVariablePool to access Rexx variables. You can use RexxVariablePool from subcommand handlers, external functions, and exit handlers.
Rexx procedure variables are accessed using the RexxVariablePool function.
RexxVariablePool accesses variables of a currently active Rexx procedure.
retc = RexxVariablePool(RequestBlockList);
is a linked list of shared variable request blocks (SHVBLOCK). Each block is a separate variable access request.
The SHVBLOCK has the following form:
typedef struct shvnode {
struct shvnode *shvnext;
RXSTRING shvname;
RXSTRING shvvalue;
ULONG shvnamelen;
ULONG shvvaluelen;
UCHAR shvcode;
UCHAR shvret;
} SHVBLOCK;where:
is the address of the next SHVBLOCK in the request list. shvnext is null for the last request block.
is an RXSTRING containing a Rexx variable name. shvname usage varies with the SHVBLOCK request code:
shvname is an RXSTRING pointing to the name of the Rexx variable that the shared variable request block accesses.
shvname is an RXSTRING defining an area of storage to receive the name of the next variable. shvnamelen is the length of the RXSTRING area. If the variable name is longer than the shvnamelen characters, the name is truncated and the RXSHV_TRUNC bit of shvret is set. On return, shvname.strlength contains the length of the variable name; shvnamelen remains unchanged.
If shvname is an empty RXSTRING (strptr is null), the Rexx interpreter allocates and returns an RXSTRING to hold the variable name. If the Rexx interpreter allocates the RXSTRING, an RXSHV_TRUNC condition cannot occur. However, RXSHV_MEMFL errors are possible for these operations. If an RXSHV_MEMFL condition occurs, memory is not allocated for that request block. The RexxVariablePool caller must release the storage with GlobalFree(ptr).
Note: The RexxVariablePool does not add a terminating null character to the variable name.
An RXSTRING containing a Rexx variable value. The meaning of shvvalue varies with the SHVBLOCK request code:
shvvalue is the value assigned to the Rexx variable in shvname. shvvaluelen contains the length of the variable value.
shvvalue is a buffer that is used by the Rexx interpreter to return the value of the Rexx variable shvname. shvvaluelen contains the length of the value buffer. On return, shvvalue.strlength is set to the length of the returned value but shvvaluelen remains unchanged. If the variable value is longer than the shvvaluelen characters, the value is truncated and the RXSHV_TRUNC bit of shvret is set. On return, shvvalue.strlength is set to the length of the returned value; shvvaluelen remains unchanged.
If shvvalue is an empty RXSTRING (strptr is null), the Rexx interpreter allocates and returns an RXSTRING to hold the variable value. If the Rexx interpreter allocates the RXSTRING, an RXSHV_TRUNC condition cannot occur. However, RXSHV_MEMFL errors are possible for these operations. If an RXSHV_MEMFL condition occurs, memory is not allocated for that request block. The RexxVariablePool caller must release the storage with GlobalFree(ptr).
Note: The RexxVariablePool does not add a terminating null character to the variable value.
shvvalue is not used.
The shared variable block request code. Valid request codes are:
Assign a new value to a Rexx procedure variable.
Retrieve the value of a Rexx procedure variable.
Drop (unassign) a Rexx procedure variable.
Fetch the private information of the Rexx procedure. The following information items can be retrieved by name:
The number of arguments supplied to the Rexx procedure. The number is formatted as a character string.
The nth argument string to the Rexx procedure. If the nth argument was not supplied to the procedure (either omitted or fewer than n parameters were specified), a null string is returned.
The current Rexx data queue name.
The Rexx procedure source string used for the PARSE SOURCE instruction.
The Rexx interpreter version string used for the PARSE SOURCE instruction.
Fetch the next variable, excluding variables hidden by PROCEDURE instructions. The variables are not returned in any specified order.
The Rexx interpreter maintains an internal pointer to its list of variables. The variable pointer is reset to the first Rexx variable whenever:
An external program returns control to the interpreter
A set, fetch, or drop RexxVariablePool function is used
RXSHV_NEXTV returns both the name and the value of Rexx variables until the end of the variable list is reached. If no Rexx variables are left to return, RexxVariablePool sets the RXSHV_LVAR bit in shvret.
The individual shared variable request return code. shvret is a 1-byte field of status flags for the individual shared variable request. The shvret fields for all request blocks in the list are ORed together to form the RexxVariablePool return code. The individual status conditions are:
The request was processed without error (all flag bits are FALSE).
The named variable was uninitialized at the time of the call.
No more variables are available for an RXSHV_NEXTV operation.
A variable value or variable name was truncated because the supplied RXSTRING was too small for the copied value.
The variable name specified in shvname was invalid for the requested operation.
The Rexx interpreter was unable to obtain the storage required to complete the request.
The shared variable request block contains an invalid function code.
The Rexx interpreter processes each request block in the order provided. RexxVariablePool returns to the caller after the last block is processed or a severe error occurred (such as an out-of-memory condition).
The RexxVariablePool function return code is a composite return code for the entire set of shared variable requests. The return codes for all of the individual requests are ORed together to form the composite return code. Individual shared variable request return codes are returned in the shared variable request blocks.
RexxVariablePool has processed the entire shared variable request block list.
The RexxVariablePool function return code is a composite return code for the entire set of shared variable requests. The low-order 6 bits of the shvret fields for all request blocks are ORed together to form the composite return code. Individual shared variable request status flags are returned in the shared variable request block shvret field.
The variable pool interface was not enabled when the call was issued.
/*********************************************************************/
/* */
/* SetRexxVariable - Set the value of a Rexx variable */
/* */
/*********************************************************************/
INT SetRexxVariable(
PSZ name, /* Rexx variable to set */
PSZ value) /* value to assign */
{
SHVBLOCK block; /* variable pool control block*/
block.shvcode = RXSHV_SYSET; /* do a symbolic set operation*/
block.shvret=(UCHAR)0; /* clear return code field */
block.shvnext=(PSHVBLOCK)0; /* no next block */
/* set variable name string */
MAKERXSTRING(block.shvname, name, strlen(name));
/* set value string */
MAKERXSTRING(block.shvvalue, value, strlen(value));
block.shvvaluelen=strlen(value); /* set value length */
return RexxVariablePool(&block); /* set the variable */
}