Previous Up Next

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.


Previous Up Next