Function Codes (SHVCODE)

Three function codes (D, F, and S) may be given in either lowercase or uppercase:

Lowercase: (The Symbolic interface). The names must be valid REXX symbols (in mixed case if desired), and usual REXX substitution occurs in compound variables.
Uppercase: (The Direct interface). No substitution or case translation takes place. Simple symbols must be valid REXX variable names (that is, in uppercase, and not starting with a digit or a period), but in compound symbols any characters (including lowercase, blanks, and so forth) are permitted following a valid REXX stem.

Note: The Direct interface, which is also provided (in part) by EXEC 2, should be used in preference to the Symbolic interface whenever generality is desired.

The other function codes, N and P, must always be given in uppercase. The specific actions for each function code are as follows:

D and d

Drop variable. The SHVNAMA/SHVNAML adlen describes the name of the variable to be dropped. SHVVALA/SHVVALL are not used. The name is validated to ensure that it does not contain incorrect characters, and the variable is then dropped, if it exists. If the name given is a stem, all variables starting with that stem are dropped.

F and f

Fetch variable. The SHVNAMA/SHVNAML adlen describes the name of the variable to be fetched. SHVVALA specifies the address of a buffer into which the data is to be copied, and SHVBUFL contains the length of the buffer. The name is validated to ensure that it does not contain incorrect characters, and the variable is then located and copied to the buffer. The total length of the variable is put into SHVVALL, and, if the value was truncated (because the buffer was not big enough), the SHVTRUNC bit is set. If the variable is shorter than the length of the buffer, no padding takes place. If the name is a stem, the initial value of that stem (if any) is returned.

SHVNEWV is set if the variable did not exist before the operation, and in this case the value copied to the buffer is the derived name of the variable (after substitution and so forth); see Compound Symbols.

N

Fetch Next variable. This function can search through all the variables known to the language processor (that is, all those of the current generation, excluding those hidden by PROCEDURE instructions). The order in which the variables are revealed is not specified.

The language processor maintains a pointer to its list of variables: this is reset to point to the first variable in the list whenever a host command is issued, or any function other than N or P is run through the EXECCOMM interface.

Whenever an N (Next) function is run, the name and value of the next variable available are copied to two buffers supplied by the caller.

SHVNAMA specifies the address of a buffer into which the name is to be copied, and SHVUSER contains the length of that buffer. The total length of the name is put into SHVNAML, and if the name was truncated (because the buffer was not big enough) the SHVTRUNC bit is set. If the name is shorter than the length of the buffer, no padding takes place. The value of the variable is copied to the user's buffer area using exactly the same protocol as for the Fetch operation.

If SHVRET has SHVLVAR set, the end of the list of known variables has been found, the internal pointers have been reset, and no valid data has been copied to the user buffers. If SHVTRUNC is set, either the name or the value has been truncated.

By repeatedly executing the N function (until the SHVLVAR flag is set) a user program can locate all the REXX variables of the current generation.

P

Fetch private information. This interface is identical with the F fetch interface, except that the name refers to certain fixed information items that are available. Only the first letter of each name is checked (though callers should supply the whole name), and the following names are recognized:

ARG: Fetch primary argument string. The first argument string that would be parsed by the ARG instruction is copied to the user's buffer.
PARM: Fetch the number of argument strings. The number of argument strings supplied to the program is placed in the caller's buffer. The number is formatted as a character string.
Note: When specifying PARM, each letter must be supplied.
PARM.n: Fetch the nth argument string. Argument string n is placed in the caller's buffer. Returns a null string if argument string n cannot be supplied (whether omitted, null, or fewer than n argument strings specified). Parm.1 returns the same result as ARG.
Note: When specifying PARM.n, 'PARM.' must be supplied.
SOURCE: Fetch source string. The source string, as described for PARSE SOURCE in PARSE, is copied to the user's buffer.
VERSION: Fetch version string. The version string, as described for PARSE VERSION in PARSE, is copied to the user's buffer.

S and s

Set variable. The SHVNAMA/SHVNAML adlen describes the name of the variable to be set, and SHVVALA/SHVVALL describes the value to be assigned to it. The name is validated to ensure that it does not contain incorrect characters, and the variable is then set from the value given. If the name is a stem, all variables with that stem are set, just as though this was a REXX assignment. SHVNEWV is set if the variable did not exist before the operation.

Note:

EXEC 2 supports only the S (Set) and F (Fetch) functions. Other requests are rejected.
The interface is enabled only during the execution of commands (including CMS subcommands) and external routines (functions and subroutines). An attempt to call the EXECCOMM entry point asynchronously results in a return code of -1 (Invalid entry conditions).
While the EXECCOMM request is being serviced, interrupts are enabled for most of the time.