cgi and exec. Executing a program

cgi and exec. Executing a program

^file::cgi[filename]
^file::cgi[filename;env_hash]
^file::cgi[filename;env_hash;arguments]   [3.2.2]
^file::cgi[filename;env_hash;argument1;argument2;…]
^file::cgi[format;filename;env_hash;arguments]   [3.2.2]
^file::cgi[format;filename;env_hash;argument1;argument2;…]   [3.2.2]
^file::exec[filename]
^file::exec[filename;env_hash]
^file::exec[filename;env_hash;arguments]   [3.2.2]
^file::exec[filename;env_hash;argument1;argument2;…]
^file::exec[format;filename;env_hash;arguments]   [3.2.2]
^file::exec[format;filename;env_hash;argument1;argument2;…]   [3.2.2]

Constructor cgi creates an object of class file, containing results returned by a program according to CGI standard .

Note: when a program/script is executed, directory with it will be its working directory.

Headers, returned by the CGI-script, will then become fields of class file converted into UPPERCASE. E.g., if a CGI-script script.pl returns a header some_field:some_value, then, on having processed
$f[^file::cgi[script.pl]]
we can address to $f.SOME_FIELD and get value some_value.

Constructor exec is similar to cgi but doesn't separate HTTP-headers from the text returned by the script.

format-defines format of loaded file and can be either text (default) or binary. While using binary format the result will not transcoded to $request:charset and will not truncated on first zero char.

filename-path and name of file.

Object, created by these constructors, has additional fields:
status-information on the status of program's termination (usually 0 (zero) means successful termination, while non-zero status means error);
stderr-standard errors stream.

Example
$cgi_file[^file::cgi[new.cgi]]
$cgi_file.text

Outputs text resulting from execution of new.cgi.

Optional arguments of constructors:

env_hash-hash, which can include

·	additional environment variables to be later accessed from within the script,

·	key stdin, containing text sent to the script in standard input stream,

·	key charset, which indicates charset in which script operates (data to and from script will be transcoded accordingly). [3.1.3]

Note: you can specify only standard CGI environment variables, or variables, whose names start with CGI_ or HTTP_ (restricted to: UPPERCASE Latin characters, numbers, underscore and hyphen).
Note: unsafe-mode version allows you to use CGI environment variables' names without any limitations. [3.4.1]
Note: while processing HTTP POST request, you can use construction $.stdin[$request:body] to send received POST data to the script's standard input stream.
Note: variables which were set by http server while executes Parser also will be availabe for scripts.
arguments-single-column table that contains arguments.

Example of how to execute an external cgi-script
$search[^file::cgi[search.cgi;$.QUERY_STRING[text=$form:q&page=$form:p]]]

Example of how to execute an external script
$script[^file::exec[script.pl;$.CGI_INFORMATION[I have had it enough]]]

Information being sent can be accessed and used within script script.pl:
print "Additional information: $ENV{CGI_INFORMATION}\n";

Example of receiving binary data from an external script
$response:body[^file::exec[binary;getfile.pl;$.CGI_FILENAME[$form:filename]]]

Example of passing several arguments
You can also send a number of arguments to the program by specifying them-separated by semicolon-after env_hash:
$script[^file::exec[script.pl;;height;width]]

...or specify arguments as a table with one column: [3.2.2]
$args[^table::create{arg
height
width}]
$script[^file::exec[script.pl;;$args]]

Example of how to execute a process in the background
If you need to execute a long-run process, it can be run in the background using a wrapper.
For wrapper to exit right away, the process stdout and stderr should be redirected:
#/bin/sh
sleep 60 >/dev/null 2>&1 &

Note: we insist that you store scripts to be run by constructors cgi and exec beyond web-space, since executing a script with arbitrary arguments may case unexpected consequences.

Last updated: 04.05.2016