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 command-line is provided with either of the functions command-line or executable-name. Examples appear below.

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. If the environment argument is unspecified, the environment of the OmniMark program is passed on to the program being launched.

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

Examples: command-line

The examples that follow centre around using OMPROCESS to launch the Unix tar utility. Given a list of filenames in a file called list.txt, a typical invocation of the tar utility might resemble 

  tar -zcf results.tar.gz [filenames]
where [filenames] is the contents of the file list.txt, and where results.tar.gz is the name of the resultant archive. This invocation can be specified directly in OMPROCESS using the command-line function: 
  import "omprocess.xmd" unprefixed
  
  process
     void execute command-line ("tar -zcf results.tar.gz " || file "list.txt")
Here, the file operator is used to expand the file list.txt and append it to the leading part of the command line. (The parentheses are needed due to the precedence of heralded arguments in OmniMark.)

The tar utility can take a list of filenames by using its -T command-line option: 

  tar -zcf results.tar.gz -T list.txt
This invocation can be mimicked in OMPROCESS directly using command-line: 
  import "omprocess.xmd" unprefixed
  
  process
     void execute command-line "tar -zcf results.tar.gz -T list.txt"
Beyond this, tar can read the list of filenames from its standard input if the argument to the -T command-line option is a lone hyphen (-) 
  tar -zcf results.tar.gz -T - < list.txt
This command line is modelled in OMPROCESS as 
  import "omprocess.xmd" unprefixed
  
  process
     void execute command-line "tar -zcf results.tar.gz -T -" 
                         stdin file "list.txt"
where the stdin argument to execute has been used to feed the contents of the file list.txt onto the standard input of the tar utility. However, since the stdin argument is an arbitrary string source, its value need not be a static file. In fact, we could use any OmniMark string source including using a string source function to generate the list of filenames dynamically. Consider the following example, somewhat contrived for brevity: 
  import "omprocess.xmd" unprefixed
  
  define string source function
     file-list ()
  as
     output file "list.txt"
  
  
  process
     void execute command-line "tar -zcf results.tar.gz -T -" 
                         stdin file-list ()
Finally, the hyphen convention that allows the list of files to be specified on the standard input of the tar utility can also be used to specify that the archive should be written to standard output. In fact, in the somewhat esoteric Unix command line 
  tar -zcf - -T - < list.txt > results.tar.gz
the tar utility will read the list of files from its standard input, and write the archive to its standard output. Using OMPROCESS, this command line might be written 
  import "omprocess.xmd" unprefixed
  
  process
     void execute command-line "tar -zcf - -T -" 
                         stdin file "list.txt" 
                        stdout file "results.tar.gz"
In complete symmetry with the example of a dynamically-generated list of filenames given above, the stdout argument can be an arbitrary OmniMark string sink. For example, again contrived for brevity: 
  import "omprocess.xmd" unprefixed
  
  define string source function
     file-list ()
  as
     output file "list.txt"
  
  
  define string sink function
     destination ()
  as
     set file "results.tar.gz" to #current-input
  
  
  process
     void execute command-line "tar -zcf - -T -" 
                         stdin file-list () 
                        stdout destination ()

Examples: executable-name

All of the examples given in the previous section using the command-line function can be specified using the executable-name function. The executable-name function builds a command line from an executable name and a string shelf of arguments, and is useful when finer control over command-line parsing is desired. This might be the case, for instance, if some arguments on the command line contain spaces.

The list of filenames in list.txt can be collected onto a shelf using a straightforward repeat scan loop: 

  process
     local string arguments variable
  
     repeat scan #main-input
     match any ++ => t ("%n" | value-end)
        set new arguments to t
     again
For the first, simplistic invocation of the tar utility, the arguments -zcf results.tar.gz are best placed ahead of the list of filenames. This is most easily done by initializing the arguments shelf to contain them from the start: 
  process
     local string arguments variable initial { "-zcf", "results.tar.gz" }
  
     ; ...
The invocation of the tar utility now takes the form 
  import "omprocess.xmd" unprefixed
  
  process
     local string arguments variable initial { "-zcf", "results.tar.gz" }
  
     ; Load the ARGUMENTS shelf with filenames ...
  
     void execute executable-name "tar" arguments arguments
where the repeat scan loop has been omitted for brevity. The other invocations follow similarly; for example, the final example from above could be written in its entirety as 
  import "omprocess.xmd" unprefixed
  
  define string source function
     file-list ()
  as
     output file "list.txt"
  
  
  define string sink function
     destination ()
  as
     set file "results.tar.gz" to #current-input
  
  
  process
     void execute executable-name "tar" arguments { "-zcf", "-", "-T", "-" }
                            stdin file-list ()
                           stdout destination ()

Exceptions

The following exceptions may occur:

Other Library Functions