Difference between revisions of "Command-Line Options"
m (moved Startup Options to Command-Line Options) |
m (Fixed wiki syntax for links) |
||
(44 intermediate revisions by 4 users not shown) | |||
Line 2: | Line 2: | ||
It gives more details on the command-line options of all BaseX [[Startup]] modes. | It gives more details on the command-line options of all BaseX [[Startup]] modes. | ||
− | Options can be specified multiple times. | + | 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= |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
;Launch the console mode: | ;Launch the console mode: | ||
<pre> | <pre> | ||
Line 24: | Line 17: | ||
$ basex -h | $ basex -h | ||
BaseX [Standalone] | BaseX [Standalone] | ||
− | Usage: basex [- | + | Usage: basex [-bcdiLoqrRsuvVwxXz] [input] |
[input] Execute input file or expression | [input] Execute input file or expression | ||
-b<pars> Bind external query variables | -b<pars> Bind external query variables | ||
-c<input> Execute commands from file or string | -c<input> Execute commands from file or string | ||
-d Activate debugging mode | -d Activate debugging mode | ||
− | -i<input> Open | + | -i<input> Open XML file or database |
− | - | + | -I<input> Assign input string to context |
-o<output> Write output to file | -o<output> Write output to file | ||
-q<expr> Execute XQuery expression | -q<expr> Execute XQuery expression | ||
+ | -r<num> Set number of query executions | ||
+ | -R Turn query execution on/off | ||
-s<pars> Set serialization parameter(s) | -s<pars> Set serialization parameter(s) | ||
+ | -t[path] Run tests in file or directory | ||
-u Write updates back to original files | -u Write updates back to original files | ||
-v/V Show (all) process info | -v/V Show (all) process info | ||
-w Preserve whitespaces from input files | -w Preserve whitespaces from input files | ||
-x Show query execution plan | -x Show query execution plan | ||
+ | -X Show query plan before/after compilation | ||
-z Skip output of results | -z Skip output of results | ||
</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 [[Commands#SET|SET]] 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 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. |
{| class="wikitable" | {| class="wikitable" | ||
Line 48: | Line 45: | ||
! width="40%" | Description | ! width="40%" | Description | ||
! Option | ! Option | ||
+ | ! Default | ||
! Examples | ! Examples | ||
|- valign="top" | |- valign="top" | ||
| {{Code|[input]}} | | {{Code|[input]}} | ||
|Evaluates the specified input: | |Evaluates the specified input: | ||
− | * The input string may point to an existing file. If the file suffix is {{Code|.bxs}}, the file | + | * 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]]; otherwise, it will be evaluated as XQuery expression. |
* Otherwise, the input string itself is 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/> | |• {{Code|"doc('X')//head"}}<br/>• {{Code|query.xq}}<br/>• {{Code|commands.bxs}}<br/> | ||
Line 60: | Line 59: | ||
| 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> | | <code>[[Options#BINDINGS|BINDINGS]]</code> | ||
− | |• <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<input>}} | | {{Code|-c<input>}} | ||
| Executes [[Commands]]: | | Executes [[Commands]]: | ||
* Several commands in the input can be separated by semicolons ({{Code|;}}). | * Several commands in the input can be separated by semicolons ({{Code|;}}). | ||
− | * If the specified input is a valid file reference | + | * 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;info"}}<br/>• {{Code|-ccommands.txt}}<br/>• {{Code|-c"<info/>"}} | ||
Line 72: | Line 73: | ||
| 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> | | <code>[[Options#DEBUG|DEBUG]]</code> | ||
+ | | <code>false</code> | ||
| | | | ||
|- valign="top" | |- valign="top" | ||
| {{Code|-i<input>}} | | {{Code|-i<input>}} | ||
− | | Opens | + | | Opens an XML file or database specified by the argument. The opened input can then be processed by a command or XQuery expression. |
+ | | | ||
| | | | ||
| {{Code|-iitems.xml "//item"}} | | {{Code|-iitems.xml "//item"}} | ||
|- valign="top" | |- valign="top" | ||
− | | {{Code|- | + | | {{Code|-I<input>}} |
− | | | + | | Assigns an input string as item of type {{Code|xs:untypedAtomic}} to the query context. |
| | | | ||
| | | | ||
+ | | {{Code|-I "Hello Universe" -q "."}} | ||
|- valign="top" | |- valign="top" | ||
| {{Code|-o<file>}} | | {{Code|-o<file>}} | ||
| All command and query output is written to the specified file. | | All command and query output is written to the specified file. | ||
+ | | | ||
| | | | ||
| {{Code|-o output.txt}} | | {{Code|-o output.txt}} | ||
Line 91: | Line 96: | ||
| {{Code|-q<expr>}} | | {{Code|-q<expr>}} | ||
| Executes the specified string as XQuery expression. | | Executes the specified string as XQuery expression. | ||
+ | | | ||
| | | | ||
| {{Code|-q"doc('input')//head"}} | | {{Code|-q"doc('input')//head"}} | ||
+ | |- valign="top" | ||
+ | | {{Code|-r<num>}} | ||
+ | | Specifies how often a specified query will be evaluated. | ||
+ | | <code>[[Options#RUNS|RUNS]]</code> | ||
+ | | <code>1</code> | ||
+ | | {{Code|-V -r10 "1"}} | ||
+ | |- valign="top" | ||
+ | | {{Code|-R}} | ||
+ | | Specifies if a query will be executed or parsed only. | ||
+ | | <code>[[Options#RUNQUERY|RUNQUERY]]</code> | ||
+ | | <code>true</code> | ||
+ | | {{Code|-V -R "1"}} | ||
|- valign="top" | |- valign="top" | ||
| {{Code|-s<pars>}} | | {{Code|-s<pars>}} | ||
| 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> | | <code>[[Options#SERIALIZER|SERIALIZER]]</code> | ||
+ | | | ||
| <code>-smethod=text</code> | | <code>-smethod=text</code> | ||
+ | |- valign="top" | ||
+ | | {{Code|-t}} | ||
+ | | Runs all [[Unit Module|Unit tests]] in the specified file or directory. | ||
+ | | | ||
+ | | | ||
+ | | -t project/tests | ||
|- valign="top" | |- valign="top" | ||
| {{Code|-u}} | | {{Code|-u}} | ||
− | | | + | | Propagates updates on input files back to disk. |
| <code>[[Options#WRITEBACK|WRITEBACK]]</code> | | <code>[[Options#WRITEBACK|WRITEBACK]]</code> | ||
+ | | <code>false</code> | ||
| | | | ||
|- valign="top" | |- valign="top" | ||
Line 107: | Line 133: | ||
| Prints process and timing information to the ''standard output''. | | Prints process and timing information to the ''standard output''. | ||
| | | | ||
+ | | <code>false</code> | ||
| | | | ||
|- valign="top" | |- valign="top" | ||
Line 112: | Line 139: | ||
| 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> | | <code>[[Options#QUERYINFO|QUERYINFO]]</code> | ||
+ | | <code>false</code> | ||
| | | | ||
|- valign="top" | |- valign="top" | ||
| {{Code|-w}} | | {{Code|-w}} | ||
− | | | + | | Specifies if whitespaces in XML text nodes should be chopped (which is the default) or preserved. |
| <code>[[Options#CHOP|CHOP]]</code> | | <code>[[Options#CHOP|CHOP]]</code> | ||
+ | | <code>true</code> | ||
| | | | ||
|- valign="top" | |- valign="top" | ||
Line 122: | Line 151: | ||
| This flags turn on the output of the query execution plan, formatted in [[Options#XMLPLAN|XML]]. | | This flags turn on the output of the query execution plan, formatted in [[Options#XMLPLAN|XML]]. | ||
| <code>[[Options#XMLPLAN|XMLPLAN]]</code> | | <code>[[Options#XMLPLAN|XMLPLAN]]</code> | ||
+ | | <code>false</code> | ||
+ | | | ||
+ | |- valign="top" | ||
+ | | {{Code|-X}} | ||
+ | | 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> | ||
+ | | <code>true</code> | ||
| | | | ||
|- valign="top" | |- valign="top" | ||
| {{Code|-z}} | | {{Code|-z}} | ||
− | | | + | | Turns the serialization of XQuery results on/off. This flag is useful if the query is profiled or analyzed. |
| <code>[[Options#SERIALIZE|SERIALIZE]]</code> | | <code>[[Options#SERIALIZE|SERIALIZE]]</code> | ||
+ | | <code>true</code> | ||
| | | | ||
|} | |} | ||
− | = | + | =Server= |
+ | |||
+ | {{Mark|Updated with Version 9.0:}} {{Code|-c}} flag now accepts valid URLs and file references. | ||
+ | |||
;Launch the server | ;Launch the server | ||
<pre> | <pre> | ||
Line 142: | Line 182: | ||
$ basexserver -h | $ basexserver -h | ||
BaseX [Server] | BaseX [Server] | ||
− | Usage: basexserver [- | + | Usage: basexserver [-cdinpSz] [stop] |
− | stop | + | stop Stop running server |
− | -c< | + | -c<input> Execute commands from file or string |
− | -d | + | -d Activate debugging mode |
− | + | -n<name> Set host the server is bound to | |
− | + | -p<port> Set server port | |
− | -n<name> | + | -S Start as service |
− | -p<port> | + | -z Suppress logging |
− | -S | ||
− | -z | ||
</pre> | </pre> | ||
Line 166: | Line 204: | ||
|- valign="top" | |- valign="top" | ||
| {{Code|stop}} | | {{Code|stop}} | ||
− | | Stops | + | | Stops a local database server instance and quits. |
| | | | ||
| | | | ||
|- valign="top" | |- valign="top" | ||
| {{Code|-c<cmd>}} | | {{Code|-c<cmd>}} | ||
− | | | + | | Executes [[Commands]]: |
+ | * 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 179: | Line 219: | ||
| 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> | | <code>[[Options#DEBUG|DEBUG]]</code> | ||
− | + | | <code>false</code> | |
− | |||
− | |||
− | |||
− | |||
− | | <code> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
| | | | ||
|- valign="top" | |- valign="top" | ||
| {{Code|-n<name>}} | | {{Code|-n<name>}} | ||
− | | Specifies the host the server will be bound to. | + | | Specifies the host the server will be bound to. |
| <code>[[Options#SERVERHOST|SERVERHOST]]</code> | | <code>[[Options#SERVERHOST|SERVERHOST]]</code> | ||
| | | | ||
Line 207: | Line 235: | ||
|- valign="top" | |- valign="top" | ||
| {{Code|-S}} | | {{Code|-S}} | ||
− | | Starts the server as service (i.e., in the 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. |
| | | | ||
| | | | ||
Line 214: | Line 242: | ||
| Does not generate any [[Logging|log files]]. | | Does not generate any [[Logging|log files]]. | ||
| <code>[[Options#LOG|LOG]]</code> | | <code>[[Options#LOG|LOG]]</code> | ||
+ | | <code>true</code> | ||
| | | | ||
|} | |} | ||
Line 219: | Line 248: | ||
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. | 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= |
;Launch the console mode communicating with the server | ;Launch the console mode communicating with the server | ||
Line 237: | Line 266: | ||
$ basexclient -h | $ basexclient -h | ||
BaseX [Client] | BaseX [Client] | ||
− | Usage: basexclient [- | + | Usage: basexclient [-bcdiLnopPqrRsUvVwxXz] [input] |
[input] Execute input file or expression | [input] Execute input file or expression | ||
-b<pars> Bind external query variables | -b<pars> Bind external query variables | ||
-c<input> Execute commands from file or string | -c<input> Execute commands from file or string | ||
-d Activate debugging mode | -d Activate debugging mode | ||
− | -i<input> Open | + | -i<input> Open XML file or database |
− | - | + | -I<input> Assign input string to context |
-n<name> Set server (host) name | -n<name> Set server (host) name | ||
-o<output> Write output to file | -o<output> Write output to file | ||
Line 249: | Line 278: | ||
-P<pass> Specify user password | -P<pass> Specify user password | ||
-q<expr> Execute XQuery expression | -q<expr> Execute XQuery expression | ||
+ | -r<num> Set number of query executions | ||
+ | -R Turn query execution on/off | ||
-s<pars> Set serialization parameter(s) | -s<pars> Set serialization parameter(s) | ||
-U<name> Specify user name | -U<name> Specify user name | ||
Line 254: | Line 285: | ||
-w Preserve whitespaces from input files | -w Preserve whitespaces from input files | ||
-x Show query execution plan | -x Show query execution plan | ||
+ | -X Show query plan before/after compilation | ||
-z Skip output of results | -z Skip output of results | ||
</pre> | </pre> | ||
Line 259: | Line 291: | ||
The flags have the following meaning (equivalent database options are shown in the table as well). | The flags have the following meaning (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 escaping some characters might be necessary, depending on your Operating System. | ||
− | |||
{| class="wikitable" | {| class="wikitable" | ||
Line 271: | Line 302: | ||
| {{Code|[input]}} | | {{Code|[input]}} | ||
|Evaluates the specified input: | |Evaluates the specified input: | ||
− | * The input string may point to an existing file. If the file suffix is {{Code|.bxs}}, the file | + | * 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]]; otherwise, it will be evaluated as XQuery expression. |
* Otherwise, the input string itself is evaluated as XQuery expression. | * Otherwise, the input string itself is evaluated as XQuery expression. | ||
| | | | ||
Line 281: | Line 312: | ||
| <code>[[Options#BINDINGS|BINDINGS]]</code> | | <code>[[Options#BINDINGS|BINDINGS]]</code> | ||
| | | | ||
− | |• <code>-b$v=example "$v"</code><br/>• <code>-b{URL}ln=value<br/>"declare namespace ns='URL'; $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<input>}} | | {{Code|-c<input>}} | ||
Line 294: | Line 325: | ||
| 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> | | <code>[[Options#DEBUG|DEBUG]]</code> | ||
− | | | + | | <code>false</code> |
| | | | ||
|- valign="top" | |- valign="top" | ||
| {{Code|-i<input>}} | | {{Code|-i<input>}} | ||
− | | Opens | + | | Opens an XML file or database specified by the argument. The opened input can then be processed by a command or XQuery expression. |
| | | | ||
| | | | ||
| {{Code|-iitems.xml "//item"}} | | {{Code|-iitems.xml "//item"}} | ||
|- valign="top" | |- valign="top" | ||
− | | {{Code|- | + | | {{Code|-I<input>}} |
− | | | + | | Assigns an input string as item of type {{Code|xs:untypedAtomic}} to the query context. |
| | | | ||
| | | | ||
+ | | {{Code|-I "Hello Universe" -q "."}} | ||
|- valign="top" | |- valign="top" | ||
| {{Code|-n<name>}} | | {{Code|-n<name>}} | ||
Line 336: | Line 368: | ||
| | | | ||
| {{Code|-q"doc('input')//head"}} | | {{Code|-q"doc('input')//head"}} | ||
+ | |- valign="top" | ||
+ | | {{Code|-r<num>}} | ||
+ | | Specifies how often a specified query will be evaluated. | ||
+ | | <code>[[Options#RUNS|RUNS]]</code> | ||
+ | | <code>1</code> | ||
+ | | {{Code|-V -r10 "1"}} | ||
+ | |- valign="top" | ||
+ | | {{Code|-R}} | ||
+ | | Specifies if a query will be executed or parsed only. | ||
+ | | <code>[[Options#RUNQUERY|RUNQUERY]]</code> | ||
+ | | <code>true</code> | ||
+ | | {{Code|-V -R "1"}} | ||
|- valign="top" | |- valign="top" | ||
| {{Code|-s<pars>}} | | {{Code|-s<pars>}} | ||
Line 352: | Line 396: | ||
| Prints process and timing information to the ''standard output''. | | Prints process and timing information to the ''standard output''. | ||
| | | | ||
− | | | + | | <code>false</code> |
| | | | ||
|- valign="top" | |- valign="top" | ||
Line 358: | Line 402: | ||
| 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> | | <code>[[Options#QUERYINFO|QUERYINFO]]</code> | ||
− | | | + | | <code>false</code> |
| | | | ||
|- valign="top" | |- valign="top" | ||
| {{Code|-w}} | | {{Code|-w}} | ||
− | | | + | | Specifies if whitespaces in XML text nodes should be chopped (which is the default) or preserved. |
| <code>[[Options#CHOP|CHOP]]</code> | | <code>[[Options#CHOP|CHOP]]</code> | ||
− | | | + | | <code>chop</code> |
| | | | ||
|- valign="top" | |- valign="top" | ||
Line 370: | Line 414: | ||
| This flags turn on the output of the query execution plan, formatted in [[Options#XMLPLAN|XML]]. | | This flags turn on the output of the query execution plan, formatted in [[Options#XMLPLAN|XML]]. | ||
| <code>[[Options#XMLPLAN|XMLPLAN]]</code> | | <code>[[Options#XMLPLAN|XMLPLAN]]</code> | ||
+ | | <code>false</code> | ||
| | | | ||
+ | |- valign="top" | ||
+ | | {{Code|-X}} | ||
+ | | 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> | ||
+ | | <code>after</code> | ||
| | | | ||
|- valign="top" | |- valign="top" | ||
| {{Code|-z}} | | {{Code|-z}} | ||
− | | | + | | Turns the serialization of XQuery results on/off. This flag is useful if the query is profiled or analyzed. |
| <code>[[Options#SERIALIZE|SERIALIZE]]</code> | | <code>[[Options#SERIALIZE|SERIALIZE]]</code> | ||
− | | | + | | <code>true</code> |
| | | | ||
|} | |} | ||
− | = | + | =HTTP Server= |
+ | |||
+ | {{Mark|Introduced with Version 9.0:}} {{Code|-c}} flag accepts commands and valid URLs and file references. | ||
;Launch the HTTP server: | ;Launch the HTTP server: | ||
Line 394: | Line 446: | ||
$ basexhttp -h | $ basexhttp -h | ||
BaseX [HTTP] | BaseX [HTTP] | ||
− | Usage: basexhttp [- | + | Usage: basexhttp [-dhlnpPRUWz] [stop] |
− | stop | + | stop Stop running server |
− | -d | + | -c<input> Execute commands from file or string |
− | - | + | -d Activate debugging mode |
− | + | -h<port> Set port of HTTP server | |
− | -l | + | -l Start in local mode |
− | -n<name> | + | -n<name> Set host name of database server |
− | -p<port> | + | -p<port> Set port of database server |
− | + | -s<port> Specify port to stop HTTP server | |
− | -s<port> | + | -S Start as service |
− | -S | + | -U<name> Specify user name |
− | -U<name> | + | -z Suppress logging |
− | -z | ||
</pre> | </pre> | ||
The flags have the following meaning (equivalent database options are shown in the table as well). | The flags have the following meaning (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 escaping some characters might be necessary, depending on your Operating System. | ||
− | |||
{| class="wikitable" | {| class="wikitable" | ||
Line 422: | Line 472: | ||
|- valign="top" | |- valign="top" | ||
| {{Code|stop}} | | {{Code|stop}} | ||
− | | Stops a | + | | Stops a local HTTP server and quits. The database server will be stopped as well, unless {{Code|-l}} is specified. |
| <code>pom.xml</code> | | <code>pom.xml</code> | ||
| | | | ||
| | | | ||
+ | |- valign="top" | ||
+ | | {{Code|-c<cmd>}} | ||
+ | | Executes [[Commands]]: | ||
+ | * 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"open database"}} | ||
|- valign="top" | |- valign="top" | ||
| {{Code|-d}} | | {{Code|-d}} | ||
Line 432: | Line 490: | ||
| | | | ||
| | | | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|- valign="top" | |- valign="top" | ||
| {{Code|-h<num>}} | | {{Code|-h<num>}} | ||
Line 462: | Line 514: | ||
| {{Code|1984}} | | {{Code|1984}} | ||
| {{Code|-p9998}} | | {{Code|-p9998}} | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|- valign="top" | |- valign="top" | ||
| {{Code|-s<num>}} | | {{Code|-s<num>}} | ||
| 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> | | <code>[[Options#STOPPORT|STOPPORT]]</code> or<br/><code>pom.xml</code> | ||
− | | <code> | + | | <code>8985</code> |
| | | | ||
|- valign="top" | |- valign="top" | ||
| {{Code|-S}} | | {{Code|-S}} | ||
− | | Starts the server as service (i.e., in the 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. |
| | | | ||
| | | | ||
Line 491: | Line 537: | ||
| | | | ||
|} | |} | ||
+ | |||
+ | =GUI= | ||
+ | ;Launch the GUI: | ||
+ | <pre> | ||
+ | $ basexgui [file] | ||
+ | </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. | ||
=Changelog= | =Changelog= | ||
+ | |||
+ | ;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}}. | ||
;Version 7.7 | ;Version 7.7 | ||
− | * Added: | + | * Added: Bind host to the [[#BaseX Server|BaseX Server]] with {{Code|-n}}. |
;Version 7.5 | ;Version 7.5 | ||
Line 505: | Line 585: | ||
; Version 7.3: | ; Version 7.3: | ||
− | * Updated: all options are now evaluated in the given order | + | * Updated: all options are now evaluated in the given order. |
− | * Updated: {{Code|-i}} | + | * Updated: Create main-memory representations for specified sources with {{Code|-i}}. |
− | * Updated: Options {{Code|-C}}/{{Code|-c}} and {{Code|-q}}/{{Code|[input]}} merged | + | * Updated: Options {{Code|-C}}/{{Code|-c}} and {{Code|-q}}/{{Code|[input]}} merged. |
− | * Updated: Option {{Code|-L}} also separates serialized items with newlines (instead of spaces) | + | * Updated: Option {{Code|-L}} also separates serialized items with newlines (instead of spaces). |
; Version 7.2: | ; Version 7.2: | ||
Line 516: | Line 596: | ||
; Version 7.1.1: | ; Version 7.1.1: | ||
− | * Added: Options {{Code|-C}} and {{Code|-L}} in standalone and client mode | + | * Added: Options {{Code|-C}} and {{Code|-L}} in standalone and client mode. |
; Version 7.1: | ; Version 7.1: | ||
* Updated: Multiple query files and {{Code|-c}}/{{Code|-i}}/{{Code|-q}} flags can be specified. | * Updated: Multiple query files and {{Code|-c}}/{{Code|-i}}/{{Code|-q}} flags can be specified. | ||
− | |||
− |
Revision as of 14:50, 18 April 2018
This article is part of the Getting Started Guide. It gives more details on the command-line options of all BaseX Startup modes.
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 console mode
$ basex BaseX [Standalone] Try "help" to get more information. > _
Available command-line flags can be listed with -h
:
$ basex -h BaseX [Standalone] Usage: basex [-bcdiLoqrRsuvVwxXz] [input] [input] Execute input file or expression -b<pars> Bind external query variables -c<input> Execute commands from file or string -d Activate debugging mode -i<input> Open XML file or database -I<input> Assign input string to context -o<output> Write output to file -q<expr> Execute XQuery expression -r<num> Set number of query executions -R Turn query execution on/off -s<pars> Set serialization parameter(s) -t[path] Run tests in file or directory -u Write updates back to original files -v/V Show (all) process info -w Preserve whitespaces from input files -x Show query execution plan -X Show query plan before/after compilation -z Skip output of results
The meaning of all flags 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 escaping some characters might be necessary, depending on your Operating System.
Flag | Description | Option | Default | Examples |
---|---|---|---|---|
[input]
|
Evaluates the specified input:
|
• "doc('X')//head" • query.xq • commands.bxs | ||
-b<pars>
|
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
| |
-c<input>
|
Executes Commands:
|
• -c"list;info" • -ccommands.txt • -c"<info/>"
| ||
-d
|
Toggles the debugging mode. Debugging information is output to standard error. | DEBUG
|
false
|
|
-i<input>
|
Opens an XML file or database specified by the argument. 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<file>
|
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<pars>
|
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
|
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
|
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
|
Specifies if whitespaces in XML text nodes should be chopped (which is the default) or preserved. | CHOP
|
true
|
|
-x
|
This flags turn on the output of the query execution plan, formatted in 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
|
Server
Template:Mark -c
flag now accepts valid URLs and file references.
- Launch the server
$ basexserver BaseX [Server] Server was started (port: 1984)
Available command-line flags can be listed with -h
:
$ basexserver -h BaseX [Server] Usage: basexserver [-cdinpSz] [stop] stop Stop running server -c<input> Execute commands from file or string -d Activate debugging mode -n<name> Set host the server is bound to -p<port> Set server port -S Start as service -z Suppress logging
The flags have the following meaning (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.
Flag | Description | Option | Default | Examples |
---|---|---|---|---|
stop
|
Stops a local database server instance and quits. | |||
-c<cmd>
|
Executes Commands:
|
-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<num>
|
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
|
Does not generate any 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. > _
Available command-line flags can be listed with -h
:
$ basexclient -h BaseX [Client] Usage: basexclient [-bcdiLnopPqrRsUvVwxXz] [input] [input] Execute input file or expression -b<pars> Bind external query variables -c<input> Execute commands from file or string -d Activate debugging mode -i<input> Open XML file or database -I<input> Assign input string to context -n<name> Set server (host) name -o<output> Write output to file -p<port> Set server port -P<pass> Specify user password -q<expr> Execute XQuery expression -r<num> Set number of query executions -R Turn query execution on/off -s<pars> Set serialization parameter(s) -U<name> Specify user name -v/V Show (all) process info -w Preserve whitespaces from input files -x Show query execution plan -X Show query plan before/after compilation -z Skip output of results
The flags have the following meaning (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.
Flag | Description | Option | Default | Examples |
---|---|---|---|---|
[input]
|
Evaluates the specified input:
|
• "doc('X')//head" • query.xq • commands.bxs | ||
-b<pars>
|
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
| |
-c<input>
|
Executes Commands:
|
• -c"list;info" • -ccommands.txt • -c"<info/>"
| ||
-d
|
Toggles the debugging mode. Debugging information is output to standard error. | DEBUG
|
false
|
|
-i<input>
|
Opens an XML file or database specified by the argument. 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<file>
|
All command and query output is written to the specified file. | |||
-p<num>
|
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"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<pars>
|
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
|
Specifies if whitespaces in XML text nodes should be chopped (which is the default) or preserved. | CHOP
|
chop
|
|
-x
|
This flags turn on the output of the query execution plan, formatted in 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
Template:Mark -c
flag accepts commands and valid URLs and file references.
- Launch the HTTP server
$ basexhttp BaseX [Server] Server was started (port: 1984) HTTP Server was started (port: 8984)
Available command-line flags can be listed with -h
:
$ basexhttp -h BaseX [HTTP] Usage: basexhttp [-dhlnpPRUWz] [stop] stop Stop running server -c<input> Execute commands from file or string -d Activate debugging mode -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 flags have the following meaning (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.
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<cmd>
|
Executes Commands:
|
-c"open database"
| ||
-d
|
Turns on the debugging mode. Debugging information is output to standard error. | DEBUG
|
||
-h<num>
|
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<num>
|
Specifies the port on which the database server will be addressable. | SERVERPORT
|
1984
|
-p9998
|
-s<num>
|
Specifies the port that will be used to stop the HTTP server. | STOPPORT orpom.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
|
Does not generate any log files. | LOG
|
GUI
- Launch the GUI
$ basexgui [file]
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.
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
- Added: Bind host to the BaseX Server with
-n
.
- 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.