Difference between revisions of "Process Module"

From BaseX Documentation
Jump to navigation Jump to search
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=
Line 22: Line 23:
 
|-
 
|-
 
|'''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|code....|#Error}} If the command results in an error, an XQuery error will be raised. Its code will consist of the letters {{Code|code}} and four digits with the command’s exit code.<br/>{{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 56: Line 57:
 
|-
 
|-
 
|'''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 77: Line 78:
 
|-
 
|-
 
|'''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.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 115: Line 116:
  
 
=Errors=
 
=Errors=
 +
 +
{{Mark|Updated with Version 9.0}}:
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 120: Line 123:
 
|Description
 
|Description
 
|-
 
|-
|{{Code|BXPR9999}}
+
|{{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.
 
|}
 
|}
  
Line 129: Line 135:
  
 
* Added: [[#proc:fork|proc:fork]]
 
* Added: [[#proc:fork|proc:fork]]
 +
* Updated: error codes updates; errors now use the module namespace
  
 
;Version 8.6
 
;Version 8.6

Revision as of 12:58, 21 November 2017

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

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.
Errors code....: If the command results in an error, an XQuery error will be raised. Its code will consist of the letters code and four digits with the command’s exit code.
encoding: the specified encoding does not exist or is not supported.
timeout: the specified timeout was exceeded.
Examples
  • 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:
try {
  proc:system('xyz')
} catch bxerr:BXPR0002 {
  'Command not found.'
}

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.

A result has the following structure:

<result>
  <output>...result output...</output>
  <error>...error output...</error>
  <code>0</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
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 updates; errors now use the module namespace
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.