cmsshv

cmsshv

Fetch, Set, or Drop REXX or EXEC2 Variable Values

Portability: SAS/C extension

SYNOPSIS
DESCRIPTION
RETURN VALUE
IMPLEMENTATION
USAGE NOTES
EXAMPLE

SYNOPSIS

#include <cmsexec.h>
int cmsshv(int code, char *vn, int vnl, char *vb,
           int vbl, int *vl);

DESCRIPTION

cmsshv can be called in any situation where REXX or EXEC2 is used, as well as in conjunction with function packages. cmsshv performs the following tasks:

copies the value of a REXX or EXEC2 variable to an array of char
assigns a string value to a new or existing REXX or EXEC2 variable
undefines (drops) a REXX variable or stem.

The value of code determines what action is performed by cmsshv and how the remaining parameters are used. <cmsexec.h> defines the following values that may be used as the value of code :

SHV_SET_DIRECT

sets a REXX or EXEC2 variable name to a value. The variable name, vn , must be uppercase. If the name is a REXX stem, the characters following the period can be in mixed case.

SHV_SET_SYM

sets a REXX variable name to a value. The name can be in mixed case. EXEC2 does not support this value for code .

SHV_FETCH_DIRECT

fetches the value of a REXX or EXEC2 variable to a buffer, vb . The variable name must be uppercase. If the name is a REXX stem, the characters following the period can be in mixed case.

SHV_FETCH_SYM

fetches the value of a REXX variable to a buffer. The name can be in mixed case. EXEC2 does not support this value for code .

SHV_FETCH_PRIV

fetches REXX private information to a buffer. The variables recognized are

ARG , which fetches the argument string that is parsed by the REXX statement PARSE ARG
SOURCE , which fetches the source string that is parsed by the REXX statement PARSE SOURCE
VERSION , which fetches the version string that is parsed by the REXX statement PARSE VERSION.

SHV_FETCH_NEXT

fetches the names and values of all REXX variables as known to the REXX interpreter. The order in which the variable names and values are fetched is unpredictable. The fetch loop can be reset to start again by calling cmsshv with any other value for code .

SHV_DROP_DIRECT

drops the named REXX variable, if it exists. The name must be in uppercase or, if it is a stem, all characters preceding the period must be in uppercase. If the name is a stem, then all variables beginning with that stem are dropped.

SHV_DROP_SYM: behaves the same as SHV_DROP_DIRECT except that the name can be in mixed case.

The values of the remaining arguments vn , vnl , vb , vbl , and vl are controlled by code . The values of these arguments are summarized in the following table.

cmsshv Argument Values
code vn vnl vb vbl vl

SHV_SET_DIRECT
SHV_SET_SYM
addresses the name of the variable Length of the variable name; if 0, then the name is assumed to be null-terminated addresses a buffer containing the value to be assigned Length of the value; if 0, then the value is assumed to be null-terminated ignored

SHV_FETCH_DIRECT
SHV_FETCH_SYM
SHV_FETCH_PRIV
addresses the name of the variable Length of the variable name; if 0, then the name is assumed to be null-terminated addresses a buffer to which the value of the variable is copied Length of the buffer addresses an int where the actual length of the value will be stored. If NULL , then the value will be null-terminated

SHV_FETCH_NEXT addresses a buffer where the name is copied. The name returned is null-terminated Length of the variable name buffer addresses a buffer to which the value of the variable is copied Length of the buffer addresses an int where the actual length of the value will be stored. If NULL , then the value will be null-terminated

SHV_DROP_DIRECT
SHV_DROP_SYM
addresses the name of the variable Length of the variable name; if 0, then the name is assumed to be null-terminated ignored ignored ignored

