content.txt

Emdros is a text database middleware-layer aimed at storage and retrieval of "text plus information

<page ID="1000">

</page>


<page ID="1001">


<P>This is a short User's Guide to the Emdros Query Tool (aka eqt).</P>

<P>The Emdros Query Tool reads MQL queries and gives back the results
in a way that makes sense in the context of <em>your</em>
database.</P>

<h2>Origins of the query tool</h2>

<P>The original algorithms for the Emdros Query Tool were written by
<strong>Hendrik Jan Bosman</strong> in Python.  Thus he is the real
father of the Emdros Query Tool. The algorithms were rewritten in C++
by Ulrik Petersen.</P>

<h2>This Guide</h2>

<P>This User's Guide is divided into four parts:</P>

<OL>

  <LI>This introduction, which explains how to get started,
  <LI><page_anchor ID="1100">Graphical version User's Guide</page_anchor>
  <LI><page_anchor ID="2000">Configuration of the program</page_anchor>
  <LI><page_anchor ID="3000">Query Guide</page_anchor> (including the <page_anchor ID="3100">MQL Cheat Sheet</page_anchor>)

</OL>


<h2>PCRE Library</h2>

<P>Regular expression support is provided by the PCRE library package,
which is open source software, written by Philip Hazel, and copyright
by the University of Cambridge, England.</P>

<P>PCRE can be downloaded from:</P>

<center><P>ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/</P></center>

</page>


<page ID="1005">

<P>The Emdros Query Tool exists in three versions:</P>

<UL>

  <LI>A command-line version (<strong>eqtc</strong>)
  <LI>Two graphical versions:

      <UL>

         <LI>A non-Unicode version (<strong>eqt</strong>)<index term="eqt">
         <LI>A Unicode-aware version (<strong>eqtu</strong>)<index term="eqtu">

      </UL>

</UL>

<P>The next page explains how to get started with either of these
versions.</P>

</page>


<page ID="1010">

<h2>Introduction</h2>

<index term="configuration file"> 

<P>Before running the Emdros Query Tool for the first time on a
database, you need to write a configuration file that matches your
database.  This is a one-off thing: Once it's done, you don't need to
bother with it any more.</P>

<h2>Sample configuration file</h2>

<P>A number of sample configuration files are supplied with Emdros.
You can use these as a starting point for writing your own
configuration file.</P>

<P>One supplied configuration file is called "default.cfg", while
another is called "wihebrew.cfg".  You can search for these on your
computer to locate where they are, or see the manual page for eqt to
know where they are installed (on Windows, they are installed in
%EMDROSINSTALLPREFIX%\etc\).  </P>

<h2>Full details</h2>

<P>The "default.cfg" file is almost self-documenting.  However, you
can get more information about the details of the configuration file
here:</P>

<UL>

  <LI><page_anchor ID="2000">Configuring the program</page_anchor>

</UL>


</page>


<page ID="1020">

<P>After you've written the configuration file, you can then proceed
to running the Emdros query tool, like this:</P>

<PRE class="code">
eqtc -c {PRELT}your-config-file{PREGT} myquery.mql
</PRE><!-- widthincm : 12 -->

<P>For example:</P>

<PRE class="code">
eqtc -c myconfigfile.cfg myquery.mql
</PRE><!-- widthincm : 12 -->


<h2>Saving the output</h2>

<P>The results will be printed on standard output, so you can redirect
that to a file for later viewing:</P>

<PRE class="code">
eqtc -c {PRELT}your-config-file{PREGT} myquery.mql {PREGT} myoutput.txt
</PRE><!-- widthincm : 12 -->

<h2>More options</h2>

<P>If using MySQL or PostgreSQL, you may need to pass a password
<index term="password">to the program.  Do this with the -p option.
You may also need to pass a database username (-u) or the name of the
database host computer (-h).  For example:</P>
<index term="MySQL">
<index term="PostgreSQL">

<PRE class="code">
eqtc -c {PRELT}your-config-file{PREGT} -u {PRELT}dbuser{PREGT} -p {PRELT}password{PREGT} -h {PRELT}dbhost{PREGT} myquery.mql
</PRE><!-- widthincm : 12 -->

<P>To get a list of supported options, run eqtc with the "--help"
switch:</P>

