execinit

execinit

Create a SUBCOM Environment

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.

Note that TSO REXX does not allow a program invoked from an EXEC to read input from the same EXEC. For TSO REXX applications, the only distinction between interactive and noninteractive mode is that, in interactive mode a new REXX data stack is created, while in noninteractive mode the previous data stack is shared with the application.

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");

Chapter Contents
Previous
Next
Top of Page