EXEC - execute program

SYNOPSIS

<EXEC [flags] program [arg ...]>
  ... input to program ...
</EXEC>

DESCRIPTION
The EXEC command executes the given program, with arguments. Under Unix, each value of each given argument becomes a separate command-line argument to the program. Under NT, a command line is built from the arguments, space-separated, and it is up to the program to parse it into individual arguments.

The output of the statements inside the EXEC element will be piped to the standard input of the program. Its standard output will become the value of $ret, each line being a separate value. In version 5 and later, $ret.stderr will contain the standard error from the program (unless redirected by options), $ret.err will contain a list of putmsgs created by the execution, and $ret.exitcode will contain the exit code of the program (or the terminating signal as a negative number, if Unix).

The following flags may be given before the program argument:

• NOBR
  Don't split the returned output into lines; leave intact as one value.

• BIN
  The returned $ret value is considered binary (eg. varbyte). This is useful for image processing, where the output of the program might be a binary image. BIN implies the NOBR flag.

• BKGND
  Background the program: don't wait for it to finish executing once </EXEC> is reached. The program's input is still taken from the <EXEC> block, but its output will be ignored and $ret will be the process id of the background program instead. This is useful for starting programs that can't be waited for, or don't need to be, such as sending a mail message.

• TOFILE=$file
  Send the output of the program to the file named by $file, instead of collecting in $ret (foreground) or discarding (BKGND). If $file is ``-'' (single dash), the program's output will go to the Vortex script's standard output (aka stdout). If $file is empty, the program's output will be discarded (ie. /dev/null or NUL redirect). Added in version 4.0.1004580000 20011031. See caveat below.

• DOMAIN=$domain
  Sets the domain for USER. Added in version 5. Only supported under Windows. The default if unspecified or empty is taken from USER if present, otherwise ``.'' (local machine) is used. Ignored if USER is unset or empty.

• USER=$user
  Specifies the user to login and run the program as. The default if unspecified or empty is the current user (no login). Added in version 5. Only supported under Windows. If DOMAIN is unspecified or empty, a domain may also be given in the value, eg. Domain\User or User@Domain. PASS should also be set if USER is set.

  The $user specified must have Log on as a batch job permission, and the source user (the user calling Vortex <EXEC>, typically I_USR if from web server) must have Act as part of the operating system, Increase quotas, and Replace a process level token permissions set. These are requirements of the Windows operating system. Note: before changing these permissions, discuss the security implications with your Windows administrator. Lack of the first permission may result in Win32 error 1385 (``Logon failure: the user has not been granted the requested logon type at this computer''), whereas lack of the other permissions may result in Win32 error 1314 (``A required privilege is not held by the client'').

  If these permissions cannot be set, the FASTLOGON flag may be given, which avoids the need for the permissions, but adds other caveats (see below).

• PASS=$pass
  Sets the password to use for logging in the USER. Added in version 5. Only supported under Windows.

• FASTLOGON
  If this flag is set, a faster logon method that avoids the Windows LogonUser() call is used when executing programs as another user (ie. USER set). Setting this flag avoids the need to set Logon Batch Windows perms for USER, and Run as System and Replace OS Token for the Vortex user. However, the <EXEC> process will pop up a new DOS window, its output (stdout) may not be available, and the parent process of the Vortex script (eg. the web server) may wait for the grandchild <EXEC> process indefinitely. Added in version 5. Only supported under certain (recent) Windows versions.

• FROMFILE=$file
  Sets the file to read input from. If empty, input is redirected from /dev/null or NUL. If ``-'' (a single dash), input comes from the Vortex script's standard input (aka stdin). Otherwise input comes from the file specified. If FROMFILE is not specified at all, input comes from the output of the enclosed Vortex statements. Added in version 5.

• STDERRTOFILE=$file
  Sets the file to redirect standard error (aka stderr) to. If empty, standard error is redirected to /dev/null or NUL. If ``-'' (a single dash), standard error is redirected to the Vortex script's standard error. Otherwise standard error goes to the specified file. If STDERRTOFILE is not specified, standard error is returned in the Vortex variable $ret.stderr for foreground programs, otherwise (BKGND) it goes to /dev/null or NUL. Added in version 5; in previous versions standard error went to the Vortex script's standard error (Unix) or the same place as standard output (Windows).

