Difference between revisions of "Process Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replacement - "syntaxhighlight" to "pre")
 
(5 intermediate revisions by the same user not shown)
Line 11: Line 11:
 
{| width='100%'
 
{| width='100%'
 
|- valign="top"
 
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
 
|<pre>proc:system(
 
|<pre>proc:system(
−
   $cmd        as xs:string
+
   $command    as xs:string,
−
   $args      as xs:string*     := ()
+
   $arguments  as xs:string* := (),
−
   $options    as map(xs:string  := ()
+
   $options    as map(*)?    := map { }
−
  xs:string)  as                := ()
 
 
) as xs:string</pre>
 
) as xs:string</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''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:
+
|Executes a {{Code|$command}} with the specified {{Code|$arguments}} in a separate process and returns the result as a string. 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|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|timeout}}: abort process execution after the specified number of seconds.
Line 33: Line 32:
 
* {{Code|proc:system('date')}} returns the current date on a Linux system.
 
* {{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):
 
* Analyses the given input and counts the number of lines, words and characters (provided that {{Code|wc}} is available on the system):
−
<syntaxhighlight lang="xquery">
+
<pre lang='xquery'>
 
proc:system(
 
proc:system(
 
   'wc', (),
 
   'wc', (),
 
   map { 'input': 'A B' || out:nl() || 'C' }
 
   map { 'input': 'A B' || out:nl() || 'C' }
 
)
 
)
−
</syntaxhighlight>
+
</pre>
 
* The following example returns “Command not found” (unless {{Code|xyz}} is a valid command on the system):
 
* The following example returns “Command not found” (unless {{Code|xyz}} is a valid command on the system):
−
<syntaxhighlight lang="xquery">
+
<pre lang='xquery'>
 
try {
 
try {
 
   proc:system('xyz')
 
   proc:system('xyz')
Line 46: Line 45:
 
   'Command not found: ' || $err:description
 
   'Command not found: ' || $err:description
 
}
 
}
−
</syntaxhighlight>
+
</pre>
 
|}
 
|}
  
Line 53: Line 52:
 
{| width='100%'
 
{| width='100%'
 
|- valign="top"
 
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
 
|<pre>proc:execute(
 
|<pre>proc:execute(
−
   $cmd        as xs:string
+
   $command    as xs:string,
−
   $args      as xs:string*     := ()
+
   $arguments  as xs:string* := (),
−
   $options    as map(xs:string  := ()
+
   $options    as map(*)?    := map { }
−
  xs:string)  as                := ()
 
 
) as element(result)</pre>
 
) as element(result)</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Executes the specified command in a separate process and returns the result as element:
+
|Executes a {{Code|$command}} with the specified {{Code|$arguments}} in a separate process and returns the result as an 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 {{Function||proc:system}}.
 
* The same {{Code|$options}} are allowed as for {{Function||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: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).
 
* 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:
 
The result has the following structure:
−
<syntaxhighlight lang="xml">
+
<pre lang="xml">
 
<result>
 
<result>
 
   <output>...output...</output>
 
   <output>...output...</output>
Line 74: Line 71:
 
   <code>...process code...</code>
 
   <code>...process code...</code>
 
</result>
 
</result>
−
</syntaxhighlight>
+
</pre>
 
|- valign="top"
 
|- valign="top"
 
|'''Errors'''
 
|'''Errors'''
Line 89: Line 86:
 
{| width='100%'
 
{| width='100%'
 
|- valign="top"
 
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
 
|<pre>proc:fork(
 
|<pre>proc:fork(
−
   $cmd        as xs:string
+
   $command    as xs:string,
−
   $args      as xs:string*     := ()
+
   $arguments  as xs:string* := (),
−
   $options    as map(xs:string  := ()
+
   $options    as map(*)?    := map { }
−
  xs:string)  as                := ()
 
 
) as element(result)</pre>
 
) as element(result)</pre>
 
|- valign="top"
 
|- valign="top"
 
| '''Summary'''
 
| '''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 {{Function||proc:system}} (but the encoding will be ignored).
+
|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"
 
|- valign="top"
 
|'''Errors'''
 
|'''Errors'''
Line 112: Line 108:
 
{| width='100%'
 
{| width='100%'
 
|- valign="top"
 
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
 
|<pre>proc:property(
 
|<pre>proc:property(
 
   $name  as xs:string
 
   $name  as xs:string
Line 130: Line 126:
 
{| width='100%'
 
{| width='100%'
 
|- valign="top"
 
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
 
|<pre>proc:property-names() as xs:string*</pre>
 
|<pre>proc:property-names() as xs:string*</pre>
 
|- valign="top"
 
|- valign="top"

Latest revision as of 18:38, 1 December 2023

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

Conventions[edit]

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[edit]

proc:system[edit]

Signature 
proc:system(
  $command    as xs:string,
  $arguments  as xs:string*  := (),
  $options    as map(*)?     := map { }
) as xs:string
Summary Executes a $command with the specified $arguments in a separate process and returns the result as a string. 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[edit]

Signature 
proc:execute(
  $command    as xs:string,
  $arguments  as xs:string*  := (),
  $options    as map(*)?     := map { }
) as element(result)
Summary Executes a $command with the specified $arguments in a separate process and returns the result as an element:
  • 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[edit]

Signature 
proc:fork(
  $command    as xs:string,
  $arguments  as xs:string*  := (),
  $options    as map(*)?     := map { }
) as element(result)
Summary Executes a $command with the specified $arguments in a separate process and ignores the result. The same $options are allowed as for proc:system with the encoding being 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[edit]

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[edit]

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[edit]

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[edit]

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.

Retrieved from "http://docs.basex.org/index.php?title=Process_Module&oldid=16867"