Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
m
[[Category:XQuery]]
Text replacement - "syntaxhighlight" to "pre"
=Conventions=
All functions and errors in this module are assigned to the {{Code|<code><nowiki>http://basex.org/modules/proc}} </nowiki></code> namespace, which is statically bound to the {{Code|proc}} prefix.<br/>All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.
=Functions=
==proc:system==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|proc:system|$cmd as xs:string|xs:string}}<br/pre>{{Func|proc:system|( $cmd command as xs:string, $args arguments as xs:string*|xs :string}}<br/>{{Func|proc:system|$cmd as xs:string= (), $args options as xsmap(*)? :string*, $encoding = map { }) as xs:string|xs:string}}<br/pre>|-valign="top"
| '''Summary'''
|Executes a {{Code|$command}} with the specified command {{Code|$arguments}} in a separate process and returns the result as a string.<br/>Additional command arguments may be specified via The {{Code|$argsoptions}}.<br/>The result can be explicitly converted to a specified parameter contains process options:* {{Code|$encoding}}: convert result to the specified encoding. If no encoding is specifiedsupplied, the system’s default encoding is used.* {{Code|timeout}}: abort process execution after the specified number of seconds.* {{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'''
|{{Error|BXPRnnnnencoding|#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 command results in commands returns an errorexit code different to 0, an XQuery error will be raised. Its code will consist of the letters {{Code|BXPRcode}} and four digits with the command’s exit code.<br/>{{Error|BXPR9999|#Error}} the specified encoding does not exist or is not supported.|-valign="top"
| '''Examples'''
|
* {{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):<pre lang='xquery'>proc:system( 'wc', (), map { 'input': 'A B' || out:nl() || 'C' })</pre>* The following example returns "Command “Command not found", if found” (unless {{Code|xyz}} is a valid command on the command "xyz" cannot be located or executedsystem):<pre classlang="brush:'xquery"'>
try {
proc:system('xyz')
} catch bxerrproc:BXPR0002 error { 'Command not found.: '|| $err:description
}
</pre>
==proc:execute==
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|proc:execute|$cmd as xs:string|element(result)}}<br/pre>{{Func|proc:execute|( $cmd command as xs:string, $args arguments as xs:string*|element := (result)}}<br/>{{Func|proc:execute|$cmd as xs:string, $args options as xsmap(*)? :string*, $encoding = map { }) as xs:string|element(result)}}</pre>|-valign="top"
| '''Summary'''
|Executes a {{Code|$command}} with the specified command {{Code|$arguments}} in a separate process and returns the result as an element.<br/>Additional command arguments may be specified via :* The same {{Code|$argsoptions}} are allowed as for {{Function||proc:system}}.<br/>The result can * Instead of the {{Code|proc:error}} error, the error message and process code will be explicitly converted assigned to a specified the returned elements.* Instead of the {{Code|$encodingproc:code....}}. If no encoding is specifiederror, the system’s default encoding is usederror message will be assigned to the returned element (no process code will be returned).<br/>A The result has the following structure:<br/><pre classlang="brush:xml">
<result>
<output>...result output...</output> <error>...error outputmessage...</error> <code>0...process code...</code>
</result>
</pre>
|-valign="top"
|'''Errors'''
|{{Error|BXPR9999encoding|#Error}} the specified encoding does not exist or is not supported.<br/>{{Error|timeout|#Error}} the specified timeout was exceeded.|-valign="top"
| '''Examples'''
|
* {{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.
|}
==proc:fork==
{| width='100%'
|- valign="top"
| 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'''
|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'''
|{{Error|encoding|#Error}} the specified encoding does not exist or is not supported.
|- valign="top"
| '''Examples'''
|
* {{Code|proc:fork('sleep', '5')}}: sleep for 5 seconds (no one should notice).
|}
==proc:property==
{| width='100%'
|- valign="top"
| width='120' | '''Signature'''
|<pre>proc:property(
$name as xs:string
) as xs:string?</pre>
|- valign="top"
| '''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].
|- valign="top"
| '''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.
|}
==proc:property-names==
{| width='100%'
|- valign="top"
| width='120' | '''Signature'''
|<pre>proc:property-names() as xs:string*</pre>
|- valign="top"
| '''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].
|- valign="top"
| '''Examples'''
|
* {{Code|proc:property('java.runtime.version')}} returns the version of the Java runtime engine.
|}
! width="110"|Code
|Description
|-valign="top"|{{Code|BXPR9999code...}}|The result of a command call with an exit code different to 0.|- valign="top"|{{Code|code9999}}|A command could not be executed.|- valign="top"|{{Code|encoding}}
|The specified encoding does not exist or is not supported.
|- valign="top"
|{{Code|timeout}}
|The specified timeout was exceeded.
|}
=Changelog=
;Version 9.0
* Added: {{Function||proc:fork}}
* Updated: error codes; errors now use the module namespace
* Updated: new {{Code|input}} option; revised error handling
;Version 8.6
* Updated: {{Function||proc:system}}, {{Function||proc:exec}}: {{Code|encoding}} option moved to options argument, {{Code|timeout}} and {{Code|dir}} options added.
;Version 8.3
* Added: {{Function||proc:property}}, {{Function||proc:property-names}}.
The module was introduced with Version 7.3.
