Difference between revisions of "Process Module"
Jump to navigation
Jump to search
m (Text replacement - "\[\[#([^]:]+:[^|]+)\|([^]:]+:[^|]+)\]\]" to "{{Function||$1}}") |
|||
Line 10: | Line 10: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|proc:system|$cmd as xs:string|xs:string}}<br/>{{Func|proc:system|$cmd as xs:string, $args as xs:string*|xs:string}}<br/>{{Func|proc:system|$cmd as xs:string, $args as xs:string*, $options as map(xs:string, xs:string)|xs:string}}<br/> | |{{Func|proc:system|$cmd as xs:string|xs:string}}<br/>{{Func|proc:system|$cmd as xs:string, $args as xs:string*|xs:string}}<br/>{{Func|proc:system|$cmd as xs:string, $args as xs:string*, $options as map(xs:string, xs:string)|xs:string}}<br/> | ||
− | |- | + | |- 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 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: | ||
Line 20: | Line 20: | ||
* {{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. | * {{Code|input}}: standard string input ({{Code|stdin}}) to be passed on to the command. | ||
− | |- | + | |- 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.<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/> | |{{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''' | ||
| | | | ||
Line 47: | Line 47: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|proc:execute|$cmd as xs:string|element(result)}}<br/>{{Func|proc:execute|$cmd as xs:string, $args as xs:string*|element(result)}}<br/>{{Func|proc:execute|$cmd as xs:string, $args as xs:string*, $options as map(xs:string, xs:string)|element(result)}} | |{{Func|proc:execute|$cmd as xs:string|element(result)}}<br/>{{Func|proc:execute|$cmd as xs:string, $args as xs:string*|element(result)}}<br/>{{Func|proc:execute|$cmd as xs:string, $args as xs:string*, $options as map(xs:string, xs:string)|element(result)}} | ||
− | |- | + | |- valign="top" |
| '''Summary''' | | '''Summary''' | ||
|Executes the specified command in a separate process and returns the result as element: | |Executes the specified command in a separate process and returns the result as element: | ||
Line 65: | Line 65: | ||
</result> | </result> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | |- | + | |- 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 78: | Line 78: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|proc:fork|$cmd as xs:string|element(result)}}<br/>{{Func|proc:fork|$cmd as xs:string, $args as xs:string*|element(result)}}<br/>{{Func|proc:fork|$cmd as xs:string, $args as xs:string*, $options as map(xs:string, xs:string)|element(result)}} | |{{Func|proc:fork|$cmd as xs:string|element(result)}}<br/>{{Func|proc:fork|$cmd as xs:string, $args as xs:string*|element(result)}}<br/>{{Func|proc:fork|$cmd as xs:string, $args as xs:string*, $options as map(xs:string, xs:string)|element(result)}} | ||
− | |- | + | |- 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 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). | ||
− | |- | + | |- 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 96: | Line 96: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|proc:property|$name as xs:string|xs:string?}}<br/> | |{{Func|proc:property|$name as xs:string|xs:string?}}<br/> | ||
− | |- | + | |- 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''' | ||
| | | | ||
Line 112: | Line 112: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|proc:property-names||xs:string*}}<br/> | |{{Func|proc:property-names||xs:string*}}<br/> | ||
− | |- | + | |- 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 129: | Line 129: | ||
! 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. |
Revision as of 14:19, 20 July 2022
This XQuery Module provides functions for executing system commands from XQuery.
Contents
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.
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:
|
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 |
<syntaxhighlight lang="xquery"> proc:system( 'wc', (), map { 'input': 'A B' || out:nl() || 'C' } ) </syntaxhighlight>
<syntaxhighlight lang="xquery"> try { proc:system('xyz') } catch proc:error { 'Command not found: ' || $err:description } </syntaxhighlight> |
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:
The result has the following structure: <syntaxhighlight lang="xml"> <result> <output>...output...</output>
<error>...error message...</error>
</result> </syntaxhighlight> |
Errors | encoding : the specified encoding does not exist or is not supported.timeout : the specified timeout was exceeded.
|
Examples |
|
proc:fork
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: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 |
|
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 |
|
Errors
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
- 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.