The Subcommand Interface to EXECs and CLISTs

Subcommand Processing in C Programs

Subcommand functions enable a program to identify itself to the operating system as a subcommand processor. The ability to handle subcommands provides program flexibility and extends program capabilities. The SUBCOM facility provides a program with a mechanism for taking input from CMS or TSO command languages and provides the programmer with an additional full-scale language to perform program tasks. For example, a simple subcommand application allows a CLIST or EXEC to execute a number of similar commands repeatedly. A more complicated application defines complex subcommands as sequences of simpler commands, packaged as a CLIST or EXEC.

All SUBCOM interfaces are portable between CMS, TSO, and USS, so a program written for one environment can be ported to another. Although the exact internal processing (or effect of SUBCOM functions) is system-dependent, these differences are transparent to the user, so a program's operation on different systems is still predictable. Even SUBCOM programs with substantial differences in required CMS and TSO behavior can usually be written with the system dependencies isolated to smaller parts of the program.

Steps in Subcommand Processing

Under TSO, CMS and the USS shell, programs that support a subcommand environment can be described as doing their processing in a basic loop consisting of the following steps:

Get the next subcommand (from the terminal or from an EXEC or CLIST).
Identify the subcommand name.
Process the subcommand, possibly issuing one or more messages.
Set the subcommand's return code for access by an EXEC or CLIST.
Go to step 1.

Associated with each of these steps are the following SUBCOM functions:

execget , which obtains a subcommand from an appropriate source
execid , which extracts the subcommand name and may perform additional system-dependent processing, for example, recognizing system-defined use of special characters in the subcommand
execmsg , which sends diagnostic messages, the exact form of which can be controlled by the user
execrc , which sets the return code from the completed subcommand and may perform additional system-dependent processing.

In addition, an execinit function is used to initialize the subcommand environment (and assign a name to it), and execend is used to terminate the environment.

The set of library functions that implement the SUBCOM interface can be summarized as follows: execinit establishes and assigns a name to a SUBCOM environment.

execcall invokes a new CLIST or EXEC, from which input can be read later.

execend cancels the program's SUBCOM environment.

execget gets a line of input from an EXEC/CLIST or from the terminal.

execid parses a string into a subcommand name and operands, using system-dependent conventions.

execinit establishes and assigns a name to a SUBCOM environment.

execmsg sends a message to the user, in a system-dependent way, allowing the use of system facilities for message suppression or abbreviation.

execmsi tests the environment, in a system-dependent way, to determine which portions of messages the user wants to print.

execrc sets the return code of the most recent subcommand.

execshv provides a way to fetch, set, or drop REXX, EXEC2 or CLIST variable values.

If these functions are used to create a subcommand environment, a typical SUBCOM program has the following basic form:

execinit(...);                    /* Set up environment.       */
for(;;) {
 execget(...);                    /* Get a subcommand.         */
    cmd = execid(...);            /* Identify subcommand.      */
    if (strcmp(cmd,"END")==0)
       break;
    if (strcmp(cmd,"EXEC")==0)
       execcall(...);             /* Implement exec.           */
    else
       process(...);              /* Process the subcommand.   */

    execrc(...);                  /* Set the return code.      */
}
execend();                         /* Terminate the environment.*/

Chapter Contents
Previous
Next
Top of Page

`execcall`	invokes a new CLIST or EXEC, from which input can be read later.
`execend`	cancels the program's SUBCOM environment.
`execget`	gets a line of input from an EXEC/CLIST or from the terminal.
`execid`	parses a string into a subcommand name and operands, using system-dependent conventions.
`execinit`	establishes and assigns a name to a SUBCOM environment.
`execmsg`	sends a message to the user, in a system-dependent way, allowing the use of system facilities for message suppression or abbreviation.
`execmsi`	tests the environment, in a system-dependent way, to determine which portions of messages the user wants to print.
`execrc`	sets the return code of the most recent subcommand.
`execshv`	provides a way to fetch, set, or drop REXX, EXEC2 or CLIST variable values.