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:

copies the value of a REXX, EXEC2, or CLIST variable to an array of char
assigns a string value to a new or existing REXX, EXEC2, or CLIST variable
undefines (drops) a CMS or USS REXX variable or stem, or causes a CLIST or TSO REXX variable to be assigned a null (length 0) value.

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

***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