eqtusersguide.tex

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

\documentclass[a4paper]{article}
\usepackage{graphicx}
\usepackage{ucs}
\usepackage{html}
\title{Emdros Query Tool User's Guide -- Version 3.1.0}
\author{Ulrik Petersen}
\begin{document}
\newenvironment{precode}
        {\begin{list}{}{
        \setlength{\rightmargin}{\leftmargin}
        \setlength{\listparindent}{0pt}% needed for AMS classes
        \raggedright
        \setlength{\itemsep}{0pt}
        \setlength{\parsep}{0pt}
        \normalfont\ttfamily}%
        \item[]}
        {\end{list}}
\maketitle

\tableofcontents

\section{Introduction}




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




The Emdros Query Tool reads MQL queries and gives back the results
in a way that makes sense in the context of {\em your}
database.


\subsection{Origins of the query tool}




The original algorithms for the Emdros Query Tool were written by
{\bf Hendrik Jan Bosman} in Python.  Thus he is the real
father of the Emdros Query Tool. The algorithms were rewritten in C++
by Ulrik Petersen.


\subsection{This Guide}




This User's Guide is divided into four parts:


\begin{enumerate}

  
\item This introduction, which explains how to get started,
  
\item Graphical version User's Guide
  
\item Configuration of the program
  
\item Query Guide (including the MQL Cheat Sheet)

\end{enumerate}


\subsection{PCRE Library}




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.




PCRE can be downloaded from:



\begin{center}


ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/

\end{center}



\subsection{Three versions}



The Emdros Query Tool exists in three versions:


\begin{itemize}

  
\item A command-line version ({\bf eqtc})
  
\item Two graphical versions:

      \begin{itemize}

         
\item A non-Unicode version ({\bf eqt})
         
\item A Unicode-aware version ({\bf eqtu})

      \end{itemize}

\end{itemize}



The next page explains how to get started with either of these
versions.



\subsection{Getting started}

\subsubsection{Introduction}


 



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.


\subsubsection{Sample configuration file}




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




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%$\backslash$etc$\backslash$).  


\subsubsection{Full details}




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


\begin{itemize}

  
\item Configuring the program

\end{itemize}



\subsection{Command-line version}



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


\begin{verbatim}

eqtc -c <your-config-file> myquery.mql

\end{verbatim}



For example:


\begin{verbatim}

eqtc -c myconfigfile.cfg myquery.mql

\end{verbatim}


\subsubsection{Saving the output}




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


\begin{verbatim}

eqtc -c <your-config-file> myquery.mql > myoutput.txt

\end{verbatim}

\subsubsection{More options}




If using MySQL or PostgreSQL, you may need to pass a 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:




\begin{verbatim}

eqtc -c <your-config-file> -u <dbuser> -p <password> -h <dbhost> myquery.mql

\end{verbatim}



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


\begin{verbatim}

eqtc --help

\end{verbatim}



\section{Graphical version User's Guide}

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


\subsection{Starting the program}

\subsubsection{Getting started}




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 \includegraphics[scale=0.5]{connect.png} "Connect to database".


\subsubsection{Connection dialog}




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:


\begin{itemize}
  
\item SQLite, or
  
\item MySQL or PostgreSQL

\end{itemize}  

\subsubsection{Non-Unicode vs. Unicode}




For each backend, the program exists in two versions:


\begin{itemize}

  
\item A non-Unicode version ({\bf eqt})
  
\item A Unicode-aware version ({\bf eqtu})

\end{itemize}



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.



\subsubsection{SQLite version}



The Connection Settings dialog looks like this if you have selected
SQLite as the backend:


\includegraphics[scale=0.5]{SQLiteConnSettings.png}

\paragraph{Set the configuration file}





The first thing you should do is press the "Browse" button next to
the "Configuration" edit box, then navigate to where you have your
configuration file.




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.




For example:


\includegraphics[scale=0.5]{SQLiteConnSettingsFilled.png}

\paragraph{Press OK}




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




\subsubsection{MySQL/PostgreSQL version}



When you start the Emdros Query Tool using the MySQL or the PostgreSQL backend, you will see this dialog:


\includegraphics[scale=0.5]{MyPgSQLConnSettings.png}


\paragraph{Set the configuration file}




The first thing you should do is press the "Browse" button next to
the "Configuration" edit box, then navigate to where you have your
configuration file.


\paragraph{Database}




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.


\paragraph{Host, user, password}




Most people can leave the "host" and "user" fields as they are, and
simply write the password.




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) is running.




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 Emdros
documentation).




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.


\paragraph{Example}



\includegraphics[scale=0.5]{MyPgConnSettingsFilled.png}


\paragraph{Press OK}




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





\subsection{The main screen}



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



\includegraphics[scale=0.5]{MainScreen.png}

\subsubsection{Parts}




The main screen consist of these parts:


\begin{itemize}

  
\item A menu at the top. 

  \includegraphics[scale=0.5]{MenuBar.png}

  
\item Below that, a toolbar with
  buttons. 

  \includegraphics[scale=0.5]{ToolBar.png}

  
\item Below that, three areas:

     \begin{itemize}

        
\item To the right, a collapsible tree that shows the
        database schema

        
\item In the top half of the left side, the input area, where you write your
        queries and your configuration files.

        
\item In the lower half of the left side, the output area, where the output from
        queries will be written.

     \end{itemize}

\end{itemize}

\subsubsection{Next}




Next, we describe each of these parts.



\subsubsection{Toolbar}



The toolbar looks like this:


\includegraphics[scale=0.5]{ToolBar.png}



The buttons represent actions, each of which will be explained
below.


\paragraph{New, Open, Save}




{\bf New}\ \includegraphics[scale=0.5]{new.png}\ :
Clears the input and output areas to "start afresh".




{\bf Open}\ \includegraphics[scale=0.5]{open.png}\ :
Opens a file (a query or a configuration file).
 



{\bf Save}\ \includegraphics[scale=0.5]{save.png}\ :
Saves the current file.


\paragraph{Copy, Cut, Paste}




{\bf Copy}\ \includegraphics[scale=0.5]{copy.png}\ :
Copies the current selection to the clipboard.  Works for both the
input area and the output areaoutput area.




{\bf Cut}\ \includegraphics[scale=0.5]{cut.png}\ : Cuts
the current selection to the clipboard.  Works for both the
input area and the output areaoutput area.




{\bf Paste}\ \includegraphics[scale=0.5]{paste.png}\ : Pastes the current clipboard contents.  Works for
both the input area and the
output area.


\paragraph{Execute, Stop}




{\bf Execute}\ \includegraphics[scale=0.5]{flash.png}\ : Executes the query in the input area.