Tamino X-Plorer Version 9.7
 —  Tamino X-Plorer  —

Working with the Tamino XQuery Tool

The following topics are covered below.


Specifying an XQuery

When you specify a query in the XQuery window, you must always provide server, database, collection and the query itself.

Only queries that reference XML doctypes are possible. For queries on non-XML doctypes, use X-Query. See Performing X-Queries with the Tamino X-Plorer.

Start of instruction setTo specify an XQuery

  1. In the Server text box, specify the name of the server on which you want to execute your query.

    You can use the selection icon (graphics/select.png) to open a dialog that lets you navigate to the required server and database. You can also use the option Tools > Connect to Server from the main menu to navigate to the required server and database.

  2. In the Database text box, specify the name of a database of the above server in which you want to execute your query.

  3. In the Collection text box, specify the name of a collection in the above database in which you want to execute your query.

  4. In the query editor below the above text boxes, specify the query. See XQuery 4 User Guide and XQuery 4 Reference Guide in the Tamino XML Server documentation for detailed information.

    You can specify the sorting sequence in your query, for example, with the sort by clause (the sorting sequence specified in the Tamino X-Plorer (instance descriptor) is not applied).

    You can now execute the query as described below. See Executing an XQuery.

    It is also possible to retrieve information about query execution, without executing the query. See Explaining an XQuery.

Top of page

Creating a New XQuery

When you create a new query, any information in the query area is deleted.

Note:
The result of the previous query is not overwritten until you issue the Execute Query or Explain Query command for the new query.

Start of instruction setTo create a new XQuery

  1. From the File menu, choose New.

    Or:
    Press CTRL+N.

    Or:
    Choose the following toolbar button:

    New

    A dialog box appears asking whether you want to save the currently displayed query.

  2. Choose either the Yes or No button.

    When you choose the Yes button and the current query has not yet been saved in a file, the Save As dialog box appears. See Saving an XQuery below.

    The query area is now empty.

  3. Specify a query and choose the Execute Query or Explain Query command

Top of page

Using Templates and the auto-complete Feature

You can use pre-defined XQuery templates and the auto-complete feature to complete your XQuery statements, without much typing effort. Type in the first one or two letters of the word that you want to insert and press CTRL+SPACE. Also notice that the query statement aligns itself automatically.

Top of page

Explaining an XQuery

When you have specified a query, you can use the Explain Query command (which corresponds to ino:explain) to retrieve information about query execution for analysis and optimization. For detailed information on ino:explain, see the X-Query Reference Guide in the Tamino XML Server documentation.

The Explain Query command works in the same way as the Execute Query command. The only difference is that the query is not executed, it is just analyzed.

When the query is sent to the Tamino server, two additional lines, {?explain?} and {?explain preprocessor?}, are inserted at the top of the query. Therefore, all line numbers in the explanation text of the query (in the Result pane and Response pane) are greater by two than in the query editor.

When you request the explanation of a query for a database which has not yet been connected, the Connect dialog box appears and you have to specify all required logon information. See Connecting to a Tamino Database.

Start of instruction setTo explain an XQuery

Top of page

Executing an XQuery

When you have specified a query and want to display the result, you have to execute the query.

When you execute a query for a database which has not yet been connected, the Connect dialog box appears and you have to specify all required logon information. See Connecting to a Tamino Database.

Each new query that is executed overwrites the previous result pack. If you want to save your result pack, see Saving the Current Result Pack.

Note:
Before you execute a query, it is recommended that you retrieve information about query execution using the Explain Query command. See Explaining an XQuery.

Start of instruction setTo execute an XQuery

Top of page

Cancel XQuery Execution

If you execute a query that takes a considerable amount of time, a processing dialog box is displayed, which lets you cancel the query. You just need to choose the Abort button and the query is cancelled.

graphics/xqlcancel_query.png

Top of page

XQuery Scratchpad

In addition to using the Explain Query and Execute Query features as described above, you can select a section of XQuery code from the display and activate the Explain or Execute feature for this selected code section.

Start of instruction setTo execute or explain a section of code from the text input field

  1. Ensure that the text input field contains valid XQuery code.

  2. Select the required section of the displayed XQuery code in the text input field, by moving the cursor to the required first character, then dragging the cursor to the required last character.

  3. From the Tools menu, select either graphics/Run.gif to execute the selected query code, or graphics/ExplainQuery.gif to examine the selected query code.

    The results are then displayed in the Result window.

