Difference between revisions of "Process Module"

From BaseX Documentation
Jump to navigation Jump to search
(27 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
=Conventions=
 
=Conventions=
  
All functions 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/>
+
{{Mark|Updated with Version 9.0:}}
All errors are assigned to the <code><nowiki>http://basex.org/errors</nowiki></code> namespace, which is statically bound to the {{Code|bxerr}} prefix.
+
 
 +
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=
 
=Functions=
  
 
==proc:system==
 
==proc:system==
 +
 +
{{Mark|Updated with Version 9.0:}} new {{Code|input}} option; revised error handling.
  
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| 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*, $encoding as xs:string|xs:string}}<br/>
+
|{{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'''
 
| '''Summary'''
|Executes the specified command in a separate process and returns the result as string.<br/>{{Code|$cmd}} is the name of the command. Arguments to the command may be specified via {{Code|$args}}.<br/>The result can be explicitly converted to a specified {{Code|$encoding}}. If no encoding is specified, the system’s default encoding is used.
+
|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'''
 
|'''Errors'''
|{{Error|BXPRnnnn|#Error}} If the command results in an error, an XQuery error will be raised. Its code will consist of the letters {{Code|BXPR}} and four digits with the command’s exit code.<br/>{{Error|BXPR9999|#Error}} the specified encoding does not exist or is not supported.
+
|{{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'''
 
| '''Examples'''
 
|
 
|
 
* {{Code|proc:system('date')}} returns the current date on a Linux system.
 
* {{Code|proc:system('date')}} returns the current date on a Linux system.
* The following example returns "Command not found", if the command "xyz" cannot be located or executed:
+
* 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">
 
<pre class="brush:xquery">
 
try {
 
try {
 
   proc:system('xyz')
 
   proc:system('xyz')
} catch bxerr:BXPR0002 {
+
} catch proc:error {
   'Command not found.'
+
   'Command not found: ' || $err:description
 
}
 
}
 
</pre>
 
</pre>
Line 39: Line 53:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| 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*, $encoding as xs:string|element(result)}}
+
|{{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'''
 
| '''Summary'''
|Executes the specified command in a separate process and returns the result as element.<br/>{{Code|$cmd}} is the name of the command. Arguments to the command may be specified via {{Code|$args}}.<br/>The result can be explicitly converted to a specified {{Code|$encoding}}. If no encoding is specified, the system’s default encoding is used.<br/>A result has the following structure:<br/>
+
|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">
 
<pre class="brush:xml">
 
<result>
 
<result>
   <output>...result output...</output>
+
   <output>...output...</output>
   <error>...error output...</error>
+
   <error>...error message...</error>
   <code>0</code>
+
   <code>...process code...</code>
 
</result>
 
</result>
 
</pre>
 
</pre>
 
|-
 
|-
 
|'''Errors'''
 
|'''Errors'''
|{{Error|BXPR9999|#Error}} the specified encoding does not exist or is not supported.
+
|{{Error|encoding|#Error}} the specified encoding does not exist or is not supported.<br/>{{Error|timeout|#Error}} the specified timeout was exceeded.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 58: Line 77:
 
* {{Code|proc:execute('dir', '\')}} returns the files of the root directory of a Windows system.
 
* {{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.
 
* {{Code|proc:execute('ls', ('-l', '-a'))}} executes the {{Code|ls -la}} command on Unix systems.
 +
|}
 +
 +
==proc:fork==
 +
 +
{{Mark|Introduced with Version 9.0:}}
 +
 +
{| 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==
 
==proc:property==
 
{{Mark|Introduced with Version 8.3:}}
 
  
 
{| width='100%'
 
{| width='100%'
Line 70: Line 107:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the Java system property specified by {{Code|$name}}. 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].  
+
|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'''
 
| '''Examples'''
Line 78: Line 115:
  
 
==proc:property-names==
 
==proc:property-names==
 
{{Mark|Introduced with Version 8.3:}}
 
  
 
{| width='100%'
 
{| width='100%'
Line 87: Line 122:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the names of all Java system properties. 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].  
+
|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'''
 
| '''Examples'''
Line 95: Line 130:
  
 
=Errors=
 
=Errors=
 +
 +
{{Mark|Updated with Version 9.0:}}
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 100: Line 137:
 
|Description
 
|Description
 
|-
 
|-
|{{Code|BXPR9999}}
+
|{{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.
 
|The specified encoding does not exist or is not supported.
 +
|-
 +
|{{Code|timeout}}
 +
|The specified timeout was exceeded.
 
|}
 
|}
  
 
=Changelog=
 
=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
 
;Version 8.3
Line 111: Line 167:
  
 
The module was introduced with Version 7.3.
 
The module was introduced with Version 7.3.
 
[[Category:XQuery]]
 

Revision as of 12:06, 18 January 2018

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

Conventions

Template:Mark

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

Template:Mark new input option; revised error handling.

Signatures proc:system($cmd as xs:string) as xs:string
proc:system($cmd as xs:string, $args as xs:string*) as xs:string
proc:system($cmd as xs:string, $args as xs:string*, $options as map(xs:string, xs:string)) 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):
proc:system(
  'wc', (),
  map { 'input': 'A B' || out:nl() || 'C' }
)
  • The following example returns “Command not found” (unless xyz is a valid command on the system):
try {
  proc:system('xyz')
} catch proc:error {
  'Command not found: ' || $err:description
}

proc:execute

Signatures proc:execute($cmd as xs:string) as element(result)
proc:execute($cmd as xs:string, $args as xs:string*) as element(result)
proc:execute($cmd as xs:string, $args as xs:string*, $options as map(xs:string, xs:string)) 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:

<result>
  <output>...output...</output>
  <error>...error message...</error>
  <code>...process code...</code>
</result>
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

Template:Mark

Signatures proc:fork($cmd as xs:string) as element(result)
proc:fork($cmd as xs:string, $args as xs:string*) as element(result)
proc:fork($cmd as xs:string, $args as xs:string*, $options as map(xs:string, xs:string)) 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

Signatures 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
  • map:merge(proc:property-names() ! map:entry(., proc:property(.))) returns a map with all system properties.

proc:property-names

Signatures 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

Template:Mark

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

The module was introduced with Version 7.3.