Other Library Functions

execute

function

Library: Process execution (OMPROCESS)
Import : omprocess.xmd

Returns: The return code generated by executing the specified process


Declaration 
export integer function
        execute              value     command-line-type command-line
                in-directory value     string            initial-directory optional
                       stdin value     string source     stdin             optional
                      stdout value     string sink       stdout            optional
                      stderr value     string sink       stderr            optional
                 environment read-only string            environment       optional

Argument definitions

command-line
is a representation of the command-line used to launch the process
initial-directory
is the starting directory of execution
stdin
is the standard input stream for the process
stdout
is the standard output stream of the process
stderr
is the standard error stream of the process
environment
is a collection of environment variables for the process


Purpose

The execute function launches the execution of a program external to OmniMark, using the provided command-line. The program is fed its input from the stdin argument; the stdout argument can be used to process the output generated by the program. Similarly, the stderr argument can be used to process the error stream from the program. If stdin is not specified, it defaults to an empty string, whereas if either or both of stdout and stderr are not specified, they default to #suppress.

The environment shelf is used to specify a set of environment variables that are provided to the process when it is launched. The value of each item on the environment shelf should have the form 

  NAME=VALUE
where VALUE may be a zero-length string. The shelf item keys are not used, and need not be set to anything. On both Unix and Windows platforms, the ENVIRONMENT shelf represents the entire environment variable space of the process: its items are not merged with any pre-existing environment variables. In the case where any pre-existing environment variables should be preserved, the following procedure should be followed: 
       import "omutil.xmd" prefixed by util.
  
       process
          local string environment variable
  
          repeat over util.environment as e
             set new environment to key of e || "=" || e
          again
  
          ; Add any additional environment variables.

Following this, the local shelf environment will contain the appropriately-merged set of environment variables, and can be passed to the execute function.

When the execute function terminates, its value is the return code provided by the execution of the program.

Exceptions

The following exceptions may occur:

Other Library Functions