Process Module

This XQuery Module provides functions for executing system commands from XQuery.

Conventions

All functions and errors in this module are assigned to the http://basex.org/modules/proc namespace, which is statically bound to the proc prefix.

Functions

proc:system

Signature	proc:system( $cmd as xs:string, $args as xs:string* := (), $options as map(*) := () ) as xs:string
Summary	Executes the specified command in a separate process and returns the result as string. $cmd is the name of the command, arguments to the command may be specified via $args. The $options parameter contains process options: encoding: convert result to the specified encoding. If no encoding is supplied, the system’s default encoding is used. timeout: abort process execution after the specified number of seconds. dir: process command in the specified directory. input: standard string input (stdin) to be passed on to the command.
Errors	encoding: the specified encoding does not exist or is not supported. timeout: the specified timeout was exceeded. error: the command could not be executed, or an I/O exception was raised. code....: If the commands returns an exit code different to 0, an error will be raised. Its code will consist of the letters code and four digits with the exit code.
Examples	proc:system('date') returns the current date on a Linux system. Analyses the given input and counts the number of lines, words and characters (provided that wc is available on the system): <syntaxhighlight lang="xquery"> proc:system( 'wc', (), map { 'input': 'A B' || out:nl() || 'C' } ) </syntaxhighlight> The following example returns “Command not found” (unless xyz is a valid command on the system): <syntaxhighlight lang="xquery"> try { proc:system('xyz') } catch proc:error { 'Command not found: ' || $err:description } </syntaxhighlight>

proc:execute

Signature	proc:execute( $cmd as xs:string, $args as xs:string* := (), $options as map(*) := () ) as element(result)
Summary	Executes the specified command in a separate process and returns the result as element: $cmd is the name of the command, and arguments to the command may be specified via $args. The same $options are allowed as for proc:system. Instead of the proc:error error, the error message and process code will be assigned to the returned elements. Instead of the proc:code.... error, the error message will be assigned to the returned element (no process code will be returned). The result has the following structure: <syntaxhighlight lang="xml"> <result> <output>...output...</output> <error>...error message...</error> ...process code... </result> </syntaxhighlight>
Errors	encoding: the specified encoding does not exist or is not supported. timeout: the specified timeout was exceeded.
Examples	proc:execute('dir', '\') returns the files of the root directory of a Windows system. proc:execute('ls', ('-l', '-a')) executes the ls -la command on Unix systems.

proc:fork

Signature	proc:fork( $cmd as xs:string, $args as xs:string* := (), $options as map(*) := () ) as element(result)
Summary	Executes the specified command and ignores the result. $cmd is the name of the command, and arguments to the command may be specified via $args. The same $options are allowed as for proc:system (but the encoding will be ignored).
Errors	encoding: the specified encoding does not exist or is not supported.
Examples	proc:fork('sleep', '5'): sleep for 5 seconds (no one should notice).

proc:property

Signature	proc:property( $name as xs:string ) as xs:string?
Summary	Returns the system property, specified by $name, or a context parameter of the web.xml file with that name (see Web Applications). An empty sequence is returned if the property does not exist. For environment variables of the operating system, please use fn:environment-variable.
Examples	proc:property('java.class.path') returns the full user class path. map:merge(proc:property-names() ! map:entry(., proc:property(.))) returns a map with all system properties.

proc:property-names

Signature	proc:property-names() as xs:string*
Summary	Returns the names of all Java system properties and context parameters of the web.xml file (see Web Applications). For environment variables of the operating system, please use fn:available-environment-variables.
Examples	proc:property('java.runtime.version') returns the version of the Java runtime engine.

Errors

Code	Description
code...	The result of a command call with an exit code different to 0.
code9999	A command could not be executed.
encoding	The specified encoding does not exist or is not supported.
timeout	The specified timeout was exceeded.

Changelog

Version 9.0

• Added: proc:fork
• Updated: error codes; errors now use the module namespace
• Updated: new input option; revised error handling

Version 8.6

• Updated: proc:system, proc:exec: encoding option moved to options argument, timeout and dir options added.

Version 8.3

• Added: proc:property, proc:property-names.

The module was introduced with Version 7.3.