1. Documentation
2. Command-Line Plug-In

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:

• The cmdline/exec procedure – A built-in procedure for running any program. Only accessible to users with the admin role. This procedure should normally only be used for testing and development.
• Procedures of the cmdline.exec type – Supports inserting procedure arguments into the command-line or into the environment. Useful to enable limited command-line access for normal users and for storing pre-configured commands.

2. Return Values

Using the cmdline/exec procedure, the command-line execution can easily be tested. Below follows some simple command examples (using a Unix environment):

cmdline/exec('ls', '', '')
  --> { exitValue: 0, output: 'cmdline http jdbc ...' }

cmdline/exec('test 0 -eq 1', '', '')
  --> { exitValue: 1, output: '' }

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:

• exitValue – The return status code from the operating system process. Normally 0 (zero) if the execution succeeded and non-zero otherwise. See the documentation for each command for more information.
• output – The output text from the program. In the examples above this has been simplified, but the actual strings are not truncated and may contain newline characters (and other control characters).

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:

• stdin – Always an empty input stream, returning EOF on the first byte read.
• stdout – All output is captured and returned in the output string as part of the result.
• stderr – All output is captured and sent to the thread context log.

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:

• Directory – The working directory for the program. If not specified or left blank, the plugin/ directory will be used.
• Environment – The list of environment variables to set, specified in a NAME1=VALUE1;NAME2=VALUE2;... format, each entry separated by a ; character. If not specified or left blank, all the RapidContext environment variables will be passed on unmodified.

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.

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