Difference between revisions of "Command-Line Options"

From BaseX Documentation
Jump to navigation Jump to search
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
This article is part of the [[Getting Started]] Guide.
 
This article is part of the [[Getting Started]] Guide.
It gives more details on the command-line options of all BaseX [[Startup]] modes.
+
Each BaseX [[Startup]] mode has one or more command-line options which are described in this article.
  
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 argument.
+
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 argument.
  
 
=Standalone=
 
=Standalone=
  
;Launch the console mode:
+
;Launch the standalone (console) mode:
 
<pre>
 
<pre>
 
$ basex
 
$ basex
Line 13: Line 13:
 
> _</pre>
 
> _</pre>
  
Available command-line flags can be listed with {{Code|-h}}:
+
You can list the command-line options available for the standalone mode using {{Code|-h}}:
 
<pre>
 
<pre>
 
$ basex -h
 
$ basex -h
Line 38: Line 38:
 
</pre>
 
</pre>
  
The meaning of all flags is listed in the following table. If an equivalent database option exists (which can be specified via the <code>[[Commands#SET|SET]]</code> command), it is listed as well. For the examples to work escaping some characters might be necessary, depending on your Operating System.
+
The meaning of all options is listed in the following table. If an equivalent database option exists (which can be specified via the <code>[[Commands#SET|SET]]</code> 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"
 
{| class="wikitable"
Line 58: Line 59:
 
| {{Code|-b&lt;args&gt;}}
 
| {{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 to the default namespace, it can be specified with the [http://www.jclark.com/xml/xmlns.htm Clark Notation].
 
| 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 to the default namespace, it can be specified with the [http://www.jclark.com/xml/xmlns.htm Clark Notation].
| <code>[[Options#BINDINGS|BINDINGS]]</code>
+
| {{Option|BINDINGS}}
 
|
 
|
 
|• <code>-bv=example "declare variable $v external; $v"</code><br/>• <code>-b{URL}ln=value<br/>"declare namespace ns='URL'; declare variable $ns:ln external; $ns:ln"</code>
 
|• <code>-bv=example "declare variable $v external; $v"</code><br/>• <code>-b{URL}ln=value<br/>"declare namespace ns='URL'; declare variable $ns:ln external; $ns:ln"</code>
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-c&lt;input&gt;}}
 
| {{Code|-c&lt;input&gt;}}
| Executes [[commands]]:
+
| Executes [[commands]]. If the specified input is a valid URI or file reference, this file will be evaluated as [[Commands#Command_Scripts|Command Script]].
* Several commands in the input can be separated by semicolons ({{Code|;}}).
 
* If the specified input is a valid URL or file reference, this file will be evaluated as [[Commands#Command_Scripts|Command Script]].
 
 
|
 
|
 
|
 
|
|• {{Code|-c"list;info"}}<br/>• {{Code|-ccommands.txt}}<br/>• {{Code|-c"<info/>"}}
+
|• {{Code|-c list}}<br/>• {{Code|-ccommands.txt}}<br/>• {{Code|-c"<info/>"}}
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-d}}
 
| {{Code|-d}}
 
| Toggles the debugging mode. Debugging information is output to ''standard error''.
 
| Toggles the debugging mode. Debugging information is output to ''standard error''.
| <code>[[Options#DEBUG|DEBUG]]</code>
+
| {{Option|DEBUG}}
 
| <code>false</code>
 
| <code>false</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-i&lt;input&gt;}}
 
| {{Code|-i&lt;input&gt;}}
| Opens an XML file or database specified by the argument. The opened input can then be processed by a command or XQuery expression.
+
| Opens the specified XML file, directory with XML files, or database. The opened input can then be processed by a command or XQuery expression.
 
|
 
|
 
|
 
|
Line 102: Line 101:
 
| {{Code|-r&lt;num&gt;}}
 
| {{Code|-r&lt;num&gt;}}
 
| Specifies how often a specified query will be evaluated.
 
| Specifies how often a specified query will be evaluated.
| <code>[[Options#RUNS|RUNS]]</code>
+
| {{Option|RUNS}}
 
| <code>1</code>
 
| <code>1</code>
 
| {{Code|-V -r10 "1"}}
 
| {{Code|-V -r10 "1"}}
Line 108: Line 107:
 
| {{Code|-R}}
 
| {{Code|-R}}
 
| Specifies if a query will be executed or parsed only.
 
| Specifies if a query will be executed or parsed only.
| <code>[[Options#RUNQUERY|RUNQUERY]]</code>
+
| {{Option|RUNQUERY}}
 
| <code>true</code>
 
| <code>true</code>
 
| {{Code|-V -R "1"}}
 
| {{Code|-V -R "1"}}
Line 114: Line 113:
 
| {{Code|-s&lt;args&gt;}}
 
| {{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>).
 
| 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>).
| <code>[[Options#SERIALIZER|SERIALIZER]]</code>
+
| {{Option|SERIALIZER}}
 
|
 
|
 
| <code>-smethod=text</code>
 
| <code>-smethod=text</code>
Line 126: Line 125:
 
| {{Code|-u}}
 
| {{Code|-u}}
 
| Propagates updates on input files back to disk.
 
| Propagates updates on input files back to disk.
| <code>[[Options#WRITEBACK|WRITEBACK]]</code>
+
| {{Option|WRITEBACK}}
 
| <code>false</code>
 
| <code>false</code>
 
|
 
|
Line 138: Line 137:
 
| {{Code|-V}}
 
| {{Code|-V}}
 
| Prints detailed query information to the ''standard output'', including details on the compilation and profiling steps.
 
| Prints detailed query information to the ''standard output'', including details on the compilation and profiling steps.
| <code>[[Options#QUERYINFO|QUERYINFO]]</code>
+
| {{Option|QUERYINFO}}
 
| <code>false</code>
 
| <code>false</code>
 
|
 
|
Line 144: Line 143:
 
| {{Code|-w}}
 
| {{Code|-w}}
 
| Toggles whitespace chopping of XML text nodes. By default, whitespaces will be chopped.
 
| Toggles whitespace chopping of XML text nodes. By default, whitespaces will be chopped.
| <code>[[Options#CHOP|CHOP]]</code>
+
| {{Option|CHOP}}
 
| <code>true</code>
 
| <code>true</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-x}}
 
| {{Code|-x}}
| Toggles the output of the query execution plan, formatted as [[Options#XMLPLAN|XML]].
+
| Toggles the output of the query execution plan, formatted as {{Option|XML}}.
| <code>[[Options#XMLPLAN|XMLPLAN]]</code>
+
| {{Option|XMLPLAN}}
 
| <code>false</code>
 
| <code>false</code>
 
|
 
|
Line 156: Line 155:
 
| {{Code|-X}}
 
| {{Code|-X}}
 
| Generates the query plan before or after query compilation. {{Code|-x}} needs to be activated to make the plan visible.
 
| Generates the query plan before or after query compilation. {{Code|-x}} needs to be activated to make the plan visible.
| <code>[[Options#COMPPLAN|COMPPLAN]]</code>
+
| {{Option|COMPPLAN}}
 
| <code>true</code>
 
| <code>true</code>
 
|
 
|
Line 162: Line 161:
 
| {{Code|-z}}
 
| {{Code|-z}}
 
| Turns the serialization of XQuery results on/off. This flag is useful if the query is profiled or analyzed.
 
| Turns the serialization of XQuery results on/off. This flag is useful if the query is profiled or analyzed.
| <code>[[Options#SERIALIZE|SERIALIZE]]</code>
+
| {{Option|SERIALIZE}}
 
| <code>true</code>
 
| <code>true</code>
 
|
 
|
Line 169: Line 168:
 
=GUI=
 
=GUI=
 
;Launch the GUI:
 
;Launch the GUI:
 +
 +
The <code>basexgui</code> command has only one option. You can pass one or more XML and XQuery files as parameters. If an XML file is specified, a database instance is created from this file, or an existing database is opened. XQuery files are opened in the XQuery editor.
 +
 
<pre>
 
<pre>
 
$ basexgui [file]
 
$ basexgui [file]
 
</pre>
 
</pre>
 
One or more XML and XQuery files can be passed on as parameters. If an XML file is specified, a database instance is created from this file, or an existing database is opened. XQuery files are opened in the XQuery editor.
 
  
 
=Server=
 
=Server=
Line 184: Line 184:
 
</pre>
 
</pre>
  
Available command-line flags can be listed with {{Code|-h}}:
+
You can list the available command-line options using {{Code|-h}}:
 
<pre>
 
<pre>
 
$ basexserver -h
 
$ basexserver -h
Line 198: Line 198:
 
</pre>
 
</pre>
  
The flags have the following meaning (equivalent database options are shown in the table as well).
+
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 escaping some characters might be necessary, depending on your Operating System.
+
For the examples to work, it might be necessary to escape some characters depending on your Operating System.
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 215: Line 215:
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-c&lt;input&gt;}}
 
| {{Code|-c&lt;input&gt;}}
| Executes [[commands]]:
+
| Executes [[commands]]. If the specified input is a valid URI or file reference, this file will be evaluated as [[Commands#Command_Scripts|Command Script]].
* Several commands in the input can be separated by semicolons ({{Code|;}}).
 
* If the specified input is a valid URL or file reference, this file will be evaluated as [[Commands#Command_Scripts|Command Script]].
 
 
|
 
|
 
|
 
|
Line 224: Line 222:
 
| {{Code|-d}}
 
| {{Code|-d}}
 
| Turns on the debugging mode. Debugging information is output to ''standard error''.
 
| Turns on the debugging mode. Debugging information is output to ''standard error''.
| <code>[[Options#DEBUG|DEBUG]]</code>
+
| {{Option|DEBUG}}
 
| <code>false</code>
 
| <code>false</code>
 
|
 
|
Line 230: Line 228:
 
| {{Code|-n&lt;name&gt;}}
 
| {{Code|-n&lt;name&gt;}}
 
| Specifies the host the server will be bound to.
 
| Specifies the host the server will be bound to.
| <code>[[Options#SERVERHOST|SERVERHOST]]</code>
+
| {{Option|SERVERHOST}}
 
|
 
|
 
| {{Code|-p127.0.0.1}}
 
| {{Code|-p127.0.0.1}}
Line 236: Line 234:
 
| {{Code|-p&lt;port&gt;}}
 
| {{Code|-p&lt;port&gt;}}
 
| Specifies the port on which the server will be addressable.
 
| Specifies the port on which the server will be addressable.
| <code>[[Options#SERVERPORT|SERVERPORT]]</code>
+
| {{Option|SERVERPORT}}
 
| {{Code|1984}}
 
| {{Code|1984}}
 
| {{Code|-p9999}}
 
| {{Code|-p9999}}
Line 247: Line 245:
 
| {{Code|-z}}
 
| {{Code|-z}}
 
| Prevents the generation of [[Logging|log files]].
 
| Prevents the generation of [[Logging|log files]].
| <code>[[Options#LOG|LOG]]</code>
+
| {{Option|LOG}}
 
| <code>true</code>
 
| <code>true</code>
 
|
 
|
Line 268: Line 266:
 
</pre>
 
</pre>
  
Available command-line flags can be listed with {{Code|-h}}:
+
You can list the available command-line options using {{Code|-h}}:
 
<pre>
 
<pre>
 
$ basexclient -h
 
$ basexclient -h
Line 295: Line 293:
 
</pre>
 
</pre>
  
The flags have the following meaning (equivalent database options are shown in the table as well).
+
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 escaping some characters might be necessary, depending on your Operating System.
+
For the examples to work, it might be necessary to escape some characters depending on your Operating System.
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 316: Line 314:
 
| {{Code|-b&lt;args&gt;}}
 
| {{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 to the default namespace, it can be specified with the [http://www.jclark.com/xml/xmlns.htm Clark Notation] or [http://www.w3.org/TR/xquery-30/#id-basics Expanded QName Notation].
 
| 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 to the default namespace, it can be specified with the [http://www.jclark.com/xml/xmlns.htm Clark Notation] or [http://www.w3.org/TR/xquery-30/#id-basics Expanded QName Notation].
| <code>[[Options#BINDINGS|BINDINGS]]</code>
+
| {{Option|BINDINGS}}
 
|
 
|
 
|• <code>-b$v=example "declare variable $v external; $v"</code><br/>• <code>-b{URL}ln=value<br/>"declare namespace ns='URL'; declare variable $ns:ln external; $ns:ln"</code>
 
|• <code>-b$v=example "declare variable $v external; $v"</code><br/>• <code>-b{URL}ln=value<br/>"declare namespace ns='URL'; declare variable $ns:ln external; $ns:ln"</code>
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-c&lt;input&gt;}}
 
| {{Code|-c&lt;input&gt;}}
| Executes [[commands]]:
+
| 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.
* Several commands in the input can be separated by semicolons ({{Code|;}}).
 
* If the specified input is a valid file reference or URL, its content will be executed instead. Empty lines and lines starting with the number sign {{Code|#}} will be ignored.
 
 
|
 
|
 
|
 
|
|• {{Code|-c"list;info"}}<br/>• {{Code|-ccommands.txt}}<br/>• {{Code|-c"<info/>"}}
+
|• {{Code|-c list}}<br/>• {{Code|-ccommands.txt}}<br/>• {{Code|-c"<info/>"}}
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-d}}
 
| {{Code|-d}}
 
| Toggles the debugging mode. Debugging information is output to ''standard error''.
 
| Toggles the debugging mode. Debugging information is output to ''standard error''.
| <code>[[Options#DEBUG|DEBUG]]</code>
+
| {{Option|DEBUG}}
 
| <code>false</code>
 
| <code>false</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-i&lt;input&gt;}}
 
| {{Code|-i&lt;input&gt;}}
| Opens an XML file or database specified by the argument. The opened input can then be processed by a command or XQuery expression.
+
| Opens the specified XML file, directory with XML files, or database. The opened input can then be processed by a command or XQuery expression.
 
|
 
|
 
|
 
|
Line 348: Line 344:
 
| {{Code|-n&lt;name&gt;}}
 
| {{Code|-n&lt;name&gt;}}
 
| Specifies the host name on which the server is running.
 
| Specifies the host name on which the server is running.
| <code>[[Options#HOST|HOST]]</code>
+
| {{Option|HOST}}
 
| {{Code|localhost}}
 
| {{Code|localhost}}
 
| {{Code|-nserver.basex.org}}
 
| {{Code|-nserver.basex.org}}
Line 360: Line 356:
 
| {{Code|-p&lt;port&gt;}}
 
| {{Code|-p&lt;port&gt;}}
 
| Specifies the port on which the server is running.
 
| Specifies the port on which the server is running.
| <code>[[Options#PORT|PORT]]</code>
+
| {{Option|PORT}}
 
| {{Code|1984}}
 
| {{Code|1984}}
 
| {{Code|-p9999}}
 
| {{Code|-p9999}}
Line 366: Line 362:
 
| {{Code|-P&lt;pass&gt;}}
 
| {{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 specified with this flag, it may get visible to others.
 
| Specifies the user password. If this flag is omitted, the password will be requested on command line. ''Warning'': when the password is specified with this flag, it may get visible to others.
| <code>[[Options#PASSWORD|PASSWORD]]</code>
+
| {{Option|PASSWORD}}
 
|
 
|
 
| {{Code|-Uadmin -Padmin}}
 
| {{Code|-Uadmin -Padmin}}
Line 373: Line 369:
 
| Executes the specified string as XQuery expression.
 
| Executes the specified string as XQuery expression.
 
|
 
|
| {{Code|-q"doc('input')//head"}}
+
| {{Code|-q"1+2"}}
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-r&lt;num&gt;}}
 
| {{Code|-r&lt;num&gt;}}
 
| Specifies how often a specified query will be evaluated.
 
| Specifies how often a specified query will be evaluated.
| <code>[[Options#RUNS|RUNS]]</code>
+
| {{Option|RUNS}}
 
| <code>1</code>
 
| <code>1</code>
 
| {{Code|-V -r10 "1"}}
 
| {{Code|-V -r10 "1"}}
Line 383: Line 379:
 
| {{Code|-R}}
 
| {{Code|-R}}
 
| Specifies if a query will be executed or parsed only.
 
| Specifies if a query will be executed or parsed only.
| <code>[[Options#RUNQUERY|RUNQUERY]]</code>
+
| {{Option|RUNQUERY}}
 
| <code>true</code>
 
| <code>true</code>
 
| {{Code|-V -R "1"}}
 
| {{Code|-V -R "1"}}
Line 389: Line 385:
 
| {{Code|-s&lt;args&gt;}}
 
| {{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>).
 
| 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>).
| <code>[[Options#SERIALIZER|SERIALIZER]]</code>
+
| {{Option|SERIALIZER}}
 
|
 
|
 
| <code>-smethod=text</code>
 
| <code>-smethod=text</code>
Line 395: Line 391:
 
| {{Code|-U&lt;name&gt;}}
 
| {{Code|-U&lt;name&gt;}}
 
| Specifies the user name. If this flag is omitted, the user name will be requested on command line.
 
| Specifies the user name. If this flag is omitted, the user name will be requested on command line.
| <code>[[Options#USER|USER]]</code>
+
| {{Option|USER}}
 
|
 
|
 
| {{Code|-Uadmin}}
 
| {{Code|-Uadmin}}
Line 407: Line 403:
 
| {{Code|-V}}
 
| {{Code|-V}}
 
| Prints detailed query information to the ''standard output'', including details on the compilation and profiling steps.
 
| Prints detailed query information to the ''standard output'', including details on the compilation and profiling steps.
| <code>[[Options#QUERYINFO|QUERYINFO]]</code>
+
| {{Option|QUERYINFO}}
 
| <code>false</code>
 
| <code>false</code>
 
|
 
|
Line 413: Line 409:
 
| {{Code|-w}}
 
| {{Code|-w}}
 
| Toggles whitespace chopping of XML text nodes. By default, whitespaces will be chopped.
 
| Toggles whitespace chopping of XML text nodes. By default, whitespaces will be chopped.
| <code>[[Options#CHOP|CHOP]]</code>
+
| {{Option|CHOP}}
 
| <code>chop</code>
 
| <code>chop</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-x}}
 
| {{Code|-x}}
| Toggles the output of the query execution plan, formatted as [[Options#XMLPLAN|XML]].
+
| Toggles the output of the query execution plan, formatted as {{Option|XML}}.
| <code>[[Options#XMLPLAN|XMLPLAN]]</code>
+
| {{Option|XMLPLAN}}
 
| <code>false</code>
 
| <code>false</code>
 
|
 
|
Line 425: Line 421:
 
| {{Code|-X}}
 
| {{Code|-X}}
 
| Generates the query plan before or after query compilation. {{Code|-x}} needs to be activated to make the plan visible.
 
| Generates the query plan before or after query compilation. {{Code|-x}} needs to be activated to make the plan visible.
| <code>[[Options#COMPPLAN|COMPPLAN]]</code>
+
| {{Option|COMPPLAN}}
 
| <code>after</code>
 
| <code>after</code>
 
|
 
|
Line 431: Line 427:
 
| {{Code|-z}}
 
| {{Code|-z}}
 
| Turns the serialization of XQuery results on/off. This flag is useful if the query is profiled or analyzed.
 
| Turns the serialization of XQuery results on/off. This flag is useful if the query is profiled or analyzed.
| <code>[[Options#SERIALIZE|SERIALIZE]]</code>
+
| {{Option|SERIALIZE}}
 
| <code>true</code>
 
| <code>true</code>
 
|
 
|
Line 446: Line 442:
 
</pre>
 
</pre>
  
Available command-line flags can be listed with {{Code|-h}}:
+
You can list the available command-line options using {{Code|-h}}:
 
<pre>
 
<pre>
 
$ basexhttp -h
 
$ basexhttp -h
Line 464: Line 460:
 
</pre>
 
</pre>
  
The flags have the following meaning (equivalent database options are shown in the table as well).
+
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 escaping some characters might be necessary, depending on your Operating System.
+
For the examples to work, it might be necessary to escape some characters depending on your Operating System.
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 482: Line 478:
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-c&lt;input&gt;}}
 
| {{Code|-c&lt;input&gt;}}
| Executes [[commands]]:
+
| Executes [[commands]]. If the specified input is a valid URI or file reference, this file will be evaluated as [[Commands#Command_Scripts|Command Script]].
* Several commands in the input can be separated by semicolons ({{Code|;}}).
 
* If the specified input is a valid URL or file reference, this file will be evaluated as [[Commands#Command_Scripts|Command Script]].
 
 
|
 
|
 
|
 
|
Line 491: Line 485:
 
| {{Code|-d}}
 
| {{Code|-d}}
 
| Turns on the debugging mode. Debugging information is output to ''standard error''.
 
| Turns on the debugging mode. Debugging information is output to ''standard error''.
| <code>[[Options#DEBUG|DEBUG]]</code>
+
| {{Option|DEBUG}}
 
|
 
|
 
|
 
|
Line 503: Line 497:
 
| {{Code|-l}}
 
| {{Code|-l}}
 
| Starts the server in ''local mode'', and executes all commands in the embedded database context.
 
| Starts the server in ''local mode'', and executes all commands in the embedded database context.
| <code>[[Options#HTTPLOCAL|HTTPLOCAL]]</code>
+
| {{Option|HTTPLOCAL}}
 
|
 
|
 
|
 
|
Line 509: Line 503:
 
| {{Code|-n&lt;name&gt;}}
 
| {{Code|-n&lt;name&gt;}}
 
| Specifies the host name on which the server is running.
 
| Specifies the host name on which the server is running.
| <code>[[Options#HOST|HOST]]</code>
+
| {{Option|HOST}}
 
| {{Code|localhost}}
 
| {{Code|localhost}}
 
| {{Code|-nserver.basex.org}}
 
| {{Code|-nserver.basex.org}}
Line 515: Line 509:
 
| {{Code|-p&lt;port&gt;}}
 
| {{Code|-p&lt;port&gt;}}
 
| Specifies the port on which the database server will be addressable.
 
| Specifies the port on which the database server will be addressable.
| <code>[[Options#SERVERPORT|SERVERPORT]]</code>
+
| {{Option|SERVERPORT}}
 
| {{Code|1984}}
 
| {{Code|1984}}
 
| {{Code|-p9998}}
 
| {{Code|-p9998}}
Line 521: Line 515:
 
| {{Code|-s&lt;port&gt;}}
 
| {{Code|-s&lt;port&gt;}}
 
| Specifies the port that will be used to stop the HTTP server.
 
| Specifies the port that will be used to stop the HTTP server.
| <code>[[Options#STOPPORT|STOPPORT]]</code> or<br/><code>pom.xml</code>
+
| {{Option|STOPPORT}} or<br/><code>pom.xml</code>
 
| <code>8985</code>
 
| <code>8985</code>
 
|
 
|
Line 532: Line 526:
 
| {{Code|-U&lt;name&gt;}}
 
| {{Code|-U&lt;name&gt;}}
 
| Specifies a user name, which will be used by the HTTP services for opening a new session.
 
| Specifies a user name, which will be used by the HTTP services for opening a new session.
| <code>[[Options#USER|USER]]</code>
+
| {{Option|USER}}
 
|
 
|
 
| {{Code|-Uadmin}}
 
| {{Code|-Uadmin}}
Line 538: Line 532:
 
| {{Code|-z}}
 
| {{Code|-z}}
 
| Prevents the generation of [[Logging|log files]].
 
| Prevents the generation of [[Logging|log files]].
| <code>[[Options#LOG|LOG]]</code>
+
| {{Option|LOG}}
 
|
 
|
 
|}
 
|}

Revision as of 12:59, 11 July 2019

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 argument.

Standalone

Launch the standalone (console) mode
$ basex
BaseX [Standalone]
Try "help" to get more information.
> _

You can list the command-line options available for the standalone mode using -h:

$ 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
  -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
  -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 chopping
  -x         Toggle output of query plan
  -z         Toggle output of query result

The meaning of all options is 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 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 to the default namespace, it can be specified with the Clark Notation. BINDINGS -bv=example "declare variable $v external; $v"
-b{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 will be evaluated as Command Script. -c list
-ccommands.txt
-c"<info/>"
-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> Executes the specified string as XQuery expression. -q"doc('input')//head"
-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
-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 chopping of XML text nodes. By default, whitespaces will be chopped. CHOP true
-x Toggles the output of the query execution plan, formatted as XML. XMLPLAN false
-X Generates the query plan before or after query compilation. -x needs to be activated to make the plan visible. COMPPLAN true
-z Turns the serialization of XQuery results on/off. This flag is useful if the query is profiled or analyzed. SERIALIZE true

GUI

Launch the GUI

The basexgui command has only one option. You can pass one or more XML and XQuery files as parameters. If an XML file is specified, a database instance is created from this file, or an existing database is opened. XQuery files are opened in the XQuery editor.

$ basexgui [file]

Server

Launch the server
$ basexserver
BaseX [Server]
Server was started (port: 1984)

You can list the available command-line options using -h:

$ basexserver -h
BaseX [Server]
Usage: basexserver [-cdnpSz] [stop]
  stop       Stop running server
  -c<input>  Execute commands from file or string
  -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

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 database server instance and quits.
-c<input> Executes commands. If the specified input is a valid URI or file reference, this file will be evaluated as Command Script. -c"open database;info"
-d Turns on the debugging mode. 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

Launch the console mode communicating with the server

The user name and password will be requested. The default user/password combination is admin/admin:

$ basexclient
Username: admin
Password: *****
BaseX [Client]
Try "help" to get more information.
> _

You can list the available command-line options using -h:

$ 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
  -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
  -r<num>    Run query multiple times
  -R         Toggle query execution
  -s<args>   Set serialization parameters
  -U<name>   Specify user name
  -v         Toggle output of progress info
  -V         Toggle detailed query output
  -w         Toggle whitespace chopping
  -x         Toggle output of query plan
  -z         Toggle output of query result

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
[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 to the default namespace, it can be specified with the Clark Notation or Expanded QName Notation. BINDINGS -b$v=example "declare variable $v external; $v"
-b{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/>"
-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 specified with this flag, it may get visible to others. PASSWORD -Uadmin -Padmin
-q<expr> Executes the specified string as XQuery expression. -q"1+2"
-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 user name. If this flag is omitted, the user name 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 chopping of XML text nodes. By default, whitespaces will be chopped. CHOP chop
-x Toggles the output of the query execution plan, formatted as XML. XMLPLAN false
-X Generates the query plan before or after query compilation. -x needs to be activated to make the plan visible. COMPPLAN after
-z Turns the serialization of XQuery results on/off. This flag is useful if the query is profiled or analyzed. SERIALIZE true

HTTP Server

Launch the HTTP server
$ basexhttp
BaseX [Server]
Server was started (port: 1984)
HTTP Server was started (port: 8984)

You can list the available command-line options using -h:

$ basexhttp -h
BaseX [HTTP]
Usage: basexhttp [-cdhlnpsSUz] [stop]
  stop       Stop running server
  -c<input>  Execute commands from file or string
  -d         Enable debugging output
  -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 user name
  -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 will be evaluated as Command Script. -c"open database"
-d Turns on the debugging mode. Debugging information is output to standard error. DEBUG
-h<port> Specifies the port on which the HTTP server will be addressable. jetty.xml 8984 -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
8985
-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 user name, which will be used by the HTTP services for opening a new session. USER -Uadmin
-z Prevents the generation of log files. LOG

Changelog

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.