Chapter 4. Getting Started with Qizx/open
Prev | Part II. User's Guide | Next

## Chapter 4. Getting Started with Qizx/open

This section is a simplified version of the tutorial found in Chapter 4, Getting Started with Qizx/open.

To help experimenting and developing with XML Query, Qizx/open comes with two tools which make it easy to write and execute XML Query scripts:

Qizx Studio

  A graphic tool featuring a simple XML Query workbench with which you can write and execute XML Query scripts, and view the results.

qizx

  A command-line tool which can be used to execute XML Query script files.

## 1. Writing and running queries with Qizx Studio

Qizx Studio currently provides a basic environment for editing and running XML Query queries.

### Starting Qizx Studio

- On Windows, the directory bin inside the Qizx distribution contains an executable qizxstudio.exe (or qizxstudio.bat), that can be started directly by a double-click,

- On Linux or Mac OS X or other Unix, the shell script bin/qizxstudio can be started from a terminal or from a graphical file manager.

  Note that when started from a console, Qizx Studio accepts command-line arguments, for example to directly load a XML Query script in the editor. See the reference documentation.

You should then see a window looking like this:

Figure 4.1. Qizx Studio first launch

### Note

In contrast with Qizx, there is only one tab in Qizx/open Studio: "XQuery" for entering and running queries.

Let us try this query (which is the contents of the file `qizxopen/queries/4.xq`):

    (: Find all books written by French authors. :)
    declare namespace t = "http://www.qizx.com/namespace/Tutorial";

    declare variable $authors := collection("../../book_data/Authors/*.xml");
    declare variable $books := collection("../../book_data/Books/*.xml");

    for $a in $authors//t:author[@nationality = "France"]
       for $b in $books//t:book[.//t:author = $a/t:fullName]
    return
        $b/t:title

Note that the directory `docs/samples/programming/qizxopen/queries` contains the queries needed to illustrate this lesson.

- Use the menu File → Open XQuery to load the file mentioned above.

  Note that you can also save to a file a query that you have entered or edited in Qizx Studio.

  There is an history that allows running again former queries, so it is not necessary to save intermediary experiments.

- Then you can use the button Execute to run the query.

  ### Important

  The query above uses relative paths for the `collection()` function. Depending how you launched Qizx Studio, you might have to replace the relative paths by absolute paths, otherwise you will get an error like "`empty collection ../../book_data/Authors/*.xml`".

  After execution, we should obtain something similar to this:

  Figure 4.2. Result of a query

- Notice that, in the picture above, the display mode of the right-side view has been changed to "Data Model", by using the View combo-box. This makes it easier to see the Data Model structure.

  The result sequence contains one item, which is a element `t:title` whose string value is "`Planet of the Apes`".

  If for example we change the value "`France`" to "`US`" in the query, then we get a sequence of 8 items.

  In the same directory there are a few other queries that you can also try.

- The result items in the right-side view can be exported into a file using a button in the header. Notice that the resulting file will not in general be a well-formed XML document.

- The Diagnostic view at bottom left contains messages, which can be simple information (execution times) or possible execution errors.

  Compilation and execution errors have generally a link to the location in the source code. By clicking the link, the cursor moves to the location of the error in the editor view.

- For more information about the editor and the query history, please see the documentation of Qizx Studio.

## 2. Running queries with the qizx command line tool

The shell script `qizx` (`qizx.bat` on Windows) is also located in the `bin/` directory in the Qizx distribution. In the following we assume that this `bin/` directory is in the `PATH` environment variable.

In a terminal window, type the following command (the current directory is assumed to be `docs/samples/programming/qizxopen)`:

    qizx queries/4.xq

Results are displayed on the console (or standard output) by default. The option `-out` specifies an output file. Serialization options can be used to specify the output format.

The details of option switches can be found in the tool reference qizx(1).

Prev | Up | Next
Part II. User's Guide | Home | Part III. Developer's Guide