RexxVariablePool - Parameters

RequestBlockList (PSHVBLOCK) - input

A linked list of shared variable request blocks (SHVBLOCK). Each shared variable request block in the linked list is a separate variable access request.

The SHVBLOCK has the following form: SHVBLOCKdatastructure


typedef struct shvnode {
    struct shvnode    *shvnext;
    RXSTRING           shvname;
    RXSTRING           shvvalue;
    ULONG              shvnamelen;
    ULONG              shvvaluelen;
    UCHAR              shvcode;
    UCHAR              shvret;
}   SHVBLOCK;

shvnext

The address of the next SHVBLOCK in the request list. shvnext is NULL for the last request block.
shvname
An RXSTRING containing a REXX variable name. shvname usage varies for the different SHVBLOCK request codes:

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 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 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 is 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 DosFreeMem.

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

RXSHV_EXIT
shvname is unused for the RXSHV_EXIT function.
shvvalue
An RXSTRING containing a REXX variable value. The meaning of shvvalue varies for the different SHVBLOCK request codes:

RXSHV_SET

RXSHV_SYSET

shvvalue is the value assigned to the REXX variable in shvname. shvvaluelen contains the length of the variable value.
RXSHV_EXIT
shvvalue is the value assigned to the exit handler return value. shvvaluelen contains the length of the variable value.
RXSHV_FETCH

RXSHV_SYFET

RXSHV_PRIV

RXSHV_NEXT

shvvalue is a buffer the REXX interpreter uses to return a copy of REXX variable shvname. shvvaluelen contains the length of the value buffer. On return, shvvalue.strlength is set to the length of the returned value and shvvaluelen is unchanged. If the variable value is longer than 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 is 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 DosFreeMem.

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. The 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 REXX procedure private information. The following information items can be retrieved by name:

EXITNAME

The name of the current system exit handler for this thread. If not called from within an exit handler, a null string will be returned.
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 next variable. RXSHV_NEXTV traverses the variables in the current generation of REXX variables, 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.
RXSHV_EXIT
Set a return value for an external function or system exit call. RXSHV_EXIT is valid only from external functions or system exit events that return a string value. An external function or exit handler can use RXSHV_EXIT only once.
shvret
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 after a severe error (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 request shared variable blocks.

---

[Back: RexxVariablePool - Syntax]
[Next: RexxVariablePool - Returns]