Difference between revisions of "Command-Line Options"

From BaseX Documentation
Jump to navigation Jump to search
m (Q in Expanded QName)
 
(291 intermediate revisions by 10 users not shown)
Line 1: Line 1:
This page gives an overview on all command-line options of the BaseX [[Startup Overview|Startup]] scripts:
+
This article is part of the [[Getting Started]] Guide.
 +
Each BaseX [[Startup]] mode has one or more command-line options, which are described in this article.
  
==BaseX Server==
+
Command-line options can be specified multiple times. Please note that all options will be evaluated in the given order. The standard input can be parsed by specifying a single dash ({{Code|-}}) as an argument.
 +
 
 +
{{Announce|Updated with Version 11}}: The Clark notation was replaced with the [[XQuery 3.0#Expanded QNames|Expanded QNames]] notation.
 +
 
 +
=Standalone=
 +
 
 +
{{Announce|Added with Version 11:}} {{Code|-C}}, {{Code|-Q}}, {{Code|-W}}
 +
 
 +
The following options are available for the standalone [[Command-Line Client]]:
 +
 
 +
<pre>
 +
$ basex -h
 +
BaseX [Standalone]
 +
Usage: basex [-bcdiIoqrRstuvVwxz] [input]
 +
  [input]    XQuery or command file, or query string
 +
  -b<args>  Bind external query variables
 +
  -c<input>  Execute commands from file or string
 +
  -C<file>  Execute command script file
 +
  -d        Toggle debugging output
 +
  -i<input>  Bind file or database to context
 +
  -I<input>  Bind input string to context
 +
  -o<path>  Write output to local file
 +
  -q<expr>  Execute XQuery expression
 +
  -Q<file>  Execute XQuery file
 +
  -r<num>    Run query multiple times
 +
  -R        Toggle query execution
 +
  -s<args>  Set serialization parameters
 +
  -t[path]  Run tests in file or directory
 +
  -u        Toggle updates in original files
 +
  -v        Toggle output of progress info
 +
  -V        Toggle detailed query output
 +
  -w        Toggle whitespace stripping
 +
  -W        Enable indentation with whitespaces
 +
  -x        Toggle output of query plan
 +
  -z        Toggle output of query result
 +
</pre>
 +
 
 +
Further details are listed in the following table. If an equivalent database option exists (which can be specified via the {{Command|SET}} command), it is listed as well.
 +
For the examples to work, it might be necessary to escape some characters depending on your operating system.
 +
 
 +
{| class="wikitable"
 +
|- valign="top"
 +
! width='120' | Flag
 +
! width="40%" | Description
 +
! Option
 +
! Default
 +
! Examples
 +
|- valign="top"
 +
| {{Code|[input]}}
 +
|Evaluates the specified input:
 +
* The input string may point to an existing file. If the file suffix is {{Code|.bxs}}, the file contents will be executed as [[Commands#Basics|Command Script]]; any other file content will be evaluated as XQuery expression.
 +
* Otherwise, the input string itself is evaluated as XQuery expression.
 +
|
 +
|
 +
|• {{Code|"doc('X')//head"}}<br/>• {{Code|query.xq}}<br/>• {{Code|commands.bxs}}<br/>
 +
|- valign="top"
 +
| {{Code|-b&lt;args&gt;}}
 +
| Binds external variables to XQuery expressions. This flag may be specified multiple times. Variables names and their values are delimited by equality signs (<code>=</code>). The names may be optionally prefixed with dollar signs. If a variable uses a namespace different from the default namespace, it can be specified with the [[XQuery 3.0#Expanded QNames|Expanded QNames]] notation.
 +
| {{Option|BINDINGS}}
 +
|
 +
|• <code>-bv=example "declare variable $v external; $v"</code><br/>• <code>-bQ{URL}ln=value<br/>"declare namespace ns='URL'; declare variable $ns:ln external; $ns:ln"</code>
 +
|- valign="top"
 +
| {{Code|-c&lt;input&gt;}}
 +
| Executes [[commands]]. If the specified input is a valid URI or file reference, this file is evaluated as [[Commands#Command_Scripts|Command Script]].
 +
|
 +
|
 +
|• {{Code|-c list}}<br/>• {{Code|-ccommands.txt}}<br/>• {{Code|-c"<info/>"}}
 +
|- valign="top"
 +
| {{Code|-C&lt;file&gt;}}
 +
| Evaluates the contents of the specified file as [[Commands#Command_Scripts|Command Script]].
 +
|
 +
|
 +
|
 +
|- valign="top"
 +
| {{Code|-d}}
 +
| Toggles the debugging mode. Debugging information is output to ''standard error''.
 +
| {{Option|DEBUG}}
 +
| <code>false</code>
 +
|
 +
|- valign="top"
 +
| {{Code|-i&lt;input&gt;}}
 +
| Opens the specified XML file, directory with XML files, or database. The opened input can then be processed by a command or XQuery expression.
 +
|
 +
|
 +
| {{Code|-iitems.xml "//item"}}
 +
|- valign="top"
 +
| {{Code|-I&lt;input&gt;}}
 +
| Assigns an input string as item of type {{Code|xs:untypedAtomic}} to the query context.
 +
|
 +
|
 +
| {{Code|-I "Hello Universe" -q "."}}
 +
|- valign="top"
 +
| {{Code|-o&lt;path&gt;}}
 +
| All command and query output is written to the specified file.
 +
|
 +
|
 +
| {{Code|-o output.txt}}
 +
|- valign="top"
 +
| {{Code|-q&lt;expr&gt;}}
 +
| Evaluates the specified string as XQuery expression.
 +
|
 +
|
 +
| {{Code|-q"doc('input')//head"}}
 +
|- valign="top"
 +
| {{Code|-Q&lt;file&gt;}}
 +
| Evaluates the contents of the specified file as XQuery expression.
 +
|
 +
|
 +
|
 +
|- valign="top"
 +
| {{Code|-r&lt;num&gt;}}
 +
| Specifies how often a specified query will be evaluated.
 +
| {{Option|RUNS}}
 +
| <code>1</code>
 +
| {{Code|-V -r10 "1"}}
 +
|- valign="top"
 +
| {{Code|-R}}
 +
| Specifies if a query will be evaluated or parsed and compiled only.
 +
| {{Option|RUNQUERY}}
 +
| <code>true</code>
 +
| {{Code|-V -R "1"}}
 +
|- valign="top"
 +
| {{Code|-s&lt;args&gt;}}
 +
| Specifies parameters for serializing XQuery results; see [[Serialization]] for more details. This flag may be specified multiple times. Key and values are separated by the equality sign (<code>=</code>).
 +
| {{Option|SERIALIZER}}
 +
|
 +
| <code>-smethod=text</code>
 +
|- valign="top"
 +
| {{Code|-t[path]}}
 +
| Runs all [[Unit Module|Unit tests]] in the specified file or directory.
 +
|
 +
|
 +
| -t project/tests
 +
|- valign="top"
 +
| {{Code|-u}}
 +
| Propagates updates on input files back to disk.
 +
| {{Option|WRITEBACK}}
 +
| <code>false</code>
 +
|
 +
|- valign="top"
 +
| {{Code|-v}}
 +
| Toggles the output of process and timing information.
 +
|
 +
| <code>false</code>
 +
|
 +
|- valign="top"
 +
| {{Code|-V}}
 +
| Prints detailed query information to the ''standard output'', including details on the compilation and profiling steps.
 +
| {{Option|QUERYINFO}}
 +
| <code>false</code>
 +
|
 +
|- valign="top"
 +
| {{Code|-w}}
 +
| Toggles whitespace stripping of XML text nodes. By default, whitespaces will be preserved.
 +
| {{Option|STRIPWS}}
 +
| <code>false</code>
 +
|
 +
|- valign="top"
 +
| {{Code|-W}}
 +
| Enables indentation with whitespace. By default, query results will not be indented.
 +
| {{Option|SERIALIZER}}
 +
| <code>indent=no</code>
 +
|
 +
|- valign="top"
 +
| {{Code|-x}}
 +
| Toggles the output of the query execution plan, formatted as XML.
 +
| {{Option|XMLPLAN}}
 +
| <code>false</code>
 +
|
 +
|- valign="top"
 +
| {{Code|-z}}
 +
| Turns the serialization of XQuery results on/off. This flag is useful if the query is profiled or analyzed.
 +
| {{Option|SERIALIZE}}
 +
| <code>true</code>
 +
|
 +
|}
 +
 
 +
=GUI=
 +
 
 +
The following options are available for the standalone [[GUI|Graphical User Interface]]:
  
;Launch the server
 
 
<pre>
 
<pre>
> basexserver
+
$ basexgui -h
BaseX [Server]
+
BaseX [GUI]
Server was started.
+
Usage: basexgui [-d] [files]
 +
  [files]  Open specified files
 +
  -d  Enable debugging
 
</pre>
 
</pre>
  
Available command-line options can be listed with the <code>-h</code> flag:
+
You can pass one or more files as parameters. If an XML document is specified, a database instance can be created from this file. Other files are opened in the editor.
 +
 
 +
=Server=
 +
 
 +
{{Announce|Added with Version 11:}} {{Code|-C}}
 +
 
 +
The following options are available for the [[Database Server]]:
 +
 
 
<pre>
 
<pre>
> basexserver -h
+
$ basexserver -h
Usage: BaseXServer [-dpsz] [-c] [stop]
+
BaseX [Server]
   stop     Stop existing server
+
Usage: basexserver [-cdnpSz] [stop]
   -c<cmd>  Execute initial database command(s)
+
   stop       Stop running server
   -d       Activate debugging mode
+
   -c<input>  Execute commands from file or string
   -i      Enter interactive mode
+
  -C<file>  Execute command script file
   -p<num> Set server port
+
   -d         Enable debugging output
   -s      Start as service
+
   -n<name>  Set host the server is bound to
   -z       Suppress logging
+
   -p<port>   Set server port
 +
   -S        Start as service
 +
   -z         Suppress logging
 
</pre>
 
</pre>
  
The options have the following meaning:
+
Details on all options are listed in the following table (equivalent database options are shown in the table as well).
 +
For the examples to work, it might be necessary to escape some characters depending on your operating system.
  
{| class="wikitable"  
+
{| class="wikitable"
 
|- valign="top"
 
|- valign="top"
! width='60' | Flag
+
! width='120' | Flag
! Description
+
! width="40%" | Description
! width='165' | Examples
+
! Option
 +
! Default
 +
! Examples
 
|- valign="top"
 
|- valign="top"
| <code>stop</code>
+
| {{Code|stop}}
| Stop an existing server instance; remaining input is ignored.
+
| Stops a local database server instance and quits.
 +
|
 
|
 
|
 
|- valign="top"
 
|- valign="top"
| <code>-c&lt;cmd&gt;</code>
+
| {{Code|-c&lt;input&gt;}}
| Launch database commands before the server itself is started; all remaining text is interpreted as command input. Several commands can be separated by semicolons.
+
| Executes [[commands]]. If the specified input is a valid URI or file reference, this file is evaluated as [[Commands#Command_Scripts|Command Script]].
| <code>-c"open database;info"</code>
+
|
 +
|
 +
| {{Code|-c"open database;info"}}
 +
|- valign="top"
 +
| {{Code|-C&lt;file&gt;}}
 +
| Evaluates the contents of the specified file as [[Commands#Command_Scripts|Command Script]].
 +
|
 +
|
 +
|
 
|- valign="top"
 
|- valign="top"
| <code>-d</code>
+
| {{Code|-d}}
| Turn on debugging. Debugging information is output to ''standard error''.
+
| Enables debugging output. Debugging information is output to ''standard error''.
 +
| {{Option|DEBUG}}
 +
| <code>false</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
| <code>-i</code>
+
| {{Code|-n&lt;name&gt;}}
| Interactively enter commands on the console, similar to standalone and client mode.
+
| Specifies the host the server will be bound to.
 +
| {{Option|SERVERHOST}}
 
|
 
|
 +
| {{Code|-p127.0.0.1}}
 
|- valign="top"
 
|- valign="top"
| <code>-p&lt;num&gt;</code>
+
| {{Code|-p&lt;port&gt;}}
| Specify the port on which the server will be addressable. The default port is '''1984'''.
+
| Specifies the port on which the server will be addressable.
| <code>-p9999</code>
+
| {{Option|SERVERPORT}}
 +
| {{Code|1984}}
 +
| {{Code|-p9999}}
 
|- valign="top"
 
|- valign="top"
| <code>-s</code>
+
| {{Code|-S}}
| Start the server as service (i.e., in background).
+
| Starts the server as service (i.e., in the background). Use [[YAJSW]], or start BaseX as an ordinary background process to get more options.
|  
+
|
 +
|
 
|- valign="top"
 
|- valign="top"
| <code>-z</code>
+
| {{Code|-z}}
| Do not generate [[Logging|log files]].
+
| Prevents the generation of [[Logging|log files]].
|  
+
| {{Option|LOG}}
 +
| <code>true</code>
 +
|
 
|}
 
|}
  
==BaseX Client==
+
Multiple {{Code|-c}} and {{Code|-i}} flags can be specified. All other options will be set before any other operation takes place. The specified inputs, query files, queries and commands will be subsequently evaluated after that in the given order. The standard input can be parsed by specifying a single dash ({{Code|-}}) as argument.
 +
 
 +
=Client=
 +
 
 +
{{Announce|Added with Version 11:}} {{Code|-C}}, {{Code|-Q}}, {{Code|-W}}
  
;Launch interactive mode
+
If the [[Database Server|Database Client]] is launched, you will be requested for a username and password.
  
The user name and password will be requested. The default user/password combination is '''admin'''/'''admin''':
 
 
<pre>
 
<pre>
> basexclient
+
$ basexclient -h
Username: admin
 
Password: *****
 
 
BaseX [Client]
 
BaseX [Client]
Try "help" to get more information.
+
Usage: basexclient [-bcdiInopPqrRsUvVwxz] [input]
&gt; _
+
  [input]   XQuery or command file, or query string
</pre>
+
  -b<args>  Bind external query variables
 
+
   -c<input>  Execute commands from file or string
Available command-line options can be listed with the <code>-h</code> flag:
+
   -C<file>   Execute command script file
<pre>
+
   -d        Toggle debugging output
> basexclient -h
+
  -i<input>  Bind file or database to context
Usage: BaseXClient [-npPU] [-dovVwz] [-cq] [file]
+
  -I<input>  Bind input string to context
   [file]    Execute XQuery file
 
   -c<cmd>   Execute database command(s)
 
   -d        Activate debugging mode
 
 
   -n<name>  Set server (host) name
 
   -n<name>  Set server (host) name
   -o<file>  Write output to file
+
   -o<path>  Write output to local file
   -p<num>   Set server port
+
   -p<port>   Set server port
 
   -P<pass>  Specify user password
 
   -P<pass>  Specify user password
 
   -q<expr>  Execute XQuery expression
 
   -q<expr>  Execute XQuery expression
   -U<name>  Specify user name
+
  -Q<file>  Execute XQuery file
   -v/V       Show (all) process info
+
  -r<num>    Run query multiple times
   -w        Retain whitespaces from source files
+
  -R        Toggle query execution
   -z        Skip XQuery serialization
+
  -s<args>  Set serialization parameters
 +
   -U<name>  Specify username
 +
   -v         Toggle output of progress info
 +
  -V         Toggle detailed query output
 +
   -w        Toggle whitespace stripping
 +
  -W        Enable indentation with whitespaces
 +
  -x        Toggle output of query plan
 +
   -z        Toggle output of query result
 
</pre>
 
</pre>
  
The options have the following meaning:
+
See the following table for details (equivalent database options are shown in the table as well).
 +
For the examples to work, it might be necessary to escape some characters, depending on your operating system.
  
{| class="wikitable"  
+
{| class="wikitable"
 
|- valign="top"
 
|- valign="top"
! width='70' | Flag
+
! width='120' | Flag
! Description
+
! width="40%" | Description
 +
! Option
 
! Default
 
! Default
! width='165' | Examples
+
! Examples
 
|- valign="top"
 
|- valign="top"
| <code>[file]</code>
+
| {{Code|[input]}}
| Execute the specified XQuery file.
+
|Evaluates the specified input:
 +
* The input string may point to an existing file. If the file suffix is {{Code|.bxs}}, the file contents will be evaluated as [[Commands#Basics|Command Script]]; any other file content will be evaluated as XQuery expression.
 +
* Otherwise, the input string itself is evaluated as XQuery expression.
 
|
 
|
 
|
 
|
 +
|• {{Code|"doc('X')//head"}}<br/>• {{Code|query.xq}}<br/>• {{Code|commands.bxs}}<br/>
 +
|- valign="top"
 +
| {{Code|-b&lt;args&gt;}}
 +
| Binds external variables to XQuery expressions. This flag may be specified multiple times. Variables names and their values are delimited by equality signs (<code>=</code>). The names may be optionally prefixed with dollar signs. If a variable uses a namespace different from the default namespace, it can be specified with the [[XQuery 3.0#Expanded QNames|Expanded QNames]] notation.
 +
| {{Option|BINDINGS}}
 +
|
 +
|• <code>-b$v=example "declare variable $v external; $v"</code><br/>• <code>-bQ{URL}ln=value<br/>"declare namespace ns='URL'; declare variable $ns:ln external; $ns:ln"</code>
 
|- valign="top"
 
|- valign="top"
| <code>-c&lt;cmd&gt;</code>
+
| {{Code|-c&lt;input&gt;}}
| Launch database commands and skip interactive mode. The flag should be placed last, all remaining characters are interpreted as commands. Several commands can be separated by semicolons.
+
| Executes [[commands]]. If the specified input is a valid URI or file reference, its content will be executed instead. Empty lines and lines starting with the number sign {{Code|#}} will be ignored.
 +
|
 
|
 
|
| <code>-c"list;info"</code>
+
|• {{Code|-c list}}<br/>• {{Code|-ccommands.txt}}<br/>• {{Code|-c"<info/>"}}
 
|- valign="top"
 
|- valign="top"
| <code>-d</code>
+
| {{Code|-C&lt;file&gt;}}
| Turn on debugging. Debugging information is output to ''standard error''.
+
| Evaluates the contents of the specified file as [[Commands#Command_Scripts|Command Script]].
 +
|
 
|
 
|
 
|
 
|
 
|- valign="top"
 
|- valign="top"
| <code>-n&lt;name&gt;</code>
+
| {{Code|-d}}
| Specify the server name on which the server is running.
+
| Toggles the debugging mode. Debugging information is output to ''standard error''.
| <code>localhost</code>
+
| {{Option|DEBUG}}
| <code>-nserver.basex.org</code>
+
| <code>false</code>
 +
|
 
|- valign="top"
 
|- valign="top"
| <code>-o&lt;file&gt;</code>
+
| {{Code|-i&lt;input&gt;}}
| Command and query output is written to the specified file.
+
| Opens the specified XML file, directory with XML files, or database. The opened input can then be processed by a command or XQuery expression.
 
|
 
|
 
|
 
|
 +
| {{Code|-iitems.xml "//item"}}
 
|- valign="top"
 
|- valign="top"
| <code>-p&lt;num&gt;</code>
+
| {{Code|-I&lt;input&gt;}}
| Specify the port on which the server is running.
+
| Assigns an input string as item of type {{Code|xs:untypedAtomic}} to the query context.
| <code>1984</code>
+
|
| <code>-p9999</code>
+
|
 +
| {{Code|-I "Hello Universe" -q "."}}
 
|- valign="top"
 
|- valign="top"
| <code>-P&lt;pass&gt;</code>
+
| {{Code|-n&lt;name&gt;}}
| Specify the user password. ''Warning'': when the password is specified on command-line, it may be visible to others.
+
| Specifies the host name on which the server is running.
 +
| {{Option|HOST}}
 +
| {{Code|localhost}}
 +
| {{Code|-nserver.basex.org}}
 +
|- valign="top"
 +
| {{Code|-o&lt;path&gt;}}
 +
| All command and query output is written to the specified file.
 +
|
 +
|
 
|
 
|
| <code>-Uadmin -Padmin</code>
 
 
|- valign="top"
 
|- valign="top"
| <code>-q&lt;expr&gt;</code>
+
| {{Code|-p&lt;port&gt;}}
| Execute the specified string as XQuery expression. The flag should be placed last, as all remaining characters are interpreted as XQuery.
+
| Specifies the port on which the server is running.
 +
| {{Option|PORT}}
 +
| {{Code|1984}}
 +
| {{Code|-p9999}}
 +
|- valign="top"
 +
| {{Code|-P&lt;pass&gt;}}
 +
| Specifies the user password. If this flag is omitted, the password will be requested on command line. ''Warning'': When the password is supplied with this flag, it may end up in logs or the bash history.
 +
| {{Option|PASSWORD}}
 
|
 
|
| <code>-q"doc('input')//head"</code>
+
| {{Code|-Uadmin -P...}}
 
|- valign="top"
 
|- valign="top"
| <code>-U&lt;name&gt;</code>
+
| {{Code|-q&lt;expr&gt;}}
| Specify the user name.
+
| Executes the specified string as XQuery expression.
 
|
 
|
| <code>-Uadmin</code>
+
| {{Code|-q"1+2"}}
 
|- valign="top"
 
|- valign="top"
| <code>-v</code>
+
| {{Code|-Q&lt;file&gt;}}
| Process information is written to standard output (<code>STDOUT</code>).
+
| Evaluates the contents of the specified file as XQuery expression.
 +
|
 
|
 
|
 
|
 
|
 
|- valign="top"
 
|- valign="top"
| <code>-V</code>
+
| {{Code|-r&lt;num&gt;}}
| Detailed query information is written to ''standard output'', including compilation and profiling steps.
+
| Specifies how often a specified query will be evaluated.
 +
| {{Option|RUNS}}
 +
| <code>1</code>
 +
| {{Code|-V -r10 "1"}}
 +
|- valign="top"
 +
| {{Code|-R}}
 +
| Specifies if a query will be executed or parsed only.
 +
| {{Option|RUNQUERY}}
 +
| <code>true</code>
 +
| {{Code|-V -R "1"}}
 +
|- valign="top"
 +
| {{Code|-s&lt;args&gt;}}
 +
| Specifies parameters for serializing XQuery results; see [[Serialization]] for more details. This flag may be specified multiple times. Key and values are separated by the equality sign (<code>=</code>).
 +
| {{Option|SERIALIZER}}
 
|
 
|
 +
| <code>-smethod=text</code>
 +
|- valign="top"
 +
| {{Code|-U&lt;name&gt;}}
 +
| Specifies the username. If this flag is omitted, the username will be requested on command line.
 +
| {{Option|USER}}
 
|
 
|
 +
| {{Code|-Uadmin}}
 
|- valign="top"
 
|- valign="top"
| <code>-w</code>
+
| {{Code|-v}}
| By default, whitespaces around text nodes are chopped when a database is created. This flag can be specified to suppress chopping.
+
| Prints process and timing information to the ''standard output''.
 
|
 
|
 +
| <code>false</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
| <code>-z</code>
+
| {{Code|-V}}
| Skip the serialization of XQuery results. This flag may be useful for analyzing query plans.
+
| Prints detailed query information to the ''standard output'', including details on the compilation and profiling steps.
 +
| {{Option|QUERYINFO}}
 +
| <code>false</code>
 
|
 
|
 +
|- valign="top"
 +
| {{Code|-w}}
 +
| Toggles whitespace stripping of XML text nodes. By default, whitespaces will be preserved.
 +
| {{Option|STRIPWS}}
 +
| <code>false</code>
 +
|
 +
|- valign="top"
 +
| {{Code|-W}}
 +
| Enables indentation with whitespace. By default, query results will not be indented.
 +
| {{Option|SERIALIZER}}
 +
| <code>indent=no</code>
 +
|
 +
|- valign="top"
 +
| {{Code|-x}}
 +
| Toggles the output of the query execution plan, formatted as XML.
 +
| {{Option|XMLPLAN}}
 +
| <code>false</code>
 +
|
 +
|- valign="top"
 +
| {{Code|-z}}
 +
| Turns the serialization of XQuery results on/off. This flag is useful if the query is profiled or analyzed.
 +
| {{Option|SERIALIZE}}
 +
| <code>true</code>
 
|
 
|
 
|}
 
|}
  
==BaseX Standalone==
+
=HTTP Server=
 +
 
 +
{{Announce|Added with Version 11:}} {{Code|-C}}
  
;Launch the interactive mode:
+
The following options are available for the [[Web Application|HTTP Server]]:
<pre>
 
> basex
 
BaseX [Standalone]
 
Try "help" to get more information.
 
>_</pre>
 
  
Available command-line options can be listed with the <code>-h</code> flag:
 
 
<pre>
 
<pre>
> basex -h
+
$ basexhttp -h
Usage: BaseX [-diosuvVwz] [-cq] [file]
+
BaseX [HTTP]
   [file]    Execute XQuery file
+
Usage: basexhttp [-cdhlnpsSUz] [stop]
   -c<cmd>   Execute database command(s)
+
   stop      Stop running server
   -d        Activate debugging mode
+
  -c<input>  Execute commands from file or string
   -i<input> Open initial file or database
+
   -C<file>   Execute command script file
   -o<fileWrite output to file
+
   -d        Enable debugging output
   -q<exprExecute XQuery expression
+
  -g        Enable GZIP support
   -s<parsSet serialization parameter(s)
+
   -h<port>   Set port of HTTP server
   -u         Modifiy original files after updates
+
  -l        Start in local mode
   -v/V      Show (all) process info
+
   -n<nameSet host name of database server
   -w        Retain whitespaces from source files
+
   -p<portSet port of database server
   -z        Skip output of results
+
   -s<portSpecify port to stop HTTP server
 +
   -S         Start as service
 +
   -U<name>   Specify username
 +
   -z        Suppress logging
 
</pre>
 
</pre>
  
The options have the following meaning:
+
The meaning of all options is listed in the following table (equivalent database options are shown in the table as well).
 +
For the examples to work, it might be necessary to escape some characters depending on your Operating System.
  
{| class="wikitable"  
+
{| class="wikitable"
 
|- valign="top"
 
|- valign="top"
! width='75' | Flag
+
! width='120' | Flag
! Description
+
! width="40%" | Description
! width='165' | Examples
+
! Option
 +
! Default
 +
! Examples
 
|- valign="top"
 
|- valign="top"
| <code>[file]</code>
+
| {{Code|stop}}
| Execute the specified XQuery file.
+
| Stops a local HTTP server and quits. The database server will be stopped as well, unless {{Code|-l}} is specified.
 +
| <code>pom.xml</code>
 +
|
 
|
 
|
 
|- valign="top"
 
|- valign="top"
| <code>-c&lt;cmd&gt;</code>
+
| {{Code|-c&lt;input&gt;}}
| Launch database commands and skip interactive mode. The flag should be placed last, as all remaining characters are interpreted as commands. Several commands can be separated by semicolons.
+
| Executes [[commands]]. If the specified input is a valid URI or file reference, this file is evaluated as [[Commands#Command_Scripts|Command Script]].
| <code>-c"list;info"</code>
+
|
 +
|
 +
| {{Code|-c"open database"}}
 
|- valign="top"
 
|- valign="top"
| <code>-d</code>
+
| {{Code|-C&lt;file&gt;}}
| Turn on debugging. Debugging information is output to ''standard error''.
+
| Evaluates the contents of the specified file as [[Commands#Command_Scripts|Command Script]].
 +
|
 +
|
 
|
 
|
 
|- valign="top"
 
|- valign="top"
| <code>-i&lt;input&gt;</code>
+
| {{Code|-e}}
| Open a database or XML document specified by the argument. The opened input may be further processed by an XQuery expression.
+
| Enables debugging output. Debugging information is output to ''standard error''.
| <code>-iitems.xml -q"//item"</code>
+
| {{Option|DEBUG}}
 +
|
 +
|
 
|- valign="top"
 
|- valign="top"
| <code>-o&lt;file&gt;</code>
+
| {{Code|-g}}
| Command and query output is written to the specified file.
+
| Enables GZIP support in Jetty.
| <code>-p9999</code>
+
| {{Option|GZIP}}
 +
|
 +
|
 
|- valign="top"
 
|- valign="top"
| <code>-q&lt;expr&gt;</code>
+
| {{Code|-h&lt;port&gt;}}
| Execute the specified string as XQuery expression. The flag should be placed last, as all remaining characters are interpreted as XQuery.
+
| Specifies the port on which the HTTP server will be addressable.
| <code>-q"doc('input')//head"</code>
+
| <code>jetty.xml</code>
 +
| {{Code|8080}}
 +
| {{Code|-h9999}}
 
|- valign="top"
 
|- valign="top"
| <code>-s&lt;pars&gt;</code>
+
| {{Code|-l}}
| Specify parameters for serializing XQuery results, as specified in the [http://www.w3.org/TR/xslt-xquery-serialization/ W3C XQuery Serialization] document. This flag may be specified multiple times; key/value pairs are separated by equality signs (<code>=</code>).
+
| Starts the server in ''local mode'', and executes all commands in the embedded database context.
| <code>-smethod=text</code>
+
| {{Option|HTTPLOCAL}}
 +
|
 +
|
 +
|- valign="top"
 +
| {{Code|-n&lt;name&gt;}}
 +
| Specifies the host name on which the server is running.
 +
| {{Option|HOST}}
 +
| {{Code|localhost}}
 +
| {{Code|-nserver.basex.org}}
 +
|- valign="top"
 +
| {{Code|-p&lt;port&gt;}}
 +
| Specifies the port on which the database server will be addressable.
 +
| {{Option|SERVERPORT}}
 +
| {{Code|1984}}
 +
| {{Code|-p9998}}
 
|- valign="top"
 
|- valign="top"
| <code>-u</code>
+
| {{Code|-s&lt;port&gt;}}
| Modify original files after evaluating XQuery Update expressions.
+
| Specifies the port that will be used to stop the HTTP server.
 +
| {{Option|STOPPORT}} or<br/><code>pom.xml</code>
 +
| <code>8081</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
| <code>-v</code>
+
| {{Code|-S}}
| Process information is written to ''standard output''.
+
| Starts the server as service (i.e., in the background). Use [[YAJSW]], or start BaseX as an ordinary background process to get more options.
 
|
 
|
|- valign="top"
 
| <code>-V</code>
 
| Detailed query information is written to ''standard output'', including compilation and profiling steps.
 
 
|
 
|
 
|- valign="top"
 
|- valign="top"
| <code>-w</code>
+
| {{Code|-U&lt;name&gt;}}
| By default, whitespaces around text nodes are chopped when a database is created. This flag can be specified to suppress chopping.
+
| Specifies a username, which will be used by the HTTP services for opening a new session.
 +
| {{Option|USER}}
 
|
 
|
 +
| {{Code|-Uadmin}}
 
|- valign="top"
 
|- valign="top"
| <code>-z</code>
+
| {{Code|-z}}
| Skip the serialization of XQuery results. This flag may be useful for analyzing query plans.
+
| Prevents the generation of [[Logging|log files]].
 +
| {{Option|LOG}}
 
|
 
|
 
|}
 
|}
  
==BaseX REST==
+
=Changelog=
 +
 
 +
;Version 11.0
 +
* Added: {{Code|-C}} (standalone, server, client, HTTP server).
 +
* Added: {{Code|-Q}}, {{Code|-W}} (standalone, client).
 +
* Updated: The Clark notation was replaced with the [[XQuery 3.0#Expanded QNames|Expanded QNames]] notation.
 +
 
 +
;Version 10.0
 +
* Updated: Whitespaces are now preserved by default (see {{Option|STRIPWS}} for more details).
 +
 
 +
;Version 9.0
 +
* Added: BaseXHTTP, command-line option {{Code|-c}}.
 +
* Updated: BaseXHTTP, command-line option {{Code|-c}}, additionally accepts valid URLs and file references.
 +
 
 +
;Version 8.2
 +
* Removed: Event ports, {{Code|-e}}.
 +
 
 +
;Version 8.1
 +
* Added: Bind input strings to the query context with {{Code|-I}}.
 +
 
 +
;Version 8.0
 +
* Removed: Command-line option <code>-L</code> (results will now be automatically separated by newlines).
 +
 
 +
;Version 7.9
 +
* Added: Runs tests in file or directory with {{Code|-t}}.
 +
* Removed: interactive server mode.
 +
 
 +
;Version 7.8
 +
* Added: Specify if a query will be executed or parsed only with {{Code|-R}}.
  
;Launch the REST Server
+
;Version 7.7
<pre>
+
* Added: Bind host to the [[#BaseX Server|BaseX Server]] with {{Code|-n}}.
> basexrest
+
 
Starting REST Server on port 8984...
+
;Version 7.5
BaseX [Server]
+
* Added: detection of [[Commands#Basics|Command Scripts]].
Server was started.
+
* Removed: HTTP server flags {{Code|-R}}, {{Code|-W}}, and {{Code|-X}}.
2011-01-02 03:04:05.600:INFO::Logging to STDERR via org.mortbay.log.StdErrLog
 
2011-01-02 03:04:05.700:INFO::jetty-6.1.25
 
2011-01-02 03:04:05.800:INFO::Started SocketConnector@0.0.0.0:8984</pre>
 
  
Available command-line options can be listed with the <code>-h</code> flag:
+
; Version 7.3:
<pre>
+
* Updated: all options are now evaluated in the given order.
> basex -h
+
* Updated: Create main-memory representations for specified sources with {{Code|-i}}.
Usage: JaxRxServer [-pPrsUz]
+
* Updated: Options {{Code|-C}}/{{Code|-c}} and {{Code|-q}}/{{Code|[input]}} merged.
  -p<num>  Set database server port
+
* Updated: Option {{Code|-L}} also separates serialized items with newlines (instead of spaces).
  -P<pass>  Specify user password
 
  -r<num>  Set REST server port
 
  -s<pars>  Set serialization parameter(s)
 
  -U<name>  Specify user name
 
  -z        Suppress logging
 
</pre>
 
  
The options have the following meaning:
+
; Version 7.2:
 +
* Added: RESTXQ Service
  
{| class="wikitable"
+
; Version 7.1.1:
|- valign="top"
+
* Added: Options {{Code|-C}} and {{Code|-L}} in standalone and client mode.
! width='70' | Flag
 
! Description
 
! width='145' | Examples
 
|- valign="top"
 
| <code>-p&lt;num&gt;</code>
 
| The port on which the BaseX Server will be addressable. The default port is '''1984'''.
 
| <code>-p9998</code>
 
|- valign="top"
 
| <code>-r&lt;num&gt;</code>
 
| The port on which the REST Server will be addressable. This port will be specified in the REST URLs. The default port is '''8984'''.
 
| <code>-r9999</code>
 
|- valign="top"
 
| <code>-P&lt;pass&gt;</code>
 
| The user password, which will be used by JAX-RX to communicate with the BaseX Server. The default password is '''admin'''. ''Warning'': when the password is specified on command-line, it may be visible to others.
 
| <code>-Uadmin -Padmin</code>
 
|- valign="top"
 
| <code>-s&lt;pars&gt;</code>
 
| Specify parameters for serializing XQuery results, as specified in the [http://www.w3.org/TR/xslt-xquery-serialization/ W3C XQuery Serialization] document. This flag may be specified multiple times; key/value pairs are separated by equality signs (<code>=</code>).
 
| <code>-sencoding=US-ASCII</code><br /><code>-sindent=no</code>
 
|- valign="top"
 
| <code>-U&lt;name&gt;</code>
 
| The user name, which will be used by JAX-RX to communicate with the BaseX Server. The default user is '''admin'''.
 
| <code>-Uadmin</code>
 
|- valign="top"
 
| <code>-z</code>
 
| Do not generate [[Logging|log files]].
 
|
 
|}
 
  
[[Category:Beginner]]
+
; Version 7.1:
 +
* Updated: Multiple query files and {{Code|-c}}/{{Code|-i}}/{{Code|-q}} flags can be specified.

Latest revision as of 00:39, 21 January 2024

This article is part of the Getting Started Guide. Each BaseX Startup mode has one or more command-line options, which are described in this article.

Command-line options can be specified multiple times. Please note that all options will be evaluated in the given order. The standard input can be parsed by specifying a single dash (-) as an argument.

Updated with Version 11: The Clark notation was replaced with the Expanded QNames notation.

Standalone[edit]

Added with Version 11: -C, -Q, -W

The following options are available for the standalone Command-Line Client:

$ basex -h
BaseX [Standalone]
Usage: basex [-bcdiIoqrRstuvVwxz] [input]
  [input]    XQuery or command file, or query string
  -b<args>   Bind external query variables
  -c<input>  Execute commands from file or string
  -C<file>   Execute command script file
  -d         Toggle debugging output
  -i<input>  Bind file or database to context
  -I<input>  Bind input string to context
  -o<path>   Write output to local file
  -q<expr>   Execute XQuery expression
  -Q<file>   Execute XQuery file
  -r<num>    Run query multiple times
  -R         Toggle query execution
  -s<args>   Set serialization parameters
  -t[path]   Run tests in file or directory
  -u         Toggle updates in original files
  -v         Toggle output of progress info
  -V         Toggle detailed query output
  -w         Toggle whitespace stripping
  -W         Enable indentation with whitespaces
  -x         Toggle output of query plan
  -z         Toggle output of query result

Further details are listed in the following table. If an equivalent database option exists (which can be specified via the SET command), it is listed as well. For the examples to work, it might be necessary to escape some characters depending on your operating system.

Flag Description Option Default Examples
[input] Evaluates the specified input:
  • The input string may point to an existing file. If the file suffix is .bxs, the file contents will be executed as Command Script; any other file content will be evaluated as XQuery expression.
  • Otherwise, the input string itself is evaluated as XQuery expression.
"doc('X')//head"
query.xq
commands.bxs
-b<args> Binds external variables to XQuery expressions. This flag may be specified multiple times. Variables names and their values are delimited by equality signs (=). The names may be optionally prefixed with dollar signs. If a variable uses a namespace different from the default namespace, it can be specified with the Expanded QNames notation. BINDINGS -bv=example "declare variable $v external; $v"
-bQ{URL}ln=value
"declare namespace ns='URL'; declare variable $ns:ln external; $ns:ln"
-c<input> Executes commands. If the specified input is a valid URI or file reference, this file is evaluated as Command Script. -c list
-ccommands.txt
-c"<info/>"
-C<file> Evaluates the contents of the specified file as Command Script.
-d Toggles the debugging mode. Debugging information is output to standard error. DEBUG false
-i<input> Opens the specified XML file, directory with XML files, or database. The opened input can then be processed by a command or XQuery expression. -iitems.xml "//item"
-I<input> Assigns an input string as item of type xs:untypedAtomic to the query context. -I "Hello Universe" -q "."
-o<path> All command and query output is written to the specified file. -o output.txt
-q<expr> Evaluates the specified string as XQuery expression. -q"doc('input')//head"
-Q<file> Evaluates the contents of the specified file as XQuery expression.
-r<num> Specifies how often a specified query will be evaluated. RUNS 1 -V -r10 "1"
-R Specifies if a query will be evaluated or parsed and compiled only. RUNQUERY true -V -R "1"
-s<args> Specifies parameters for serializing XQuery results; see Serialization for more details. This flag may be specified multiple times. Key and values are separated by the equality sign (=). SERIALIZER -smethod=text
-t[path] Runs all Unit tests in the specified file or directory. -t project/tests
-u Propagates updates on input files back to disk. WRITEBACK false
-v Toggles the output of process and timing information. false
-V Prints detailed query information to the standard output, including details on the compilation and profiling steps. QUERYINFO false
-w Toggles whitespace stripping of XML text nodes. By default, whitespaces will be preserved. STRIPWS false
-W Enables indentation with whitespace. By default, query results will not be indented. SERIALIZER indent=no
-x Toggles the output of the query execution plan, formatted as XML. XMLPLAN false
-z Turns the serialization of XQuery results on/off. This flag is useful if the query is profiled or analyzed. SERIALIZE true

GUI[edit]

The following options are available for the standalone Graphical User Interface:

$ basexgui -h
BaseX [GUI]
Usage: basexgui [-d] [files]
  [files]  Open specified files
  -d  Enable debugging

You can pass one or more files as parameters. If an XML document is specified, a database instance can be created from this file. Other files are opened in the editor.

Server[edit]

Added with Version 11: -C

The following options are available for the Database Server:

$ basexserver -h
BaseX [Server]
Usage: basexserver [-cdnpSz] [stop]
  stop       Stop running server
  -c<input>  Execute commands from file or string
  -C<file>   Execute command script file
  -d         Enable debugging output
  -n<name>   Set host the server is bound to
  -p<port>   Set server port
  -S         Start as service
  -z         Suppress logging

Details on all options are listed in the following table (equivalent database options are shown in the table as well). For the examples to work, it might be necessary to escape some characters depending on your operating system.

Flag Description Option Default Examples
stop Stops a local database server instance and quits.
-c<input> Executes commands. If the specified input is a valid URI or file reference, this file is evaluated as Command Script. -c"open database;info"
-C<file> Evaluates the contents of the specified file as Command Script.
-d Enables debugging output. Debugging information is output to standard error. DEBUG false
-n<name> Specifies the host the server will be bound to. SERVERHOST -p127.0.0.1
-p<port> Specifies the port on which the server will be addressable. SERVERPORT 1984 -p9999
-S Starts the server as service (i.e., in the background). Use YAJSW, or start BaseX as an ordinary background process to get more options.
-z Prevents the generation of log files. LOG true

Multiple -c and -i flags can be specified. All other options will be set before any other operation takes place. The specified inputs, query files, queries and commands will be subsequently evaluated after that in the given order. The standard input can be parsed by specifying a single dash (-) as argument.

Client[edit]

Added with Version 11: -C, -Q, -W

If the Database Client is launched, you will be requested for a username and password.

$ basexclient -h
BaseX [Client]
Usage: basexclient [-bcdiInopPqrRsUvVwxz] [input]
  [input]    XQuery or command file, or query string
  -b<args>   Bind external query variables
  -c<input>  Execute commands from file or string
  -C<file>   Execute command script file
  -d         Toggle debugging output
  -i<input>  Bind file or database to context
  -I<input>  Bind input string to context
  -n<name>   Set server (host) name
  -o<path>   Write output to local file
  -p<port>   Set server port
  -P<pass>   Specify user password
  -q<expr>   Execute XQuery expression
  -Q<file>   Execute XQuery file
  -r<num>    Run query multiple times
  -R         Toggle query execution
  -s<args>   Set serialization parameters
  -U<name>   Specify username
  -v         Toggle output of progress info
  -V         Toggle detailed query output
  -w         Toggle whitespace stripping
  -W         Enable indentation with whitespaces
  -x         Toggle output of query plan
  -z         Toggle output of query result

See the following table for details (equivalent database options are shown in the table as well). For the examples to work, it might be necessary to escape some characters, depending on your operating system.

Flag Description Option Default Examples
[input] Evaluates the specified input:
  • The input string may point to an existing file. If the file suffix is .bxs, the file contents will be evaluated as Command Script; any other file content will be evaluated as XQuery expression.
  • Otherwise, the input string itself is evaluated as XQuery expression.
"doc('X')//head"
query.xq
commands.bxs
-b<args> Binds external variables to XQuery expressions. This flag may be specified multiple times. Variables names and their values are delimited by equality signs (=). The names may be optionally prefixed with dollar signs. If a variable uses a namespace different from the default namespace, it can be specified with the Expanded QNames notation. BINDINGS -b$v=example "declare variable $v external; $v"
-bQ{URL}ln=value
"declare namespace ns='URL'; declare variable $ns:ln external; $ns:ln"
-c<input> Executes commands. If the specified input is a valid URI or file reference, its content will be executed instead. Empty lines and lines starting with the number sign # will be ignored. -c list
-ccommands.txt
-c"<info/>"
-C<file> Evaluates the contents of the specified file as Command Script.
-d Toggles the debugging mode. Debugging information is output to standard error. DEBUG false
-i<input> Opens the specified XML file, directory with XML files, or database. The opened input can then be processed by a command or XQuery expression. -iitems.xml "//item"
-I<input> Assigns an input string as item of type xs:untypedAtomic to the query context. -I "Hello Universe" -q "."
-n<name> Specifies the host name on which the server is running. HOST localhost -nserver.basex.org
-o<path> All command and query output is written to the specified file.
-p<port> Specifies the port on which the server is running. PORT 1984 -p9999
-P<pass> Specifies the user password. If this flag is omitted, the password will be requested on command line. Warning: When the password is supplied with this flag, it may end up in logs or the bash history. PASSWORD -Uadmin -P...
-q<expr> Executes the specified string as XQuery expression. -q"1+2"
-Q<file> Evaluates the contents of the specified file as XQuery expression.
-r<num> Specifies how often a specified query will be evaluated. RUNS 1 -V -r10 "1"
-R Specifies if a query will be executed or parsed only. RUNQUERY true -V -R "1"
-s<args> Specifies parameters for serializing XQuery results; see Serialization for more details. This flag may be specified multiple times. Key and values are separated by the equality sign (=). SERIALIZER -smethod=text
-U<name> Specifies the username. If this flag is omitted, the username will be requested on command line. USER -Uadmin
-v Prints process and timing information to the standard output. false
-V Prints detailed query information to the standard output, including details on the compilation and profiling steps. QUERYINFO false
-w Toggles whitespace stripping of XML text nodes. By default, whitespaces will be preserved. STRIPWS false
-W Enables indentation with whitespace. By default, query results will not be indented. SERIALIZER indent=no
-x Toggles the output of the query execution plan, formatted as XML. XMLPLAN false
-z Turns the serialization of XQuery results on/off. This flag is useful if the query is profiled or analyzed. SERIALIZE true

HTTP Server[edit]

Added with Version 11: -C

The following options are available for the HTTP Server:

$ basexhttp -h
BaseX [HTTP]
Usage: basexhttp [-cdhlnpsSUz] [stop]
  stop       Stop running server
  -c<input>  Execute commands from file or string
  -C<file>   Execute command script file
  -d         Enable debugging output
  -g         Enable GZIP support
  -h<port>   Set port of HTTP server
  -l         Start in local mode
  -n<name>   Set host name of database server
  -p<port>   Set port of database server
  -s<port>   Specify port to stop HTTP server
  -S         Start as service
  -U<name>   Specify username
  -z         Suppress logging

The meaning of all options is listed in the following table (equivalent database options are shown in the table as well). For the examples to work, it might be necessary to escape some characters depending on your Operating System.

Flag Description Option Default Examples
stop Stops a local HTTP server and quits. The database server will be stopped as well, unless -l is specified. pom.xml
-c<input> Executes commands. If the specified input is a valid URI or file reference, this file is evaluated as Command Script. -c"open database"
-C<file> Evaluates the contents of the specified file as Command Script.
-e Enables debugging output. Debugging information is output to standard error. DEBUG
-g Enables GZIP support in Jetty. GZIP
-h<port> Specifies the port on which the HTTP server will be addressable. jetty.xml 8080 -h9999
-l Starts the server in local mode, and executes all commands in the embedded database context. HTTPLOCAL
-n<name> Specifies the host name on which the server is running. HOST localhost -nserver.basex.org
-p<port> Specifies the port on which the database server will be addressable. SERVERPORT 1984 -p9998
-s<port> Specifies the port that will be used to stop the HTTP server. STOPPORT or
pom.xml
8081
-S Starts the server as service (i.e., in the background). Use YAJSW, or start BaseX as an ordinary background process to get more options.
-U<name> Specifies a username, which will be used by the HTTP services for opening a new session. USER -Uadmin
-z Prevents the generation of log files. LOG

Changelog[edit]

Version 11.0
  • Added: -C (standalone, server, client, HTTP server).
  • Added: -Q, -W (standalone, client).
  • Updated: The Clark notation was replaced with the Expanded QNames notation.
Version 10.0
  • Updated: Whitespaces are now preserved by default (see STRIPWS for more details).
Version 9.0
  • Added: BaseXHTTP, command-line option -c.
  • Updated: BaseXHTTP, command-line option -c, additionally accepts valid URLs and file references.
Version 8.2
  • Removed: Event ports, -e.
Version 8.1
  • Added: Bind input strings to the query context with -I.
Version 8.0
  • Removed: Command-line option -L (results will now be automatically separated by newlines).
Version 7.9
  • Added: Runs tests in file or directory with -t.
  • Removed: interactive server mode.
Version 7.8
  • Added: Specify if a query will be executed or parsed only with -R.
Version 7.7
Version 7.5
  • Added: detection of Command Scripts.
  • Removed: HTTP server flags -R, -W, and -X.
Version 7.3
  • Updated: all options are now evaluated in the given order.
  • Updated: Create main-memory representations for specified sources with -i.
  • Updated: Options -C/-c and -q/[input] merged.
  • Updated: Option -L also separates serialized items with newlines (instead of spaces).
Version 7.2
  • Added: RESTXQ Service
Version 7.1.1
  • Added: Options -C and -L in standalone and client mode.
Version 7.1
  • Updated: Multiple query files and -c/-i/-q flags can be specified.