Chapter Contents |
Previous |
Next |
execshv |
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:
char
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
SHV_FETCH
vb
.
The variable name is translated to uppercase before being used.
SHV_FIRST
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
execshv
with
SHV_FIRST
or any other value for
code
.
SHV_SET
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 .
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
SHV_NO_MEM
SHV_LIBERR
execshv
internal library error.
SHV_INVALID_VAR
SHV_INVALID_FUNC
SHV_SET
,
SHV_FETCH
,
SHV_DROP
,
SHV_FIRST
,
or
SHV_NEXT
.
SHV_NOT_SUPPORTED
SHV_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
SHV_NOT_FOUND
SHV_LAST_VAR
SHV_NEXT
loop have been fetched,
as in an end-of-file return. The returned variable name and value are unpredictable.
SHV_TRUNC_VAL
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
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.