Chapter Contents |
Previous |
Next |
execget |
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.
Chapter Contents |
Previous |
Next |
Top of Page |
Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.