Chapter Contents

Previous

Next
execshv

execshv



Fetch, Set, or Drop REXX, EXEC2, or CLIST Variable Values

Portability: SAS/C extension


SYNOPSIS
DESCRIPTION
RETURN VALUE
IMPLEMENTATION
USAGE NOTES
EXAMPLE


SYNOPSIS

#include <exec.h>

int execshv(int code, char *vn, int vnl, char *vb,
            int vbl, int *vl);


DESCRIPTION

Under TSO or CMS, the execshv function can be called in any situation where an EXEC or CLIST is active. Under USS, execshv can be used only when an EXEC invoked by execcall is active.

execshv performs the following tasks:

The value of code determines what action execshv performs and how the remaining parameters are used. <exec.h> defines the following values that can be used as the value of code :

SHV_DROP
drops the named REXX or CLIST variable if it exists. The name is translated to uppercase before being used. For TSO CLIST or REXX variables, the variable name cannot truly be dropped; instead, it is set to a zero-length string.

SHV_FETCH
fetches the value of a REXX, EXEC2, or CLIST variable to a buffer, vb . The variable name is translated to uppercase before being used.

SHV_FIRST
initializes the SHV_NEXT fetch next sequence and retrieves the first in the list of all names and values of all REXX or CLIST variables as known to the REXX or CLIST interpreter. The particular variable fetched is unpredictable.

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

SHV_SET
sets a REXX, EXEC2, or CLIST variable to a value. The case of the variable name, vn , is ignored (no distinction is made between uppercase and lowercase characters).

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

execshv Argument Values
code vn vnl vb vbl vl
SHV_SET 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 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_FIRST

SHV_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 addresses the name of the variable length of the name. If 0, the name is assumed to be null-terminated. ignored ignored ignored


RETURN VALUE

The execshv function returns a negative value if the operation cannot be performed and a nonnegative value if it is performed. <exec.h> defines the negative values from execshv as follows:

SHV_NO_SUBCOM
specifies that under CMS, neither REXX, EXEC2, nor any subcommand environment is active. Under TSO, no CLIST or REXX EXEC is active. Under USS, no SUBCOM environment is active or no REXX exec is active.

SHV_NO_MEM
specifies that there is not enough memory available to complete the operation.

SHV_LIBERR
specifies an execshv internal library error.

SHV_INVALID_VAR
specifies that the variable name or value is invalid. The name does not adhere to environmental restrictions (for example, the name contains invalid characters, the length is less than 0, the length is greater than 250 for REXX or 252 for TSO CLIST, and so on) or the value is invalid (for example, longer than 32K bytes in a TSO CLIST environment).

SHV_INVALID_FUNC
specifies that the function code is not one of SHV_SET , SHV_FETCH , SHV_DROP , SHV_FIRST , or SHV_NEXT .

SHV_NOT_SUPPORTED
specifies that the current environment does not support or have the TSO CLIST variable interface module IKJCT441. This module is supplied with TSO/E Version 1 Release 2.1 or higher systems.

SHV_SIGNAL
specifies that the REXX interface process was terminated by an USS signal.

Nonnegative return values from execshv are any one or more of the following. When one or more of these conditions are true, a logical OR is performed to indicate that the condition occurred.

SHV_SUCCESS
specifies that the operation completed successfully.

SHV_NOT_FOUND
specifies that the variable name was not found.

SHV_LAST_VAR
is returned after all variables from a SHV_NEXT loop have been fetched, as in an end-of-file return. The returned variable name and value are unpredictable.

SHV_TRUNC_VAL
specifies that for SHV_FETCH , SHV_FIRST , or SHV_NEXT , the buffer addressed by vb is 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 .

SHV_TRUNC_VAR
specifies that for SHV_FIRST or SHV_NEXT , this value may be returned if the buffer addressed by vn is too short to contain the entire variable name.


IMPLEMENTATION

Under CMS, execshv uses the direct interface to REXX and EXEC2 variables provided by EXECCOMM. Under TSO, execshv uses the IKJCT441 interface to CLIST and REXX variables. Under USS, execshv uses the IRXEXCOM service.


USAGE NOTES

The <exec.h> function also defines five macros for use with execshv : shvset , shvfetch , shvdrop , shvfirst , and shvnext . These macros SET, FETCH, DROP, FETCH FIRST in SEQUENCE, and FETCH NEXT in SEQUENCE, respectively, by expanding to the full form of the execshv function call to process REXX/EXEC2 or CLIST variables. Using these macros can, in some situations, simplify the use of execshv considerably. The definition of each macro is shown here, followed by an example of its use:

   /* shvset macro */
#define shvset(vn, vb) execshv(SHV_SET, vn, 0, vb, 0, 0)

rc = shvset("XXXVAR","THIS_VALUE");

   /* shvfetch macro */
#define shvfetch(vn, vb, vbl)
    execshv(SHV_FETCH, vn, 0, vb, vbl, 0)

char valbuf[50];
rc=shvfetch("RVAR",valbuf,sizeof(valbuf));

   /* shvdrop macro */
#define shvdrop(vn) execshv(SHV_DROP, vn, 0, NULL, 0, 0)

rc = shvdrop("XXXVAR");

   /* shvfirst macro */
#define shvfirst(vn, vnl, vb, vbl)
    execshv(SHV_FIRST, vn, vnl, vb, vbl, 0)

   /*shvnest macro */
#define shvnext(vn, vnl, vb, vbl)
    execshv(SHV_NEXT, vn, vnl, vb, vbl, 0)

char vname[50], valbuf[255];
rc = shvfirst(vname,vnl,valbuf,sizeof(valbuf));
rc = shvnext (vname,vnl,valbuf,sizeof(valbuf));


EXAMPLE

The following program, named shutstc.c , demonstrates how to list all current REXX, EXEC2 or CLIST variables accessible to a program.

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

main()
{
   int rc;
   int len;
   char namebuf[20];
   char valbuf[200];
   rc = execshv(SHV_FIRST,namebuf,20,valbuf,200,&len);

   while (rc >= 0 && !(rc & SHV_LAST_VAR)) {
      if (rc & SHV_TRUNC_VAR) {
         puts("Variable name truncated.");
      }
      if (rc & SHV_TRUNC_VAL) {
         puts("Variable 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 = execshv(SHV_NEXT,namebuf,20,valbuf,200,&len);
   }
}

The following EXEC, which should be named shutst.exec , will declare several variables. The shutstc.c can be called to print these variables to the terminal.

Arnie = "cute"
Becca = "beautiful"
      .
      .
      .
'shutstc'
exit(0)


Chapter Contents

Previous

Next

Top of Page

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