Variable Pool Interface

Application programs can use the Rexx Variable Pool Interface to manipulate the variables of a currently active Rexx procedure.

Interface Types

Three of the Variable Pool Interface functions (set, fetch, and drop) have dual interfaces.

Symbolic Interface

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.

Direct Interface

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.

RexxVariablePool Restrictions

The RexxVariablePool interface is only available from subcommand handlers, external functions, and exit handlers. The interface will access the variable context that initiated the call to the handler code and is only available if made from the same thread.

RexxVariablePool Interface Function

Rexx procedure variables are accessed using the RexxVariablePool function.

RexxVariablePool

RexxVariablePool accesses variables of a currently active Rexx procedure.

retc = RexxVariablePool(RequestBlockList);

Parameters

RequestBlockList (PSHVBLOCK) - input

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;
    CONSTRXSTRING      shvname;
    RXSTRING           shvvalue;
    size_t             shvnamelen;
    size_t             shvvaluelen;
    unsigned char      shvcode;
    unsigned char      shvret;
}   SHVBLOCK;

where:

shvnext

is the address of the next SHVBLOCK in the request list. shvnext is null for the last request block.

shvname

is an RXSTRING containing a Rexx variable name. shvname usage varies with the SHVBLOCK request code:

RXSHV_SET, RXSHV_SYSET, RXSHV_FETCH, RXSHV_SYFET, RXSHV_DROPV, RXSHV_SYDRO, RXSHV_PRIV

shvname is an RXSTRING pointing to the name of the Rexx variable that the shared variable request block accesses.

RXSHV_NEXTV

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 RexxFreeMemory(ptr).

Note: The RexxVariablePool does not add a terminating null character to the variable name.

shvvalue

An RXSTRING containing a Rexx variable value. The meaning of shvvalue varies with the SHVBLOCK request code:

RXSHV_SET , RXSHV_SYSET

shvvalue is the value assigned to the Rexx variable in shvname. shvvaluelen contains the length of the variable value.

RXSHV_FETCH, RXSHV_SYFET , RXSHV_PRIV , RXSHV_NEXT

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 RexxFreeMemory(ptr).

Note: The RexxVariablePool does not add a terminating null character to the variable value.

RXSHV_DROPV , RXSHV_SYDRO

shvvalue is not used.

shvcode

The shared variable block request code. Valid request codes are:

RXSHV_SET, RXSHV_SYSET

Assign a new value to a Rexx procedure variable.

RXSHV_FETCH, RXSHV_SYFET

Retrieve the value of a Rexx procedure variable.

RXSHV_DROPV, RXSHV_SYDRO

Drop (unassign) a Rexx procedure variable.

RXSHV_PRIV

Fetch the private information of the Rexx procedure. The following information items can be retrieved by name:

PARM

The number of arguments supplied to the Rexx procedure. The number is formatted as a character string.

PARM.n

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.

QUENAME

The current Rexx data queue name.

SOURCE

The Rexx procedure source string used for the PARSE SOURCE instruction.

VERSION

The Rexx interpreter version string used for the PARSE SOURCE instruction.

RXSHV_NEXTV

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.

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:

RXSHV_OK

The request was processed without error (all flag bits are FALSE).

RXSHV_NEWV

The named variable was uninitialized at the time of the call.

RXSHV_LVAR

No more variables are available for an RXSHV_NEXTV operation.

RXSHV_TRUNC

A variable value or variable name was truncated because the supplied RXSTRING was too small for the copied value.

RXSHV_BADN

The variable name specified in shvname was invalid for the requested operation.

RXSHV_MEMFL

The Rexx interpreter was unable to obtain the storage required to complete the request.

RXSHV_BADF

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 Return Codes

0 to 127

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.

RXSHV_NOAVL

The variable pool interface was not enabled when the call was issued.

Example

/*********************************************************************/
/*                                                                   */
/* SetRexxVariable - Set the value of a Rexx variable                */
/*                                                                   */
/*********************************************************************/

int SetRexxVariable(
  const char *name,                    /* Rexx variable to set       */
  char       *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           */
}