Top of page

Saving an XQuery in the File System

You can save a query in a file in your file system.

As long as a query has not yet been saved, the name "NewXQuery" is shown in the title bar of the XQuery window. When you save this query for the first time, the Save As dialog box appears in which you have to specify the name of the file in which the query is to be saved in your file system.

Start of instruction setTo save an XQuery under a new name

  1. From the File menu, choose Save As.

    The Save As dialog box appears. File name and extension (.xquery) are automatically provided.

  2. Optionally: specify another file name. Do not change the extension.

  3. Select the path in which you want to save the file.

  4. Choose the Save button.

Start of instruction setTo save a named XQuery

Top of page

Opening a Saved XQuery

You can open a query which you have previously saved in your file system.

Start of instruction setTo open a saved XQuery

  1. From the File menu, choose Open.

    Or:
    Press CTRL+O.

    Or:
    Choose the following toolbar button:

    Open

    A dialog box appears asking whether you want to save the currently displayed query.

  2. Choose either the Yes or No button.

    When you choose the Yes button and the current query has not yet been saved in a file, the Save As dialog box appears. See Saving an XQuery above.

    The Open dialog box appears.

  3. Select the file containing the desired query.

  4. Choose the Open button.

    The previously saved query is now shown in the application window.

Top of page

Inserting an XQuery Expression from a File

You can insert the contents of a text file at the insertion point. This is helpful, for example, if you have received an XQuery expression from another user.

Note:
Do not use this feature to insert a saved XQuery with the extension "xquery". Use the Open command instead (see Opening a Saved XQuery).

Start of instruction setTo insert an XQuery from a file

  1. In the query area, move the insertion point to the position at which you want to insert the contents of the file.

  2. From the Edit menu, choose Insert From File.

    A dialog box appears.

  3. Select the desired file.

  4. Choose the Open button.

    The content of the selected file is now inserted at the insertion point.

Top of page

XQuery Modules

You can save XQuery code as a module in a database and retrieve it at a later time.

If you wish to work with modules, you must activate the module management mode. If this mode is not active, the menu entries and buttons for saving and retrieving modules are greyed out.

Start of instruction setTo activate module management mode

Start of instruction setTo save a module to the database

Start of instruction setTo retrieve a module from the database

When you save a module, it is stored in the doctype ino:module in the collection ino:source of your database.

The Tamino XQuery tool cannot be used to delete XQuery modules in a database. If you wish to delete an XQuery module in a database, use the Tamino X-Plorer instead.

If you wish to deactivate module management mode and return to query mode, proceed as follows:

Start of instruction setTo deactivate module management mode

Top of page

Selecting Text

In order to cut, copy or delete text, you have to select it. To do so, use the standard techniques for the platform on which you are currently working.

You can also select all text at once (see below). In this case, the selection depends on the area which has previously been selected in the query window.

You can select text in the following areas:

Start of instruction setTo select all text

  1. Select the required area in the query window.

  2. From the Edit menu, choose Select All.

    Or:
    Press CTRL+A.

Top of page

Cutting, Copying and Pasting Text

You can cut, copy and paste any text in the query area. You can also copy from the result contents of the Result pane (plain view only), or from the query contents at the bottom of the History pane.

This feature uses the Windows clipboard which may also contain information from another application. Thus, it is also possible to copy an entire query from or to another source.

Start of instruction setTo cut the selection and transfer it to the clipboard

Start of instruction setTo copy the selection to the clipboard

Start of instruction setTo paste the content of the clipboard

  1. Place the insertion point at the position at which you want to paste the cut or copied information.

  2. From the Edit menu, choose Paste.

    Or:
    Press CTRL+V.

    Or:
    Choose the following toolbar button:

    Paste

    The previously cut or copied text is inserted at the insertion point.

Top of page

Finding Text Occurrences in XQuery Result and Response

You can find the occurrences of a text in the plain views of XQuery result and response panes.

Start of instruction setTo find occurrences of text

  1. Activate the plain view of the result or response pane.

  2. Choose the Find icon in the toolbar.

    Or:
    Choose Find from the Edit menu.

    Or:
    Press CTRL+F.

Top of page

Deleting Text

You can delete any text in the query area.

Start of instruction setTo delete the selection

Top of page

Undoing and Redoing the Previous Change

You can undo and redo your previous changes in the query area.

Start of instruction setTo undo the previous change

Start of instruction setTo redo the previous undo action

Top of page