Chapter Contents |
Previous |
Next |
execcall |
Portability: | SAS/C extension |
SYNOPSIS | |
DESCRIPTION | |
RETURN VALUE | |
CAUTIONS | |
IMPLEMENTATION | |
EXAMPLE |
SYNOPSIS |
#include <exec.h> int execcall(const char *cmd);
DESCRIPTION |
The
execcall
function invokes an EXEC or CLIST. The character string pointed
to by
cmd
is an EXEC command.
The exact format of the command is system-dependent.
cmd
can include a specification of the file to
execute and also operands or options.
The library assumes that both
"EXEC cmdname operands"
and
"cmdname operands"
are valid arguments to
execcall
, but the exact details
are system-dependent. (Under USS, the command string should not begin with
"EXEC"
unless the intent is to
invoke a REXX script named
EXEC
.)
RETURN VALUE |
The
execcall
function returns
0
if the call is successful or nonzero if the call is not successful.
A nonzero return code indicates that the EXEC or CLIST could not be executed.
Under TSO, the return code is that of the EXEC command
or a negative return code whose meaning is the same as that from the
system
function. However, if
execcall
is used to call a TSO
REXX EXEC that terminates without passing any subcommands to the C program,
the return code is that set by the EXEC's RETURN or EXIT statement. This
cannot always be distinguished from an EXEC command failure.
Under the USS shell, as under TSO, the return code from
execcall
may reflect either a
failure of the REXX interface (IRXJCL) or a return code set by the called
EXEC.
CAUTIONS |
The
execcall
function is valid only for programs that have defined an environment
name through
execinit
.
Once
execcall
is used successfully, future
execget
calls are expected to read from the EXEC or CLIST.
execget
returns
"*ENDEXEC
rc
"
the first time it is called after a CLIST or
EXEC invoked by
execcall
has completed, where rc is the return code from the CLIST or EXEC. Subsequent calls to
execget
result in terminal reads.
IMPLEMENTATION |
For a CMS EXEC or a TSO CLIST,
execcall
does not cause any of the statements
of the EXEC or CLIST to be executed.
execcall
finds the file to be executed and completes the parameter
list to be processed.
Under CMS, the macro to be invoked has a filename of
execname
and a filetype of
envname
, where
envname
was specified by the call to
execinit
. If the macro cannot be found, an error
code is returned. Otherwise,
execcall
saves the fileid but does not invoke the macro. The next
call to
execget
invokes
the EXEC processor with the EXEC parameter list and a FILEBLOK indicating
the filename (from
execcall
)
and filetype (from
execinit
)
of the macro. Under TSO,
execcall
uses the ATTACH macro to call the EXEC command. Any CLIST arguments
are processed at this time, and prompts are generated for any omitted arguments.
No other CLIST processing occurs until
execget
is called. For a TSO REXX EXEC,
execcall
executes the statements of the EXEC up to the first subcommand
addressed to the program's environment before control is returned to the program.
Under the USS Shell, the requested REXX EXEC is invoked
using the IRXJCL service routine. Due to limitations of this service, the
name of the EXEC is limited to eight characters. The EXEC must be an executable
file, and must reside in one of the directories defined by the
PATH
environment variable. The statements of
the EXEC up to the first subcommand addressed to the program's environment
will be processed before control is returned to the program.
EXAMPLE |
See the example for the
execget
function and the comprehensive SUBCOM
example.
Chapter Contents |
Previous |
Next |
Top of Page |
Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.