Previous Up Next

Chapter 5  Command Line Tools

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

The Galax XQuery interpreter.
XML document parser and validator.
XML Schema validator. Outputs XML Schema in XQuery type system.
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

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.

Display this list of options

5.1.1  Input options

Sets the default base URI in the static context
x=literal, Binds the global variable x to literal constant
x=filename, Binds the global variable x to document in filename
Binds the context item (“.” variable) to the document in filename or ’-’ for stdin
Load the context query from file or ’-’ for stdin
Preserves whitespace in XML documents [on/off]
Preserves PI’s and comments in XML documents [on/off]

5.1.2  Output options

Set serialization kind [wf, canonical, or xquery]

5.1.3  Evaluation options

Evaluation phase [on/off]
All files are assumed to be normalized expressions for execution [on/off]
All files are assumed to be logical plans for execution [on/off]
Print XML result [on/off]
Output XML to result file
Print input expression [on/off]
Output expr to file.

5.1.4  Normalization options

Normalization phase [on/off]
Print normalized expression [on/off]
Output normalized expression to file.

5.1.5  Static typing options

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

5.1.6  Rewriting options

Rewriting phase (use with -static on) [on/off]
Document-order/duplicate-elimination optimization behavior [remove, preserve, sloppy, tidy, duptidy]
Remove all distinct-docorder (ddo) calls from the query plan. May result in faulty evaluation plans.
Preserve all distinct-doc-order calls (no optimization).
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.
Removes all distinct-doc-order operations hat can be removed while maintaining duplicate-freeness and doc-order after each step.
Only sorts and removes duplicates after a step if duplicates are generated. Intermediate results can be out of document order.
Print rewritten expression [on/off]
Output rewritten expression to file.

5.1.7  Factorization options

Factorization phase [on/off]
Print factorized expression [on/off]
Output factorized expression to file.

5.1.8  Compilation options

Print compilation annotations [on/off]
Print logical plan [on/off]
Output logical plan to file.

5.1.9  Optimization options

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

5.1.10  Miscellaneous printing options

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

5.1.11  Document projection options

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

5.1.12  Miscellaneous options

Prints the Galax version
Emit debugging [on/off]
Monitors memory and CPU consumption [on/off]
Monitors memory consumption [on/off]
Monitors CPU consumption [on/off]
Output monitor actibity to file
Set the input character encoding representation, e.g., utf8, iso88591.
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

Display this list of options
Preserves whitespace in XML documents
Preserves PI’s and comments in XML documents
Set validation on
Schema against which to perform validation
Also builds the data model instance
Monitors memory and CPU consumption
Monitors memory consumption
Monitors CPU consumption
Output monitor to file
Set serialization of namespace nodes [strip/preserve]
Set serialization kind [canonical, wf, or xquery]
Print only the error code instead of the full error message
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

Namespace prefix
Set printing to verbose
Set XML Schema import
Set XQuery type normalization
Set printing ofXQuery type
Set printing of normalized XQuery type
Output XQuery type in file
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