<PRE class="code">
eqtc --help
</PRE><!-- widthincm : 12 -->


</page>

<page ID="1100">

This section of the Emdros Query Tool User's Guide shows how to use
the graphical versions of the Emdros Query Tool.

</page>



<page ID="1110">

<h2>Getting started</h2>

<P>Once you open the program, you will be presented with the main
screen.  You will then need to "connect" to a database.  Either choose
the menu-item "Tools|New database connection" or press the button <IMG
SRC="connect.png"> "Connect to database".</P>

<h2>Connection dialog</h2>

<P>You will then be given a dialog box allowing you to choose the
Connection Settings.  At the top is a drop-down box allowing you to
choose the backend.  Based on this choice, the dialog box will appear
slightly differently depending whether the backend is:</P>

<UL>
  <LI><page_anchor ID="1115">SQLite</page_anchor>, or
  <LI><page_anchor ID="1118">MySQL or PostgreSQL</page_anchor><index term="MySQL"><index term="PostgreSQL">

</UL>  

<H2>Non-Unicode vs. Unicode</h2>

<P>For each backend, the program exists in two versions:</P>

<UL>

  <LI>A non-Unicode version (<strong>eqt</strong>)<index term="eqt">
  <LI>A Unicode-aware version (<strong>eqtu</strong>)<index term="eqtu">

</UL>

<P>Note that on Linux/Unix, eqtu may in fact be called eqt, replacing
the non-Unicode version.  This occurs if the installed wxWidgets uses
Unicode by default.</P>

</page>



<page ID="1115">

<P>The Connection Settings dialog looks like this if you have selected
SQLite as the backend:</P><index term="Connection settings dialog">

<IMG SRC="SQLiteConnSettings.png" ALT="SQLite Connection settings dialog">

<h2>Set the configuration file</h2>

<index term="configuration file">
<P>The first thing you should do is press the "Browse" button next to
the "Configuration" edit box, then navigate to where you have your
<page_anchor ID="1010">configuration file</page_anchor>.</P>

<P>Once you've opened the configuration file, the "database" field
will be filled from the "database" value stored in the configuration
file, if any.  If this is not the database you want, simply enter (or
browse for) the database you want.</P>

<P>For example:</P>

<IMG SRC="SQLiteConnSettingsFilled.png" ALT="SQLite Connection
settings dialog, filled with values">

<h2>Press OK</h2>

<P>Once you're done setting the configuration file and the database,
press "OK".  If you want to quit the program instead, press
"Cancel".</P>


</page>



<page ID="1118">

<P>When you start the Emdros Query Tool using the MySQL or the<index
term="MySQL"> PostgreSQL backend, you will see this dialog:</P>

<IMG SRC="MyPgSQLConnSettings.png" ALT="MySQL/PostgreSQL Connection
settings dialog"><index term="Connection settings dialog">

<index term="configuration file">
<h2>Set the configuration file</h2>

<P>The first thing you should do is press the "Browse" button next to
the "Configuration" edit box, then navigate to where you have your
<page_anchor ID="1010">configuration file</page_anchor>.</P>

<h2>Database</h2>

<P>Once you've opened the configuration file, the "database" field
will be filled from the "database" value stored in the configuration
file, if any.  If this is not the database you want, simply enter the
database you want.</P>

<h2>Host, user, password</h2>

<P>Most people can leave the "host" and "user" fields as they are, and
simply write the password.</P><index term="password">

<P>The "host" field shows which computer to connect to, i.e., the
computer where the MySQL or PostgreSQL backend is running. "localhost"
means the computer where eqt(u) <index term="eqt"><index
term="eqtu">is running.</P>

<P>The "user" field is the database user to connect to the backend as.
Note that this may be different from your computer user name.  The
default is "emdf", since that is the recommended default user to
create when you bootstrap the MySQL or PostgreSQL database (see
"bootstrapping.txt" in the <A
HREF="http://emdros.org/docs-download.html">Emdros
documentation</A>).</P>

<P>The "password" field is for the password of the database user to
connect as.  This is set either by the database administrator, or by
the one who bootstrapped the MySQL or PostgreSQL database.</P><index
term="password">

<h2>Example</h2>


