| The Subcommand Interface to EXECs and CLISTs |
As noted in the Introduction, a program using the
SUBCOM interface can
be completely portable between CMS, TSO and USS environments. Topics of general
interest concerning these implementations are discussed in this section. Using
SUBCOM in an interactive and noninteractive environment also is discussed.
(Topics specific to the implementation of each SAS/C function are presented
later in each detailed function description.)
Under CMS, you traditionally establish a subcommand
environment
by invoking the CMS SUBCOM service. You then write an assembler routine to
provide the appropriate function parameters and calling sequence. The SAS/C
compiler simplifies this process by providing a set of functions that enable
a program to become a subcommand processor. More detailed coverage of all
aspects of the CMS SUBCOM service can be found in the appropriate IBM documentation
for your system.
To use the SUBCOM facility under CMS, a program must
tell CMS its name and the address to which CMS should pass the commands. The
next step is to give the program the commands. Under CMS the user typically
uses an EXEC to pass the commands. Because commands in an EXEC are sent by
default to CMS, however, an alternate destination can be specified via the
address statement (in REXX) or the & SUBCOMMAND statement (in EXEC2).
After the program has handled the command, it returns to CMS so that CMS can
get another command for the program to handle. Therefore, subcommand processors
are being invoked continually and returning to CMS until they are told to
stop or are interrupted.
CMS also has a facility for letting the user program
call the EXEC processor directly. In this case, the EXEC processor sends commands
by default to the program instead of CMS. To invoke an EXEC for itself, the
program again must first declare itself via SUBCOM so that it can get commands.
In this case, it then calls CMS to tell it the name of a file that the EXEC
processor will execute. The EXEC processor executes the file and sends the
commands to the program.
To facilitate this processing, the SUBCOM interface
uses the CMS SUBCOM facility that enables a subcommand entry point. To invoke
an EXEC, the interface calls the EXEC processor with the filename and filetype
of the EXEC to be executed.
Under TSO, CLISTs are executed through a two-stage process.
First,
the EXEC command is called to read and compile the CLIST. The resulting data
are accessible through a control block called the TSO stack.
Later, when a program, or TSO itself, needs to obtain input and is willing
to accept CLIST input, it calls the PUTGET service routine. If a CLIST is
present on the stack, TSO passes control to the CLIST. The CLIST executes
until it generates a subcommand line. At this point, TSO returns control to
PUTGET, which passes the subcommand line back to its caller.
The SUBCOM implementation for TSO is closely tied to
traditional CLIST processing. The
execget
function reads the CLIST input by calling the PUTGET
routine. The
execcall
function, which invokes a new CLIST, does so by calling the
EXEC command.
The SAS/C Library SUBCOM features supports
TSO REXX in addition to the CLIST language. The REXX support does not require
that existing CLIST applications be modified. A single application can generally
be used to communicate with both CLISTs and REXX EXECs without concern for
which command language is used. There are a few cases where a program's behavior
processing a REXX EXEC may differ from the behavior processing a similar CLIST,
as described in the function descriptions.
When using the SUBCOM interface to communicate with
a REXX EXEC in TSO, the EXEC must specifically address (via the ADDRESS command)
the SAS/C application's environment to send it subcommands. The default environment
for EXECs invoked from SAS/C is still TSO. The name to be addressed is the
value of the first argument to
execinit
. Refer to SUBCOM and USS for additional information.
Note that a REXX EXEC that
addresses a SUBCOM application
cannot be called using the
system
function. If this is attempted, any subcommand addressed to the SUBCOM
application will fail with a return code of
-10
.
The TSO SUBCOM implementation for calling a REXX EXEC
is somewhat different from the CLIST implementation. In this case,
execinit
defines a host-command
environment routine to process subcommands addressed to the application.
When
execget
is called,
control is transferred from the SUBCOM application to REXX. When the REXX
EXEC generates a subcommand for the application, REXX calls the Host Command
Environment routine, which passes the subcommand back to
execget
.
If a SUBCOM application has a SIGINT signal handler
or uses the debugger, an attention while a REXX EXEC is running is specially
handled. The user is prompted to enter either IC or a regular REXX immediate
command. If IC is entered, an attention is presented to the debugger or the
SIGINT handler as if REXX were not active. Otherwise, the REXX immediate
command is passed to REXX. This allows attention handling to be shared between
REXX (which ordinarily will not let an application handle attentions itself)
and the SAS/C application.
Under the USS shell, REXX EXECs are stored as executable
files in the hierarchical file system, and can be invoked by any of the
exec
family of functions. However,
when a REXX EXEC is invoked in this fashion, it runs in a separate address
space from its caller, and only the standard REXX environments (such as the
OS/390 and SYSCALL environments) are available.
The SAS/C SUBCOM implementation for USS uses the
oeattach
function to invoke REXX
in the same address space as its caller. This allows the library to establish
the additional SUBCOM environment used for communication with the calling
program. The IBM support routine BPXWRBLD is used to establish a REXX environment
that is USS aware, so that REXX input and output will be directed to the hierarchical
file system rather than to DDnames.
The SAS/C REXX interface under the shell runs as a separate
process from the calling program to prevent interference between the program
and EXEC processing. When the REXX interface is created by a call to
execinit
, the program's environment
variables and file descriptors are copied to the REXX interface process.
This copy of the environment is not affected by any changes requested by the
program, including the use of
setenv
or
close
.
REXX input and output are always directed to the REXX process' file descriptors
0 and 1, even if these descriptors have been reopened by the program after
the call to
execinit
.
Note that a REXX script invoked by the
system
function under USS cannot address the
invoker's SUBCOM environment. Any attempt to do so will fail with return
code
-3
(command not found).
A program operating in a subcommand environment can execute in
either an interactive or noninteractive manner. Either type of execution can
be used by programs that accept input from CLISTs or EXECs, subject to operating
system restrictions.
A program with interactive style gets subcommands from
the terminal. This style program, even if it is invoked from an EXEC or CLIST,
begins by reading from the terminal and accepts EXEC or CLIST input only as
the result of terminal input (such as an EXEC command from the user). Commands
in an EXEC or CLIST following a call to an interactive program can be executed
only after that program terminates.
A program with noninteractive style receives subcommands
from an EXEC or CLIST. If this style program is invoked from an EXEC or CLIST,
it gets its input from that EXEC or CLIST and takes input from the terminal
only as a result of commands from the EXEC or CLIST or after that EXEC or
CLIST has terminated.
For example, an EXEC or CLIST could contain the following
commands:
CPGM1 (options)
SUBCMD2 (options)
If the program CPGM1 is interactive, the SUBCMD2 input
line is not read by CPGM1 or processed at all until CPGM1 terminates. If CPGM1
is noninteractive, however, the SUBCMD2 line is read by CPGM1 the first time
it calls
execget
to get
a line of input.
Under CMS, most processors are defined as interactive.
In versions of CMS after VM/SP 5, we do not recommend noninteractive programs.
Under TSO, most processors are defined as noninteractive.
An interactive program must create a new version of the TSO stack to avoid
reading input from the CLIST that invoked it.
Under the USS shell, only the interactive mode of SUBCOM
is supported.
Copyright © 2001
by SAS Institute Inc., Cary, NC, USA. All rights reserved.
