Navigation :

Exec Datasets

The exec configuration entry allows you to define commands which should be executed on the server side, with the output results returned to the client via the http response. The return is synchronous, i.e. the client is expected to wait for the response. Common exec commands may be e.g. to run a reporting program such as Jasper Reports.

None or more exec configurations may be defined. The dataset name must not conflict with any other exec dataset, any plugin dataset, any regular dataset, or any special dataset.

When invoking an exec, use the GET or POST methods. Specify the exec dataset name in the URL, e.g. if the dataset attribute of the exec element is echo then access the dataset with the following URL.

http://localhost/jarvis-agent/demo/echo/

Configuration

The configuration for an exec element is as follows:

Attribute	Default	Notes
`dataset`	(none)	Dataset name which is to be interpreted as an `exec` rather than a regular dataset. Mandatory parameter. The actual dataset given in the Jarvis request must match this, or a sub-dataset of this. E.g. if the exec configuration specifies `jasper` as its dataset name, then the dataset name supplied to Jarvis by the client may be `jasper` or `jasper.ReportName`.
`access`	(none)	This lists the group names that the logged-in user must belong to one of before they can access this `exec`. Specify a group name, comma-separated list, `` or `*`. See the documentation for `read` and `write` groups on regular datasets for further details.
`command`	(none)	This is the command line to be executed. Mandatory parameter.
`add_headers`	`no`	If yes, Jarvis will add Cookie, Content-Type and Content-Disposition headers to the response. Otherwise the exec command is entirely responsible for printing ALL headers. If `add_headers` is no, be sure to add the header `Cache-Control` and set the value to `no-cache` yourself in the outgoing response if you want to avoid responses being cached by IE.
`mime_type`	(none)	Only used if `add_headers` is `yes`. Allow exec to override the default MIME type by specifying a value to use. This takes precedence over any mime type which may be derived from a filename.
`filename_parameter`	`filename`	Only used if `add_headers` is `yes`. We expect a CGI parameter of this name to be present and to contain the returned filename. If you wish to use `filename` as a normal parameter to your exec, you will need to change this configuration.
`default_filename`	(none)	Only used if `add_headers` is `yes`. Default filename to use if no `filename_parameter` is defined or if the CGI parameter named by `filename_parameter` is not present.
`use_tmpfile`	depends	Whether or not the command should write its output to a temporary file or not. The default is `no` under non-MS Windows operating systems, and `yes` for MS Windows. This is required under MS Windows with Apache otherwise output will be corrupted. If this is set to `yes`, or the system is running on MS Windows, the parameter `__use_tmpfile` is passed through on the command line and references the filename of the file into which the command’s output should be placed. See following notes on output methods.
`tmp_directory`	depends	This allows you to overwrite the default TMP directory to be used when exec output is spooled to file instead of printed directly to the http client via standard output. Specifying `tmp_directory` will force the use of temporary files, regardless of the value of the `use_tmpfile` parameter.
`tmp_http_path`	(none)	Setting the parameter tells Jarvis to redirect the client to the output temporary file via this URI which must be configured in the web server to point to the temporary directory. E.g. if `tmp_directory` is `/tmp` and `tmp_http_path` is `/tmp-reports` then the webserver must contain an alias mapping http://host/tmp-reports/ to `/tmp`. Use of a dedicated report output directory is recommended for security reasons. Specifying `tmp_http_path` will force the use of temporary files, regardless of the value of the `use_tmpfile` parameter. Specifying `tmp_http_path` will mean that `add_headers` is ignored, as MIME headers are not relevant to a redirection response.
`cleanup_after`	`0`	If set to a non-zero value, this parameter will enable clean-up of files in the temporary directory after the specified number of minutes. Set to zero (default) means “never clean-up”. Jarvis will only remove files which are owned by the user running the server script (e.g. www-data). Even so, care should be taken when using a shared temporary directory for exec output.
`debug`	(none)	Enable `debug` output to standard error for this exec only. This parameter can not be used to disable global debugging.
`dump`	(none)	Enable `dump` output to standard error for this exec only. This parameter can not be used to disable global dump output.

