Chapter 5 Command Line Tools

Galax supports the following stand-alone command-line tools:

galax-run: The Galax XQuery interpreter.
galax-parse: XML document parser and validator.
galax-mapschema: XML Schema validator. Outputs XML Schema in XQuery type system.
galaxd: The Galax network server. Executes Galax query plans issued from remote client (Under development).

5.1 `galax-run` : The Galax XQuery interpreter

The simplest way to use Galax is by calling the ’galax-run’ interpreter from the command line. The interpreter takes an XQuery input file, evaluates it, and yields the result on standard output.

Usage: galax-run options query.xq

For instance, the following commands from the Galax home directory:

%  echo "<two>  1+1  </two>" > test.xq
%  $(GALAXHOME)/bin/galax-run test.xq
<two>2</two>

evaluates the simple query <two> { 1+1 } </two> and prints the XML value <two>2</two>.

The query interpreter has eight processing stages: parsing an XQuery expression; normalizing an XQuery expression into an XQuery core expression; static typing of a core expression; rewriting a core expression; factorizing a core expression; compiling a core expression into a logical plan; selecting a physical plan from a logical plan; and evaluating a physical plan.

Parsing, factorization, and compilation are always enabled. By default, the other phases are:

   -normalize on 
   -static off   
   -rewriting on 
   -optimization on
   -dynamic on

By default, all result values (XML result, inferred type, etc.) are written to standard output.

The command line options permit various combinations of phases, printing intermediate expressions, and redirecting output to multiple output files. Here are the available options. Default values are in code font.

-help,–help: Display this list of options

5.1.1 Input options

-base-uri: Sets the default base URI in the static context
-var: x=literal, Binds the global variable x to literal constant
-doc: x=filename, Binds the global variable x to document in filename
-context-item: Binds the context item (“.” variable) to the document in filename or ’-’ for stdin
-context: Load the context query from file or ’-’ for stdin

-xml-whitespace: Preserves whitespace in XML documents [on/off]
-xml-pic: Preserves PI’s and comments in XML documents [on/off]

5.1.2 Output options

-serialize: Set serialization kind [wf, canonical, or xquery]

5.1.3 Evaluation options

-dynamic: Evaluation phase [on/off]
-execute-normalized-expr: All files are assumed to be normalized expressions for execution [on/off]
-execute-logical-plan: All files are assumed to be logical plans for execution [on/off]
-print-xml: Print XML result [on/off]
-output-xml: Output XML to result file
-print-expr: Print input expression [on/off]
-output-expr: Output expr to file.

5.1.4 Normalization options

-normalize: Normalization phase [on/off]
-print-normalized-expr: Print normalized expression [on/off]
-output-normalized-expr: Output normalized expression to file.

5.1.5 Static typing options

-static: Static analysis phase [on/off]
-typing: Static typing behavior [none, weak, or strong]
-print-type: Print type of expression [on/off]
-output-type: Output type to file.
-print-typed-expr: Print typed expression [on/off]
-output-typed-expr: Output typed expression to file.

5.1.6 Rewriting options

-rewriting

Rewriting phase (use with -static on) [on/off]

-sbdo

Document-order/duplicate-elimination optimization behavior [remove, preserve, sloppy, tidy, duptidy]

remove: Remove all distinct-docorder (ddo) calls from the query plan. May result in faulty evaluation plans.
preserve: Preserve all distinct-doc-order calls (no optimization).
sloppy: Delay duplicate removal and sorting until the last step in the path expression. May cause the number of duplicates in intermediate results to increase exponentially since they are not removed. Also, subsequent steps are evaluated multiple times when duplicates are generated in a step.
tidy: Removes all distinct-doc-order operations hat can be removed while maintaining duplicate-freeness and doc-order after each step.
duptidy: Only sorts and removes duplicates after a step if duplicates are generated. Intermediate results can be out of document order.

-print-rewritten-expr

Print rewritten expression [on/off]

-output-rewritten-expr

Output rewritten expression to file.

5.1.7 Factorization options

-factorization: Factorization phase [on/off]
-print-factorized-expr: Print factorized expression [on/off]
-output-factorized-expr: Output factorized expression to file.

5.1.8 Compilation options

-print-comp-annotations: Print compilation annotations [on/off]
-print-logical-plan: Print logical plan [on/off]
-output-logical-plan: Output logical plan to file.

5.1.9 Optimization options

