Main Page » XQuery » Functions » Process Functions

Process Functions

This module provides functions for executing system commands from XQuery.

Conventions

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.

Execution

proc:system

Signature
proc:system(
  $command    as xs:string,
  $arguments  as xs:string*  := (),
  $options    as map(*)?     := {}
) as xs:string
SummaryExecutes a $command with the specified $arguments in a separate process and returns the result as a string. The following $options are available:
optiondefaultdescription
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
code....The result of a command call with an exit code different to 0.
encodingThe specified encoding does not exist or is not supported.
errorAn error occurred while executing a command.
timeoutThe specified timeout was exceeded.
Examples
proc:system('date')
returns the current date on a Linux system.
proc:system('wc', options := { 'input': 'A B' || char('\n') || 'C' })
Analyses the given input and counts the number of lines, words and characters (provided that wc is available on the system).
try {
  proc:system('xyz')
} catch proc:error {
  'Command not found: ' || $err:description
}
The example returns “Command not found” (unless xyz is a valid command on the system).

proc:execute

Signature
proc:execute(
  $command    as xs:string,
  $arguments  as xs:string*  := (),
  $options    as map(*)?     := {}
) as element(result)
SummaryExecutes 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).

A result element is returned with an output child element, a code child element with the process exit value, and an optional error child element.

Errors
encodingThe specified encoding does not exist or is not supported.
timeoutThe 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

Signature
proc:fork(
  $command    as xs:string,
  $arguments  as xs:string*  := (),
  $options    as map(*)?     := {}
) as element(result)
SummaryExecutes 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
encodingThe specified encoding does not exist or is not supported.
Examples
proc:fork('sleep', '5')
Sleep for 5 seconds (no one should notice).

Environment

The following functions return Java system properties as well as context parameters that are defined in the web.xml file (see Web Applications). For environment variables of the operating system, use fn:available-environment-variables.

proc:property-map

Signature
proc:property-map() as map(xs:string, xs:string)
SummaryReturns a map with all system properties.

proc:property-names

Added: New function.

Signature
proc:property-names() as xs:string*
SummaryReturns the names of all system properties.
Examples
map:merge(proc:property-names() ! map:entry(., proc:property(.)))
Returns a map with all system properties (equivalent to proc:property-map).

proc:property

Signature
proc:property(
  $name  as xs:string
) as xs:string?
SummaryReturns the value of a system property, specified by $name.
Examples
proc:property('java.class.path')
Returns the full user class path.
proc:property('java.runtime.version')
Returns the version of the Java runtime engine.

Errors

CodeDescription
code....The result of a command call with an exit code different to 0.
code9999A command could not be executed.
encodingThe specified encoding does not exist or is not supported.
errorAn error occurred while executing a command.
timeoutThe specified timeout was exceeded.

Changelog

Version 11.0Version 9.0
  • Added: proc:fork
  • Updated: error codes; errors now use the module namespace
  • Updated: new input option; revised error handling
Version 8.6Version 8.3Version 7.3
  • Added: New module added.

⚡Generated with XQuery