Difference between revisions of "Process Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replace - "assigned to the \{\{Code\|([^}]*)\}\} namespace" to "assigned to the <code><nowiki>$1</nowiki></code> namespace")
Line 9: Line 9:
  
 
==proc:system==
 
==proc:system==
 +
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
Line 34: Line 35:
  
 
==proc:execute==
 
==proc:execute==
 +
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
Line 56: Line 58:
 
* {{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:property-names==
 +
 +
{{Mark|Introduced with Version 8.3:}}
 +
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|proc:property-names||xs:string*}}<br/>
 +
|-
 +
| '''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].
 +
|-
 +
| '''Examples'''
 +
|
 +
* {{Code|proc:property('java.runtime.version')}} returns the version of the Java runtime engine.
 +
|}
 +
 +
==proc:property==
 +
 +
{{Mark|Introduced with Version 8.3:}}
 +
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|proc:property|$name as xs:string|xs:string?}}<br/>
 +
|-
 +
| '''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].
 +
|-
 +
| '''Examples'''
 +
|
 +
* {{Code|map:merge(proc:property-names() ! map:entry(., proc:property(.)))}} returns a map with all system properties.
 
|}
 
|}
  
Line 69: Line 105:
  
 
=Changelog=
 
=Changelog=
 +
 +
;Version 8.3
 +
 +
* Added: [[#proc:property|proc:property]], [[#proc:property-names|proc:property-names]].
  
 
The module was introduced with Version 7.3.
 
The module was introduced with Version 7.3.
  
 
[[Category:XQuery]]
 
[[Category:XQuery]]

Revision as of 12:05, 21 September 2015

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

Conventions

All functions in this module are assigned to the http://basex.org/modules/proc namespace, which is statically bound to the proc prefix.
All errors are assigned to the http://basex.org/errors namespace, which is statically bound to the bxerr 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*, $encoding as 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 result can be explicitly converted to a specified $encoding. If no encoding is specified, the system’s default encoding is used.
Errors BXPRnnnn: If the command results in an error, an XQuery error will be raised. Its code will consist of the letters BXPR and four digits with the command’s exit code.
BXPR9999: the specified encoding does not exist or is not supported.
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*, $encoding as 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. Arguments to the command may be specified via $args.
The result can be explicitly converted to a specified $encoding. If no encoding is specified, the system’s default encoding is used.
A result has the following structure:
<result>
  <output>...result output...</output>
  <error>...error output...</error>
  <code>0</code>
</result>
Errors BXPR9999: the specified encoding does not exist or is not supported.
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:property-names

Template:Mark

Signatures proc:property-names() as xs:string*
Summary Returns the names of all Java system properties. 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.

proc:property

Template:Mark

Signatures proc:property($name as xs:string) as xs:string?
Summary Returns the Java system property specified by $name. 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.

Errors

Code Description
BXPR9999 The specified encoding does not exist or is not supported.

Changelog

Version 8.3

The module was introduced with Version 7.3.

Retrieved from "https://old.docs.basex.org/index.php?title=Process_Module&oldid=11997"