• TIMEOUT=$n
  Sets a timeout for the program: if execution exceeds $n seconds, the program is terminated. -1 specifies no timeout, which is the default if unspecified or empty. Added in version 5.

• CHDIR=$dir
  Sets the working directory for the program to $dir (without affecting the Vortex current working directory). The default is the same as the Vortex current working directory. Added in version 5. More efficient and modular that using <syscp chdir>.

• ENVSET
    Flag that indicates the ``option assignments'' that follow are actually environment variable assignments to be added for the program, without altering the current Vortex environment. Eg. ENVSET LD_LIBRARY_PATH=/usr/local/bin would add the LD_LIBRARY_PATH environment variable set to /usr/local/bin for the program. Environment variable assignments are taken until the next non-assignment option. Both names and values may be Vortex variables; multi-value names are assigned in parallel with values, with the shorter list's last value extended to match. An unset Vortex variable used for a value causes the named environment variable(s) to be deleted instead. More efficient and modular than using <syscp setenv>. Added in version 5.

• ENVCLR
  Flag that indicates the parent (Vortex) environment is not to be inherited, which is the default. Useful for executing a program in a known fixed environment, since Vortex's environment may vary (eg. CGI vs. command line).

• MSG
  Flag that indicates error putmsgs are to be distributed, ie. printed/logged/captured as indicated by <vxcp putmsg> (p. ). This is the default behavior. If neither MSG nor NOMSG are specified, message distribution is according to <vxcp execmsg> (p. ). Added in version 5. Useful for enabling messages just for one <EXEC> when the default is set otherwise via <vxcp execmsg>. Note that in version 5, all <EXEC> putmsgs are also returned in $ret.err, regardless of MSG/NOMSG/<vxcp execmsg>.

• NOMSG
  Flag that indicates error putmsgs are not to be distributed via the current putmsg mechanisms. If neither MSG nor NOMSG are specified, message distribution is according to <vxcp execmsg> (p. ). Added in version 5. Note that in version 5, all <EXEC> putmsgs are also returned in $ret.err, regardless of MSG/NOMSG/<vxcp execmsg>. Setting NOMSG is an easy way to suppress putmsgs (eg. for exit codes or missing program) for just one <EXEC>, without having to set and clear <vxcp execmsg> or <vxcp putmsg>.

• MAXSTDOUT=$n
  Sets the maximum number of bytes of standard output read from the program; the default if empty or unspecified is no limit, Useful to avoid consuming large amounts of memory for $ret if a program unexpectedly returns lots of output. Added in version 5.

• MAXSTDERR=$n
  Sets the maximum number of bytes of standard error read from the program; the default if empty or unspecified is no limit, Useful to avoid consuming large amounts of memory for $ret if a program unexpectedly returns lots of error output. Added in version 5.

• APPEND
  Flag that indicates the immediately preceding TOFILE or STDERRTOFILE specification should append to the file (if using a file) instead of truncating it (the default). Note that in Windows versions a seek to EOF only occurs at file open, not atomically at each write() as in Unix. This means that two programs APPENDing to the same file over the same time period may erase each other's output under Windows, instead of interleaving as in Unix. Added in version 5.

• -- (two dashes)
  Flag that indicates the end of options, and that the program name and arguments follow. Useful to avoid confusion if a program has the same name as an option. Recommended for all <EXEC> calls to avoid confusion if future undetermined options are added to <EXEC>. Added in version 5.

DIAGNOSTICS
EXEC returns the standard output of the program (unless BKGND or TOFILE is given). If the NOBR or BIN flags are given, the output is one value; otherwise the output is split into one value per line.

EXAMPLE
This example runs a GIF to JPEG translator on the file /tmp/my.gif. The translator uses standard in and standard out, and the resulting JPEG is saved to a file:

<EXEC NOBR FROMFILE="/tmp/my.gif" --
    /usr/local/bin/gif2jpg>
</EXEC>
<write "/tmp/my.jpg"><fmt "%s" $ret></write>

CAVEATS
The EXEC statement was added Aug. 29 1996. The BIN and NOBR flags were added Feb. 4 1997. BKGND appeared Apr. 30 1997. Many other options appeared in version 5.

If TOFILE is ``-'' (single dash) for stdout, the program's output may appear out-of-sequence with respect to Vortex's output and will not be <CAPTURE>-able. This may change in a future version.

SEE ALSO
CAPTURE