execute

Library: Process execution (OMPROCESS)
Import: omprocess.xmd
Return type: Integer
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:

OMPROCESS_002 Unable to launch process.
OMPROCESS_003 Process terminated abnormally.
OMPROCESS_004 Directory 'X' is not accessible.
OMPROCESS_005 Unable to change to directory 'X'.
OMPROCESS_006 Unable to create pipe for 'X'.
OMPROCESS_007 Unable to write to child process.

Other Library Functions
   command-line
   executable-name
   execute
   glob
   omprocess-version

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACY LIBRARIES ] [ ERRORS ]

OmniMark 8.2.0 Documentation Generated: March 13, 2008 at 3:27:39 pm
If you have any comments about this section of the documentation, please use this form.