Chapter Contents

Previous

Next
The Subcommand Interface to EXECs and CLISTs

Overview of the SUBCOM Environment

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.)


SUBCOM and CMS

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.


SUBCOM and TSO

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.

Accessing REXX under TSO

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 .

Attention Handling

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.


SUBCOM and USS

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).


SUBCOM in Interactive and Noninteractive Environments

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.


Chapter Contents

Previous

Next

Top of Page

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.