Output Return Mechanism

Given the above configuration, there are three different ways in which Jarvis might return the output from an exec dataset.

These are as follows:

Mechanism	Notes
Redirection	This mechanism is used if and only if `tmp_http_path` is specified. Jarvis will choose a value for `__tmpfile` which is based on the `reportfile` name requested by the client. A random component will be added to the name and it is guaranteed not to exist at the time of `exec`. The `__tmpfile` parameter is passed to the executable command line. The executable command line write its output in that file. When the execution is complete, Jarvis will send back a `302 Found` response to the client to redirect it to the new output using the specified `tmp_http_path`. This is the recommended approach for cross-platform systems and/or large output and/or binary data.
Streaming	If `use_tmpfile` and/or `tmp_directory` is specified without specifying any value for `tmp_http_path` then streaming will be used. Jarvis will choose a value for `__tmpfile` which is based on the `reportfile` name requested by the client. A random component will be added to the name and it is guaranteed not to exist at the time of `exec`. The `__tmpfile` parameter is passed to the executable command line. The executable command line write its output in that file. When the execution is complete, Jarvis will loop through this file and stream the contents back to the client. If configured, Jarvis will add headers derived from the filename parameter. This is method appears to work fine under Windows under HTTP. Problems have been encountered with this method under Linux. Problems have been encountered with this method under Windows with Apache/HTTPS.
Direct /STDOUT	If no `tmpfile` parameters are specified, then Jarvis will copy the STDOUT of the executed program and will echo it via STDOUT through the server and back to the client. Problems have been encountered with this method under Windows with binary data.

A Simple Example

A sample exec is defined in the demo application, as follows:

<jarvis>
	<app>
    	<exec use_tmpfile=”no” dataset="echo" access="*" command="echo" add_headers="yes" filename_parameter="filename"/>
        ...

This uses the Unix echo program to simply echo its parameters back to standard output. We will use this to demonstrate the parameters available to exec datasets.

Environment Variables

The environment variables to the exec are the same as to the Jarvis script itself. Refer to the Apache documentation for details.

In addition, if the debug attribute is yes for this application’s main configuration, then the environment variable DEBUG will be set to DEBUG=1 when calling the exec process.

Command Line Parameters

The exec parameters to the command line are essentially those passed into SQL dataset statements. They will include:

Any GET or POST parameters supplied in the request, subject to the standard permitted syntax as described in the regular dataset section. i.e. user-supplied parameters may not start with a double-underscore, may not include special characters, etc.
Indexed RESTful parameters specified in the URI. These are passed as p1, p2, etc.
Named RESTful parameters assigned by a route rule. See the router configuration.
The parameter __dataset is given as the client-supplied dataset given to Jarvis which invoked this exec request.
The parameter __tmpfile is given if use_tmpfile is configured for this exec.
The Jarvis secure parameters beginning with double-underscore. These include __username, __group_list, etc.
Any default parameters configured in the <default_parameters> section.

E.g with the supplied demo.xml file, consider the following request.

http://localhost/jarvis-agent/demo/echo.test/v1//v2?he=th'is&she=that

The command line executed will be:

echo __group:admin='1' __dataset='echo.test' __group_list='admin' __username='admin' he='th'\''is' max_rows='500' p1='v1' p2='' p3='v2' she='that'

The parameters are quoted to make them safe for the command shell.

Output & Headers

The exec process should write its output to standard output. If add_headers is no then the program is also responsible for writing HTTP headers and a blank line before beginning output.

If add_headers is yes then Jarvis will add the content type headers. In addition, Jarvis can add a Content-Disposition header if you supply the default_filename and filename_parameter parameters.

The filename_parameter configuration parameter specifies the name of the client-given CGI parameter to evaluate to determine the returned filename. If not present, the value of the default_filename parameter will be used. This will be used as the filename in the Content-Disposition header when returning the output to the client. The filename suffix will be examined to determine the appropriate Content-Type header value to use.

Exec output may include binary data. For a practical example, see the png exec in demo.xml.