cgi and exec. Executing a program

^file::cgi[filename]
^file::cgi[filename;env_hash]
^file::cgi[filename;env_hash;argument
s]   [3.2.2]
^file::cgi[filename;env_hash;argument
1;argument2;…]
^file::cgi[format;filename;env_hash;argument
s]   
[3.2.2]
^file::cgi[format;filename;env_hash;argument
1;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;argument
1;argument2;…]
^file::exec[format;filename;env_hash;argument
s]   
[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.


Copyright © 1997–2021 Art. Lebedev Studio | http://www.artlebedev.com Last updated: 04.05.2016