***cmsshv Argument Values***
`code`	`vn`	`vnl`	`vb`	`vbl`	`vl`
SHV_SET_DIRECT SHV_SET_SYM	addresses the name of the variable	Length of the variable name; if 0, then the name is assumed to be null-terminated	addresses a buffer containing the value to be assigned	Length of the value; if 0, then the value is assumed to be null-terminated	ignored
SHV_FETCH_DIRECT SHV_FETCH_SYM SHV_FETCH_PRIV	addresses the name of the variable	Length of the variable name; if 0, then the name is assumed to be null-terminated	addresses a buffer to which the value of the variable is copied	Length of the buffer	addresses an `int` where the actual length of the value will be stored. If `NULL` , then the value will be null-terminated
SHV_FETCH_NEXT	addresses a buffer where the name is copied. The name returned is null-terminated	Length of the variable name buffer	addresses a buffer to which the value of the variable is copied	Length of the buffer	addresses an `int` where the actual length of the value will be stored. If `NULL` , then the value will be null-terminated
SHV_DROP_DIRECT SHV_DROP_SYM	addresses the name of the variable	Length of the variable name; if 0, then the name is assumed to be null-terminated	ignored	ignored	ignored

RETURN VALUE

cmsshv returns a negative value if the operation could not be performed and a nonnegative value if it was performed. <cmsexec.h> defines the negative return values from cmsshv as follows:

SHVNOEXECCOMM: neither EXEC2 nor REXX is active.
SHVNOMEM: there is not enough memory available to complete the operation.
SHVLIBERR: cmsshv failed to create a correct EXECCOMM parameter list.

Nonnegative return values from cmsshv are any one or more of the following. When one or more of these conditions are true, they are logically OR'd to indicate that the condition occurred.

SHVSUCCESS: the operation completed successfully.
SHVNEWV: the variable name did not exist.
SHVLVAR: for SHV_FETCH_NEXT only, this is the last variable to be transferred.
SHVTRUNC: for SHV_FETCH_DIRECT and SHV_FETCH_SYM, the buffer addressed by vb was too short to contain the entire value of the variable. If vl addresses an int , the actual length of the value is stored in *vl . For SHV_FETCH_NEXT, this value can be returned if the buffer addressed by vn is too short to contain the entire name.
SHVBADN: the name of the variable is invalid.
SHVBADV: the value of the variable is too long. This value can be returned only when the value of code is SHV_FETCH_DIRECT and EXEC2 is active.
SHVBADF: the value of code is not one of the values defined in <cmsexec.h> .

IMPLEMENTATION

cmsshv uses the direct interface to REXX and EXEC2 variables (known as EXECCOMM) as documented in VM/SP System Product Interpreter Reference, IBM publication No. SC24-5239. Refer to this publication for a detailed explanation about this interface.

USAGE NOTES

<cmsexec.h> also defines three macros for use with cmsshv . The macros execset , execfetch , and execdrop assign, retrieve, and drop REXX variables, respectively. Using these macros can, in some situations, simplify the use of cmsshv considerably. Each macro is shown here, followed by an example.

   /* macro */
execset(char *vn, char *vb);
rc = execset("REXXVAR","THIS_VALUE");
   /* macro */
execfetch(char *vn, char *vb, int vbl);
char valbuf[50];
rc=execfetch("RVAR",valbuf,sizeof(valbuf));
   /* macro */
execdrop(char *vn);
rc = execdrop("REXXVAR");

EXAMPLE

#include <cmsexec.h>
#include <lcio.h>
#include <stdio.h>

main()
{
   int rc;
   int len;
   char namebuf[20];
   char valbuf[200];
   rc = cmsshv(SHV_FETCH_NEXT,namebuf,20,valbuf,200,& len);
   while (rc >= &&  !(rc & SHVLVAR)) {
      if (rc SHVTRUNC) {
         puts("Either name or value truncated.");
         printf("Actual value length is %d\n",len);
      }
      printf("The variable name is: %s\n",namebuf);
      printf("The variable value is: %.*s\n",len,valbuf);
      rc=cmsshv(SHV_FETCH_NEXT,namebuf,20,valbuf,200,& len);
   }
}

Chapter Contents
Previous
Next
Top of Page