<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 resultsin 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 realfather 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 copyrightby 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 theseversions.</P></page><page ID="1010"><h2>Introduction</h2><index term="configuration file"> <P>Before running the Emdros Query Tool for the first time on adatabase, you need to write a configuration file that matches yourdatabase.  This is a one-off thing: Once it's done, you don't need tobother 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 ownconfiguration file.</P><P>One supplied configuration file is called "default.cfg", whileanother is called "wihebrew.cfg".  You can search for these on yourcomputer to locate where they are, or see the manual page for eqt toknow 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, youcan get more information about the details of the configuration filehere:</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 proceedto 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 redirectthat 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 thedatabase 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 usethe 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 mainscreen.  You will then need to "connect" to a database.  Either choosethe menu-item "Tools|New database connection" or press the button <IMGSRC="connect.png"> "Connect to database".</P><h2>Connection dialog</h2><P>You will then be given a dialog box allowing you to choose theConnection Settings.  At the top is a drop-down box allowing you tochoose the backend.  Based on this choice, the dialog box will appearslightly 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, replacingthe non-Unicode version.  This occurs if the installed wxWidgets usesUnicode by default.</P></page><page ID="1115"><P>The Connection Settings dialog looks like this if you have selectedSQLite 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 tothe "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" fieldwill be filled from the "database" value stored in the configurationfile, if any.  If this is not the database you want, simply enter (orbrowse for) the database you want.</P><P>For example:</P><IMG SRC="SQLiteConnSettingsFilled.png" ALT="SQLite Connectionsettings 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<indexterm="MySQL"> PostgreSQL backend, you will see this dialog:</P><IMG SRC="MyPgSQLConnSettings.png" ALT="MySQL/PostgreSQL Connectionsettings 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 tothe "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" fieldwill be filled from the "database" value stored in the configurationfile, if any.  If this is not the database you want, simply enter thedatabase you want.</P><h2>Host, user, password</h2><P>Most people can leave the "host" and "user" fields as they are, andsimply write the password.</P><index term="password"><P>The "host" field shows which computer to connect to, i.e., thecomputer where the MySQL or PostgreSQL backend is running. "localhost"means the computer where eqt(u) <index term="eqt"><indexterm="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.  Thedefault is "emdf", since that is the recommended default user tocreate when you bootstrap the MySQL or PostgreSQL database (see"bootstrapping.txt" in the <AHREF="http://emdros.org/docs-download.html">Emdrosdocumentation</A>).</P><P>The "password" field is for the password of the database user toconnect as.  This is set either by the database administrator, or bythe one who bootstrapped the MySQL or PostgreSQL database.</P><indexterm="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 explainedbelow.</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> <indexterm="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_anchorID="1300">output area</page_anchor>output area.</P><P><strong>Cut</strong>&nbsp;<IMG SRC="cut.png" ALT="Cut">&nbsp;: Cutsthe current selection to the clipboard.  Works for both the<page_anchor ID="1200">input area</page_anchor> and the <page_anchorID="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 forboth 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_anchorID="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 theexecution stops.  Please try pressing this button again if executiondoes 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">inputarea</page_anchor> and the <page_anchor ID="1300">outputarea</page_anchor>, thus "starting afresh".</P>