Chapter Contents

Previous

Next
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:

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

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


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

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.