Chapter Contents |
Previous |
Next |
execinit |
Portability: | SAS/C extension |
SYNOPSIS | |
DESCRIPTION | |
RETURN VALUE | |
CAUTIONS | |
IMPLEMENTATION | |
EXAMPLE |
SYNOPSIS |
#include <exec.h> int execinit(const char *envname, int interactive);
DESCRIPTION |
The
execinit
function establishes a SUBCOM environment with the name specified
by
envname
. The characteristics
of
envname
are system-dependent.
Under TSO, the value of
envname
is available through the standard CLIST variable & SYSPCMD or
the REXX call SYSVAR(SYSPCMD). Under CMS, the value of
envname
is the environment addressed by an EXEC
to send subcommands. Also under CMS, for EXECs invoked via
execcall
, the environment is used as the filetype
of the EXEC.
The
interactive
argument is a true-or-false value (where
0
is false and nonzero is true) indicating whether the program should
run as an interactive or noninteractive SUBCOM processor. Because the
interactive
argument to
execinit
can be a variable, it
is possible for a program to choose its mode according to a command-line option,
allowing complete flexibility. An interactive processor is one that normally
accepts input from the terminal, even if the program is invoked from an EXEC
or CLIST. A noninteractive processor is one that is normally called from
an EXEC or CLIST and that takes input from the EXEC or CLIST that calls it.
Using this terminology, most CMS processors, such as XEDIT, are interactive,
while most TSO processors, such as TEST, are noninteractive.
Similarly, noninteractive mode is not supported under the USS shell.
RETURN VALUE |
The
execinit
function returns
0
if the call is successful or nonzero if the call is not successful.
Reasons for failure are system-dependent. Possible errors include a missing
or invalid
envname
or,
under CMS, a nonzero return code from the CMS SUBCOM service.
CAUTIONS |
A program cannot call
execinit
more than once without an intervening
call to
execend
. Under
CMS, a program that calls
execinit
must have been called directly from CMS. Calls from other languages,
including assembler front ends, are not supported.
Noninteractive SUBCOM processing is not supported under bimodal CMS or USS.
Under TSO, when a program calls
execinit
with
interactive
set to true (nonzero), it is not possible for CLISTs invoked
by that program to share GLOBAL variables with the CLIST that called the program.
If the value of
interactive
is true (nonzero) and the SAS/C program is invoked from an EXEC or CLIST,
the remaining statements of the EXEC or CLIST are inaccessible via
execget
. If
execget
is called before the use of
execcall
, or after any EXECs or CLISTs called by
execcall
have terminated, the program gets input
from the terminal. If the value of
interactive
is false (
0
) and the SAS/C program is invoked from a CMS EXEC or TSO CLIST, then
calls to
execget
without
the use of
execcall
read
from that EXEC or CLIST.
Under TSO, if the value of
interactive
is true, a new allocation of the REXX data stack is created,
and the previous data stack contents are inaccessible until
execend
is called.
IMPLEMENTATION |
Under CMS,
execinit
invokes the CMS SUBCOM service. The name of the environment
is
envname
, truncated to
eight characters if necessary and translated to uppercase.
Under CMS, the
execinit
function creates a nucleus extension called L$CEXEC with the
ENDCMD attribute. This is done so that premature EXEC termination can be
detected (see the
execget
function description). If the CMS command NUCXDROP L$CEXEC is issued to delete
this nucleus extension, the program continues to execute, but premature termination
is not detected. If this happens, the program remains active, but control
cannot be transferred from CMS back to the program. Therefore, it is not
recommended that you use NUCXDROP L$CEXEC. For more information, see "Guidelines
for Subcommand Processing" at the end of this chapter.
Under TSO, the value of
envname
is stored in the ECTPCMD field of the Environment Control Table
(ECT). When the value of
interactive
is true, a new allocation of the TSO stack is created, if necessary,
to preserve the status of a previously executing CLIST.
Under the USS shell,
execinit
creates a new process using the
oeattach
function. This process invokes the BPXWRBLD service to create
an USS REXX language environment.
EXAMPLE |
#include <exec.h> #include <stdio.h> int rc; . . . if (rc = execinit("EXENV",0)) printf("Failed to establish SUBCOM envr\n");
Note:
See also the comprehensive SUBCOM example.
Chapter Contents |
Previous |
Next |
Top of Page |
Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.