-optimization: Optimization phase [on/off]
-nested-loop-join: Turns off sort/hash joins and uses only nested-loop joins [on/off]
-print-optimized-plan: Print optimized plan [on/off]
-output-optimized-plan: Output optimized plan to file
-print-physical-plan: Print physical plan [on/off]
-output-physical-plan: Output physical algebraic plan to file

5.1.10 Miscellaneous printing options

-verbose: Emit descriptive headers in output [on/off]
-print-global: Prints everything : prologs, exprs, etc.
-output-all: Output everything to file.
-print-error-code: Print only the error code instead of the full error message
-output-err: Redirect error output to file.
-print-context-item: Serializes the context item at the end of query evaluation
-output-context-item: Output the context item to the given file
-print-annotations: Print expression annotations [on/off]
-print-prolog: Print query prolog [on/off]
-print-materialize: Print whenever data materialization occurs [on/off]
-force-materialized: Force materialization of values in variables [on/off]

5.1.11 Document projection options

-projection: Document projection behavior [none, standard, or optimized]
-print-projection: Prints the projection paths
-output-projection: Output the projections paths to a file.
-print-projected-file: Prints back the input document after projection
-output-projected-file: Output the input document after projection into file.

5.1.12 Miscellaneous options

-version: Prints the Galax version
-debug: Emit debugging [on/off]
-monitor: Monitors memory and CPU consumption [on/off]
-monitor-mem: Monitors memory consumption [on/off]
-monitor-time: Monitors CPU consumption [on/off]
-output-monitor: Output monitor actibity to file
-internal-encoding: Set the input character encoding representation, e.g., utf8, iso88591.
-output-encoding: Set the output character encoding representation

5.2 `galax-parse`: XML parser and XML Schema validator

galax-parse parses an XML document and optionally validates the document against an XML Schema.

Usage: galax-parse options document.xml

-help,–help: Display this list of options
-xml-whitespace: Preserves whitespace in XML documents
-xml-pic: Preserves PI’s and comments in XML documents
-validate: Set validation on
-xmlschema: Schema against which to perform validation
-dm: Also builds the data model instance
-monitor: Monitors memory and CPU consumption
-monitor-mem: Monitors memory consumption
-monitor-time: Monitors CPU consumption
-output-monitor: Output monitor to file
-serialize-namespaces: Set serialization of namespace nodes [strip/preserve]
-serialize: Set serialization kind [canonical, wf, or xquery]
-print-error-code: Print only the error code instead of the full error message
-output-encoding: Set the output encoding representation

5.3 `galax-mapschema` : XML Schema validator

galax-mapschema maps XML schemas in xmlschema(s) into XQuery type expressions.

Usage: galax-mapschema options schema.xsd

-prefix: Namespace prefix
-verbose: Set printing to verbose
-import-type: Set XML Schema import
-normalize-type: Set XQuery type normalization
-print-type: Set printing ofXQuery type
-print-normalized-type: Set printing of normalized XQuery type
-output-type: Output XQuery type in file
-output-normalized-type: Output normalized XQuery type in file

5.4 `galaxd` : The Galax network server

galaxd is a server that allows Galax to be invoked over the network.

Usage: galaxd [options] [query.xq]

-port n: Listen on port n. If the -port option is not used, the port defaults to 3324.
-s dir: Simulate the directory dir. The server will act as if it is a part of a virtual network specified by dir. Each file host.xq in dir defines a server host in the virtual network. The virtual network is implemented on the localhost at ports 3324, 3325, …. Ports are assigned to the host.xq files in lexicographic order.

The query file query.xq should define a function named local:main(). An XQuery program can get the result of local:main() on host by calling doc("dxq://host/"). If the server is using a non-default port port, then use doc("dxq://host:port/").

5.4.1 Running simulations

It is sometimes useful to simulate a network of Galax servers on a single host. The -s option makes this possible. The way to set this up is to create a directory with a query file for each simulated host. For example, create a directory example with query files a.xq, b.xq, and c.xq. Each .xq file should define a local:main() function. Also, these files can refer to each other’s local:main() functions using doc("dxq://a/"), doc("dxq://b/"), and doc("dxq://c/"). Then start up the three servers as follows:

     galaxd -s example -port 3324
     galaxd -s example -port 3325
     galaxd -s example -port 3326

galaxd uses the -s option to find out what the virtual network will look like: it will have hosts a, b, and c, operating on non-virtual ports 3324, 3325, and 3326 on localhost. The first invocation of galaxd above uses port 3324, so it uses a.xq to define its local:main() function. Similarly, the second and third invocations use b.xq and c.xq, respectively.