execcall

execcall

Identify a Macro to Be Executed

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.

Note that if errors are detected by the EXEC command, the TSO stack is flushed, and a diagnostic message is printed by EXEC.

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