Command-Line Plug-In

The command-line plug-in provides the ability to execute programs on the RapidContext server. This allows RapidContext to run shell scripts, binary executables or system utilities supporting a non-interactive or scriptable execution.

1. Built-in Procedure & Procedure Type

The command-line plug-in provides two ways to execute programs on the server:

2. Return Values

Using the PlugIn.CmdLine.Exec procedure, the command-line execution can easily be tested. Below follows some simple command examples (using a Unix or Cygwin environment):

PlugIn.CmdLine.Exec('dir', '', '')
  --> { exitValue: 0, output: 'cmdline http jdbc ...' }

PlugIn.CmdLine.Exec('test 0 -eq 1', '', '')
  --> { exitValue: 1, output: '' }

PlugIn.CmdLine.Exec('bash -c set', '', '')
  --> { exitValue: 0, output: 'BASH=/bin/bash BASH_ARGC=() BASH_ARGV=...' }

The result of a program execution is always an object with the following properties:

3. Input & Output Streams

When executing command-line programs, the RapidContext server captures the standard input and output streams (file descriptors 0, 1 & 2) in the following way:

Using the stderr stream, the program may also communicate progress information back to the server thread context. If the command is executed in a background thread, this information can be retrieved using System.Thread.Context and displayed in a progress bar or similar.

Each progress update must be on its own line and should be flushed to the stderr stream immediately (normally automatic). Each line starting with a # character will be analyzed, but only the lines matching the progress information format below will be used:

...
# progress: 34.9%
# progress: 35.0%
# progress: 35.3%
...

4. Execution Environment

The execution environment for each command can be controlled by the following two parameters:

The executable lookup is performed by the underlying operating system using the PATH variable as it was set when the RapidContext server was started. An absolute path to the executable program can naturally also be specified at the beginning of the command-line.

Notice

Some commands like cd & set are not binary executables on most systems, but instead available as shell built-ins. These commands are available by executing the shell binary and specifying the command with a parameter (see the example above).

5. Parameter Substitution

Command-line arguments and environment values may contain procedure call arguments (for cmdline.exec procedures). These are substituted with the procedure argument values at call time. Each procedure argument name must be prefixed with a : character in the command-line or environment string in order to be replaced:

# Substituting a 'dirName' procedure argument
echo :dirName