Process Module

This [[Module Library|XQuery Module]] provides functions for executing system commands from XQuery.

=Conventions=

All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/proc</nowiki></code> namespace, which is statically bound to the {{Code|proc}} prefix.<br/>

=Functions=

==proc:system==

{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|proc:system|$cmd as xs:string|xs:string}}<br/>{{Func|proc:system|$cmd as xs:string, $args as xs:string*|xs:string}}<br/>{{Func|proc:system|$cmd as xs:string, $args as xs:string*, $options as map(xs:string, xs:string)|xs:string}}<br/>
|-
| '''Summary'''
|Executes the specified command in a separate process and returns the result as string. {{Code|$cmd}} is the name of the command, arguments to the command may be specified via {{Code|$args}}. The {{Code|$options}} parameter contains process options:
* {{Code|encoding}}: convert result to the specified encoding. If no encoding is supplied, the system’s default encoding is used.
* {{Code|timeout}}: abort process execution after the specified number of seconds.
* {{Code|dir}}: process command in the specified directory.
* {{Code|input}}: standard string input ({{Code|stdin}}) to be passed on to the command.
|-
|'''Errors'''
|{{Error|encoding|#Error}} the specified encoding does not exist or is not supported.<br/>{{Error|timeout|#Error}} the specified timeout was exceeded.<br/>{{Error|error|#Error}} the command could not be executed, or an I/O exception was raised.<br/>{{Error|code....|#Error}} If the commands returns an exit code different to 0, an error will be raised. Its code will consist of the letters {{Code|code}} and four digits with the exit code.<br/>
|-
| '''Examples'''
|
* {{Code|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 {{Code|wc}} is available on the system):
<pre class="brush:xquery">
proc:system(
  'wc', (),
  map { 'input': 'A B' || out:nl() || 'C' }
)
</pre>
* The following example returns “Command not found” (unless {{Code|xyz}} is a valid command on the system):
<pre class="brush:xquery">
try {
  proc:system('xyz')
} catch proc:error {
  'Command not found: ' || $err:description
}
</pre>
|}

==proc:execute==

{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|proc:execute|$cmd as xs:string|element(result)}}<br/>{{Func|proc:execute|$cmd as xs:string, $args as xs:string*|element(result)}}<br/>{{Func|proc:execute|$cmd as xs:string, $args as xs:string*, $options as map(xs:string, xs:string)|element(result)}}
|-
| '''Summary'''
|Executes the specified command in a separate process and returns the result as element:
* {{Code|$cmd}} is the name of the command, and arguments to the command may be specified via {{Code|$args}}.
* The same {{Code|$options}} are allowed as for [[#proc:system|proc:system]].
* Instead of the {{Code|proc:error}} error, the error message and process code will be assigned to the returned elements.
* Instead of the {{Code|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:
<pre class="brush:xml">
<result>
  <output>...output...</output>
  <error>...error message...</error>
  <code>...process code...</code>
</result>
</pre>
|-
|'''Errors'''
|{{Error|encoding|#Error}} the specified encoding does not exist or is not supported.<br/>{{Error|timeout|#Error}} the specified timeout was exceeded.
|-
| '''Examples'''
|
* {{Code|proc:execute('dir', '\')}} returns the files of the root directory of a Windows system.
* {{Code|proc:execute('ls', ('-l', '-a'))}} executes the {{Code|ls -la}} command on Unix systems.
|}

==proc:fork==

{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|proc:fork|$cmd as xs:string|element(result)}}<br/>{{Func|proc:fork|$cmd as xs:string, $args as xs:string*|element(result)}}<br/>{{Func|proc:fork|$cmd as xs:string, $args as xs:string*, $options as map(xs:string, xs:string)|element(result)}}
|-
| '''Summary'''
|Executes the specified command and ignores the result. {{Code|$cmd}} is the name of the command, and arguments to the command may be specified via {{Code|$args}}. The same {{Code|$options}} are allowed as for [[#proc:system|proc:system]] (but the encoding will be ignored).
|-
|'''Errors'''
|{{Error|encoding|#Error}} the specified encoding does not exist or is not supported.
|-
| '''Examples'''
|
* {{Code|proc:fork('sleep', '5')}}: sleep for 5 seconds (no one should notice).
|}

==proc:property==

{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|proc:property|$name as xs:string|xs:string?}}<br/>
|-
| '''Summary'''
|Returns the system property, specified by {{Code|$name}}, or a context parameter of the {{Code|web.xml}} file with that name (see [[Web_Application#Configuration|Web Applications]]). An empty sequence is returned if the property does not exist. For environment variables of the operating system, please use [https://www.w3.org/TR/xpath-functions-30/#func-environment-variable fn:environment-variable]. 
|-
| '''Examples'''
|
* {{Code|proc:property('java.class.path')}} returns the full user class path.
* {{Code|map:merge(proc:property-names() ! map:entry(., proc:property(.)))}} returns a map with all system properties.
|}

==proc:property-names==

{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|proc:property-names||xs:string*}}<br/>
|-
| '''Summary'''
|Returns the names of all Java system properties and context parameters of the {{Code|web.xml}} file  (see [[Web_Application#Configuration|Web Applications]]). For environment variables of the operating system, please use [https://www.w3.org/TR/xpath-functions-30/#func-available-environment-variables fn:available-environment-variables]. 
|-
| '''Examples'''
|
* {{Code|proc:property('java.runtime.version')}} returns the version of the Java runtime engine.
|}

=Errors=

{| class="wikitable" width="100%"
! width="110"|Code
|Description
|-
|{{Code|code...}}
|The result of a command call with an exit code different to 0.
|-
|{{Code|code9999}}
|A command could not be executed.
|-
|{{Code|encoding}}
|The specified encoding does not exist or is not supported.
|-
|{{Code|timeout}}
|The specified timeout was exceeded.
|}

=Changelog=

;Version 9.0

* Added: [[#proc:fork|proc:fork]]
* Updated: error codes; errors now use the module namespace
* Updated: new {{Code|input}} option; revised error handling

;Version 8.6

* Updated: [[#proc:system|proc:system]], [[#proc:exec|proc:exec]]: {{Code|encoding}} option moved to options argument, {{Code|timeout}} and {{Code|dir}} options added.

;Version 8.3

* Added: [[#proc:property|proc:property]], [[#proc:property-names|proc:property-names]].

The module was introduced with Version 7.3.