Changes

This [[Module Library|XQuery Module]] provides functions for executing system commands from XQuery.  =Conventions= All functions and errors in this module are introduced with the {{Mono|proc:}} prefix, which is linked assigned to the statically declared {{Mono|<code><nowiki>http://basex.org/modules/proc</nowiki></code> namespace, which is statically bound to the {{Code|proc}} namespaceprefix.<br/>

 {|width='100%'|-valign="top"| width='90120' | '''SignaturesSignature'''|{{Mono|<bpre>proc:system</b>( $cmd as xs:string) as xs:string}}<br/>{{Mono|<b>proc:system</b>($cmd command as xs:string, $args arguments as xs:string*) as xs :string}}<br/>{{Mono|<b>proc:system</b>= ($cmd as xs:string), $args options as xs:stringmap(*, $encoding as xs)? :string= map { }) as xs:string}}</pre>|-valign="top"

|Executes a {{Code|$command}} with the specified command {{Code|$arguments}} in a separate process and returns the result as a string.<br/>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 results in an error, an XQuery exception will the specified directory.* {{Code|input}}: standard string input ({{Code|stdin}}) to be thrownpassed on to the command. Its error code will consist of |- valign="top"|'''Errors'''|{{Error|encoding|#Error}} the letters specified encoding does not exist or is not supported.<br/>{{MonoError|timeout|PROC#Error}} and four digits with the command’s exit codespecified timeout was exceeded.<br/>Additional command arguments may be specified via {{MonoError|error|$args#Error}}the command could not be executed, or an I/O exception was raised.<br/>The result can be explicitly converted to a specified {{MonoError|code....|$encoding#Error}}. If no encoding is specifiedthe commands returns an exit code different to 0, an error will be raised. Its code will consist of the system’s default encoding is usedletters {{Code|code}} and four digits with the exit code.<br/>|-valign="top"

* {{MonoCode|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 lang='xquery'>proc:system( 'wc', (), map { 'input': 'A B' || out:nl() || 'C' })</pre>* The following example returns "Command “Command not found", if found” (unless {{Code|xyz}} is a valid command on the command "xyz" cannot be located or executedsystem):<pre classlang="brush:'xquery"'>

} catch PROC0001 proc:error { 'Command not found.: '|| $err:description

 {|width='100%'|-valign="top"| width='90120' | '''SignaturesSignature'''|{{Mono|<bpre>proc:execute</b>($cmd as xs:string) as element(result)}}<br/>{{Mono|<b>proc:execute</b>( $cmd command as xs:string, $args arguments as xs:string*) as element := (result)}}<br/>{{Mono|<b>proc:execute</b>($cmd as xs:string, $args options as xs:stringmap(*, $encoding as xs)? :string= map { }) as element(result)}}</pre>|-valign="top"

|Executes a {{Code|$command}} with the specified command {{Code|$arguments}} in a separate process and returns the result as an element.<br/>Additional command arguments may be specified via :* The same {{MonoCode|$argsoptions}} are allowed as for {{Function||proc:system}}.<br/>The result can * Instead of the {{Code|proc:error}} error, the error message and process code will be explicitly converted assigned to a specified the returned elements.* Instead of the {{MonoCode|$encodingproc:code....}}. If no encoding is specifiederror, the system’s default encoding is usederror message will be assigned to the returned element (no process code will be returned).<br/>A The result has the following structure:<br/><pre classlang="brush:xml">

<output>...resultoutput...</output> <error>...error message...</error> <code>0...process code...</code>

|-valign="top"|'''Errors'''|{{Error|encoding|#Error}} the specified encoding does not exist or is not supported.<br/>{{Error|timeout|#Error}} the specified timeout was exceeded.|- valign="top"| '''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%'|- valign="top"| width='120' | '''Signature'''|<pre>proc:fork( $command as xs:string, $arguments as xs:string* := (), $options as map(*)? := map { }) as element(result)</pre>|- valign="top"| '''Summary'''|Executes a {{Code|$command}} with the specified {{Code|$arguments}} in a separate process and ignores the result. The same {{Code|$options}} are allowed as for {{Function||proc:system}} with the encoding being ignored.|- valign="top"|'''Errors'''|{{Error|encoding|#Error}} the specified encoding does not exist or is not supported.|- valign="top"| '''Examples'''|* {{Code|proc:fork('sleep', '5')}}: sleep for 5 seconds (no one should notice).|} ==proc:property== {| width='100%'|- valign="top"| width='120' | '''Signature'''|<pre>proc:property( $name as xs:string) as xs:string?</pre>|- valign="top"| '''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]. |- valign="top"| '''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%'|- valign="top"| width='120' | '''Signature'''|<pre>proc:property-names() as xs:string*</pre>|- valign="top"| '''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]. |- valign="top"

* {{MonoCode|proc:executeproperty('dir', '\java.runtime.version')}} returns the root directory on version of the Java runtime engine.|} =Errors= {| class="wikitable" width="100%"! width="110"|Code|Description|- valign="top"|{{Code|code...}}|The result of a Windows systemcommand call with an exit code different to 0.|- valign="top"|{{Code|code9999}}|A command could not be executed.|- valign="top"|{{Code|encoding}}|The specified encoding does not exist or is not supported.|- valign="top"|{{Code|timeout}}|The specified timeout was exceeded.

The ;Version 9.0 * Added: {{Function||proc:fork}}* Updated: error codes; errors now use the module was introduced with namespace* Updated: new {{Code|input}} option; revised error handling ;Version8.6 * Updated: {{Function||proc:system}}, {{Function||proc:exec}}: {{Code|7encoding}} option moved to options argument, {{Code|timeout}} and {{Code|dir}} options added.2 ;Version 8.23 * Added: {{Function||proc:property}}, {{Function||proc:property-names}}. The module was introduced with Version 7.3.