Difference between revisions of "Process Module"
Jump to navigation
Jump to search
m (Text replacement - "syntaxhighlight" to "pre") |
|||
(13 intermediate revisions by the same user not shown) | |||
Line 2: | Line 2: | ||
=Conventions= | =Conventions= | ||
− | |||
− | |||
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/> | 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/> | ||
Line 12: | Line 10: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>proc:system( |
− | |- | + | $command as xs:string, |
+ | $arguments as xs:string* := (), | ||
+ | $options as map(*)? := map { } | ||
+ | ) as xs:string</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Executes | + | |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. | ||
* {{Code|dir}}: process command in the specified directory. | * {{Code|dir}}: process command in the specified directory. | ||
− | |- | + | * {{Code|input}}: standard string input ({{Code|stdin}}) to be passed on to the command. |
+ | |- valign="top" | ||
|'''Errors''' | |'''Errors''' | ||
− | |{{Error|code....|#Error}} If the commands returns an exit code different to 0, an | + | |{{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/> |
− | |- | + | |- valign="top" |
| '''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 | + | * Analyses the given input and counts the number of lines, words and characters (provided that {{Code|wc}} is available on the system): |
− | <pre | + | <pre lang='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 lang='xquery'> | ||
try { | try { | ||
proc:system('xyz') | proc:system('xyz') | ||
− | } catch proc: | + | } catch proc:error { |
− | 'Command not found | + | 'Command not found: ' || $err:description |
} | } | ||
</pre> | </pre> | ||
Line 41: | Line 51: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>proc:execute( |
− | |- | + | $command as xs:string, |
+ | $arguments as xs:string* := (), | ||
+ | $options as map(*)? := map { } | ||
+ | ) as element(result)</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Executes | + | |Executes a {{Code|$command}} with the specified {{Code|$arguments}} in a separate process and returns the result as an element: |
− | + | * The same {{Code|$options}} are allowed as for {{Function||proc:system}}. | |
− | <pre | + | * 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 lang="xml"> | ||
<result> | <result> | ||
− | <output>... | + | <output>...output...</output> |
− | <error>...error | + | <error>...error message...</error> |
− | <code> | + | <code>...process code...</code> |
</result> | </result> | ||
</pre> | </pre> | ||
− | |- | + | |- valign="top" |
|'''Errors''' | |'''Errors''' | ||
|{{Error|encoding|#Error}} the specified encoding does not exist or is not supported.<br/>{{Error|timeout|#Error}} the specified timeout was exceeded. | |{{Error|encoding|#Error}} the specified encoding does not exist or is not supported.<br/>{{Error|timeout|#Error}} the specified timeout was exceeded. | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 66: | Line 83: | ||
==proc:fork== | ==proc:fork== | ||
− | |||
− | |||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>proc:fork( |
− | |- | + | $command as xs:string, |
+ | $arguments as xs:string* := (), | ||
+ | $options as map(*)? := map { } | ||
+ | ) as element(result)</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Executes | + | |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" |
|'''Errors''' | |'''Errors''' | ||
|{{Error|encoding|#Error}} the specified encoding does not exist or is not supported. | |{{Error|encoding|#Error}} the specified encoding does not exist or is not supported. | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 88: | Line 107: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>proc:property( |
− | |- | + | $name as xs:string |
+ | ) as xs:string?</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
|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]. | |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]. | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
+ | * {{Code|proc:property('java.class.path')}} returns the full user class path. | ||
* {{Code|map:merge(proc:property-names() ! map:entry(., proc:property(.)))}} returns a map with all system properties. | * {{Code|map:merge(proc:property-names() ! map:entry(., proc:property(.)))}} returns a map with all system properties. | ||
|} | |} | ||
Line 103: | Line 125: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>proc:property-names() as xs:string*</pre> |
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|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]. | |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]. | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 116: | Line 138: | ||
=Errors= | =Errors= | ||
− | |||
− | |||
{| class="wikitable" width="100%" | {| class="wikitable" width="100%" | ||
! width="110"|Code | ! width="110"|Code | ||
|Description | |Description | ||
− | |- | + | |- valign="top" |
|{{Code|code...}} | |{{Code|code...}} | ||
|The result of a command call with an exit code different to 0. | |The result of a command call with an exit code different to 0. | ||
− | |- | + | |- valign="top" |
|{{Code|code9999}} | |{{Code|code9999}} | ||
|A command could not be executed. | |A command could not be executed. | ||
− | |- | + | |- valign="top" |
|{{Code|encoding}} | |{{Code|encoding}} | ||
|The specified encoding does not exist or is not supported. | |The specified encoding does not exist or is not supported. | ||
− | |- | + | |- valign="top" |
|{{Code|timeout}} | |{{Code|timeout}} | ||
|The specified timeout was exceeded. | |The specified timeout was exceeded. | ||
Line 140: | Line 160: | ||
;Version 9.0 | ;Version 9.0 | ||
− | * Added: | + | * Added: {{Function||proc:fork}} |
− | * Updated: error codes | + | * Updated: error codes; errors now use the module namespace |
+ | * Updated: new {{Code|input}} option; revised error handling | ||
;Version 8.6 | ;Version 8.6 | ||
− | * Updated: | + | * Updated: {{Function||proc:system}}, {{Function||proc:exec}}: {{Code|encoding}} option moved to options argument, {{Code|timeout}} and {{Code|dir}} options added. |
;Version 8.3 | ;Version 8.3 | ||
− | * Added: | + | * Added: {{Function||proc:property}}, {{Function||proc:property-names}}. |
The module was introduced with Version 7.3. | The module was introduced with Version 7.3. |
Latest revision as of 18:38, 1 December 2023
This XQuery Module provides functions for executing system commands from XQuery.
Contents
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:
|
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(
'wc', (),
map { 'input': 'A B' || out:nl() || 'C' }
)
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 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: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: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-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 |
|
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
anddir
options added.
- Version 8.3
- Added:
proc:property
,proc:property-names
.
The module was introduced with Version 7.3.