execget

execget

Return the Next Subcommand

Portability: SAS/C extension

SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTIONS
IMPLEMENTATION
EXAMPLE

SYNOPSIS

#include <exec.h>

char *execget(void);

DESCRIPTION

The execget function obtains a subcommand from a CLIST or EXEC or from the terminal if no CLIST or EXEC input is available. It returns the address of a null-terminated string containing the subcommand. The area addressed by the pointer returned from execget remains valid until the next call to execget .

If an EXEC or CLIST is active and accessible, input is obtained from that EXEC or CLIST; otherwise, the user is prompted with the name of the environment and a colon, and the next line of terminal input is returned to the program. (Before the prompt is issued, input is taken from the REXX data stack, if the stack is not empty.) If the SUBCOM interface is initialized with an interactive call to execinit , any EXECs or CLISTs active at the time are inaccessible. Additionally, under TSO, any input on the REXX data stack is inaccessible. Therefore, for such programs, a call to execget reads from the terminal unless execid or execcall has invoked a new CLIST or EXEC.

If all active EXECs or CLISTs terminate and the data stack becomes empty, execget returns a pointer to the string "*ENDEXEC rc " . The component "*ENDEXEC" is a literal character string provided as a dummy subcommand. The component "rc" is an appropriate return code. The "rc" can be omitted if no return code is defined. Subsequent calls to execget issue terminal reads, using a prompt formed from the original envname suffixed with a colon.

The "*ENDEXEC" convention was designed for the convenience of programs that want to use execget to read only from CLISTs or EXECs, while using another form of normal input (for instance, a full-screen interface). Such programs use execget only after execcall (or at start-up, if noninteractive) and switch to their alternate form of input after execget returns "*ENDEXEC" .

RETURN VALUE

The execget function returns a pointer to a buffer containing the subcommand string. If no subcommand can be returned due to an unexpected system condition, execget returns NULL .

CAUTIONS

The execget function is rejected when there is no environment name defined via execinit .

Under TSO, a CLIST can use the TERMIN statement to switch control from the CLIST to the terminal. Use of TERMIN when the SUBCOM interface is initiated with a noninteractive call causes "*ENDEXEC" to be returned, even when the CLIST has not ended.

The CMS SUBCOM interface acknowledges two logical cases of SUBCOM processing. The first case is when the program is accepting subcommands from an EXEC that is invoked external to the program. The second case occurs when the program is accepting subcommands from an EXEC invoked by execcall (see the execcall description).

If the program is accepting subcommands from an EXEC invoked externally and the EXEC terminates without sending a subcommand to execget , the string "*ENDEXEC" is placed in the subcommand buffer without a return code value because the return code belongs to the environment that invoked the EXEC (usually CMS). Subsequent calls to execget read from the terminal. If the program terminates before all the subcommands in the EXEC are processed, the remaining subcommands are issued to CMS. Under most circumstances, CMS responds with an error message and a return code of 3 . (Refer also to the note on *ENDEXEC in the section CAUTIONS under execcall .)

Note that under the USS shell, input is read from the REXX process' file descriptor 0 if no EXEC is active and there is no data present on the data stack. File descriptor 0 is normally allocated to the terminal, but could be directed elsewhere if the program's standard input had been redirected when execinit was called.

Premature termination of programs that have invoked an EXEC via execcall are handled by execend . See the section CAUTIONS following the execend description.

IMPLEMENTATION

For CMS, refer to the IMPLEMENTATION discussion in the execcall description.

Under TSO, execget issues the PUTGET MODE macro to get a line of input if the current input source is a CLIST or the terminal. If the current input source is a REXX EXEC, the next input line is obtained from the host-command environment routine. In interactive mode, "*EXECEND" is returned when the current allocation of the TSO stack becomes empty. In noninteractive mode, "*EXECEND" is returned when control passes from a CLIST to the terminal, or on the first call if no CLIST is active when program execution begins.

Under USS, if no EXEC is active when execget is called, execget reads a line from the REXX process' file descriptor 0 using the IRXSTK service routine's PULLEXTR function.

EXAMPLE

This example obtains a subcommand from a CLIST or EXEC. If no command is available, SUBCOM processing is terminated. Otherwise, the command is assumed to be an EXEC command and is executed using execcall .

#include <exec.h>
#include <string.h>

int rc;
char *cmd;

cmd = execget();

if (cmd != 0 && memcmp(cmd,"*ENDEXEC",8))
   execend();
else {
   rc = execcall(cmd);
   execrc(rc);
}

Note: Also see the comprehensive SUBCOM example. [cautionend]

Chapter Contents
Previous
Next
Top of Page