<IMG SRC="MyPgConnSettingsFilled.png" ALT="MySQL/PostgreSQL Connection settings dialog, filled with values">


<h2>Press OK</h2>

<P>Once you're done setting the configuration file and the database,
press "OK".  If you want to quit the program instead, press
"Cancel".</P>



</page>



<page ID="1120">

<P>Once you've pressed "OK" on the "Connection settings" dialog box,
you will see the main screen:</P>


<IMG SRC="MainScreen.png" ALT="The main screen">

<h2>Parts</h2>

<P>The main screen consist of these parts:</P>

<UL>

  <LI>A <page_anchor ID="1140">menu</page_anchor> at the top. 

  <IMG SRC="MenuBar.png" ALT="The menu bar">

  <LI>Below that, a <page_anchor ID="1130">toolbar</page_anchor> with
  buttons. 

  <IMG SRC="ToolBar.png" ALT="The toolbar">

  <LI>Below that, three areas:

     <UL>

        <LI>To the right, a collapsible tree that shows the
        <page_anchor ID="1400">database schema</page_anchor>

        <LI>In the top half of the left side, the <page_anchor
        ID="1200">input area</page_anchor>, where you write your
        queries and your configuration files.
<index term="configuration file">
        <LI>In the lower half of the left side, the <page_anchor
        ID="1300">output area</page_anchor>, where the output from
        queries will be written.

     </UL>

</UL>

<h2>Next</h2>

<P>Next, we describe each of these parts.</P>

</page>



<page ID="1130">

<P>The toolbar looks like this:</P>

<IMG SRC="ToolBar.png" ALT="The toolbar">

<P>The buttons represent actions, each of which will be explained
below.</P>

<h2>New, Open, Save</h2>

<P><strong>New</strong>&nbsp;<IMG SRC="new.png" ALT="New">&nbsp;:
Clears the input and output areas to "start afresh".</P>

<P><strong>Open</strong>&nbsp;<IMG SRC="open.png" ALT="Open">&nbsp;:
Opens a file (a query or a configuration file).</P> <index
term="configuration file">

<P><strong>Save</strong>&nbsp;<IMG SRC="save.png" ALT="Save">&nbsp;:
Saves the current file.</P>

<h2>Copy, Cut, Paste</h2>

<P><strong>Copy</strong>&nbsp;<IMG SRC="copy.png" ALT="Copy">&nbsp;:
Copies the current selection to the clipboard.  Works for both the
<page_anchor ID="1200">input area</page_anchor> and the <page_anchor
ID="1300">output area</page_anchor>output area.</P>

<P><strong>Cut</strong>&nbsp;<IMG SRC="cut.png" ALT="Cut">&nbsp;: Cuts
the current selection to the clipboard.  Works for both the
<page_anchor ID="1200">input area</page_anchor> and the <page_anchor
ID="1300">output area</page_anchor>output area.</P>

<P><strong>Paste</strong>&nbsp;<IMG SRC="paste.png"
ALT="Paste">&nbsp;: Pastes the current clipboard contents.  Works for
both the <page_anchor ID="1300">input area</page_anchor> and the
<page_anchor ID="1300">output area</page_anchor>.</P>

<h2>Execute, Stop</h2>

<P><strong>Execute</strong>&nbsp;<IMG SRC="flash.png"
ALT="Execute">&nbsp;: Executes the query in the <page_anchor
ID="1200">input area</page_anchor>.</P>

<P><strong>Stop</strong>&nbsp;<IMG SRC="stop.png" ALT="Stop">&nbsp;:
Stops the current execution.  You may have to wait a bit before the
execution stops.  Please try pressing this button again if execution
does not stop immediately.</P>


</page>



<page ID="1140">

<P>There are four menus, each explained on its own page:</P>

<OL>

  <LI><page_anchor ID="1145">File menu</page_anchor>

  <LI><page_anchor ID="1150">Edit menu</page_anchor>

  <LI><page_anchor ID="1155">Tools menu</page_anchor>

  <LI><page_anchor ID="1160">Help menu</page_anchor>

</OL>


</page>



<page ID="1145">

<h2>New...</h2>

<P>The "New..." menu item clears the <page_anchor ID="1200">input
area</page_anchor> and the <page_anchor ID="1300">output
area</page_anchor>, thus "starting afresh".</P>