HOW-TO-USE for Emdros
Last update: 3/30-2004


Overview
========

This document contains the following sections below:

- Suggested order of things to do
- Download the documentation
- Configuring your back-end
- Bootstrapping 
- Testing Emdros
- How to use Emdros
- Populating a database
- Website
- Contacting the author


Suggested order of things to do
===============================

The suggested order of things to do after downloading Emdros is the
following:

1) Read the README file.  It tells you what Emdros is and can do for
   you, and gives useful pointers to further research.

2) Read the NEWS file.  It contains release-notes which are usually
   important both to new users and to old timers.

3) If you are upgrading, maybe checking the ChangeLog is a good idea.

4) If you downloaded Emdros as an RPM, install it.  Otherwise, compile
   and install as directed in the INSTALL file.

5) Set up your back-end.  The file bootstrapping.txt shows you how to
   do this (see also below).

6) Test Emdros.  The two programs emdftry(1) and mqltry(1) run a suite
   of tests that exercise much of the Emdros machinery.

7) Download and read the documentation.  You will need it in order to
   make sense of Emdros.  The README-doc file tells you what each
   documentation-file contains.  Reading the MQL User's Guide first is
   usually a good idea.

8) After that, you can start analyzing, designing, and implementing
   your application on top of Emdros.  This file gives you advice on
   how to do this.  The Emdros Programmer's Reference Guide (see
   below) also gives useful information on doing this.

The first thing after you have downloaded is to familiarize yourself
with the NEWS and README files.  The NEWS file contains release-notes


Download the documentation
==========================

If you want to use Emdros, you are strongly encouraged to download the
documentation.  Otherwise, you will not be able to make sense of
Emdros:

http://emdros.org/docs.html


There is also a Programmer's Reference Guide:

http://emdros.org/progref/


Configuring your back-end
=========================

You may need to configure your back-end for use with Emdros.  Here are
the most important points:

PostgreSQL
----------

- The postmaster must be configured to accept TCP/IP connections.
  There are two ways to do this:

  - Run the postmaster with the -i option.  If you use pg_ctl to
    start/stop the postmaster, you can use pg_ctl's -o option to pass
    this option to the postmaster.

  - Configure the postgresql.conf file with the following line:

    tcpip_socket = true

    On RedHat Linux, you will find postgresql.conf in
    /var/lib/pgsql/data/.

- The postmaster must be configured to accept password authentication
  at least on the local machine.  You can configure this in the
  pg_hba.conf file, with the following line:

  - On PostgreSQL 7.2.x and earlier:
    host    all     127.0.0.1       255.255.255.255   password

  - On PostgreSQL 7.3 and later:
    host    all     all     127.0.0.1       255.255.255.255   password

  If you want to allow the psql console to access the databases, you
  may wish to include the following line as well:

  - On PostgreSQL 7.2.x and earlier:
    local       all     password

  - On PostgreSQL 7.3 and later:
    local       all     all       password


  On RedHat Linux, you will find pg_hba.conf in /var/lib/pgsql/data/.

In order to bootstrap (see bootstrapping.txt), you may have to change
the authentication to:

    local       all     all       trust

But you should probably only do this temporarily while you create a
user for use with Emdros (see bootstrapping.txt).  After you have
created a user, you can change the method back to 'password'.


PLEASE don't trust these instructions blindly.  Rather, you should
PLEASE gain an understanding of what these configurations do, and the
security-issues involved.  You should check the PostgreSQL
documentation for more information.


MySQL
-----

This should not require configuration beyond bootstrapping (see
below).  Note, however, that Emdros connects with the mysql back-end
via TCP/IP sockets, so the back-end must be configured for this.


SQLite
------

Shouldn't need any configuration.


Bootstrapping
=============

Before running any Emdros programs or interfaces, you may need to
follow the instructions in the bootstrapping.txt document.  This
basically instructs you in how to set up a database user account for
use with Emdros.  If you already have a user account for your
database, then don't worry about setting up a new one.  Just use the
username you have.

This only applies if using MySQL or PostgreSQL -- SQlite doesn't have
the concept of users, and so no setup is required.


Testing Emdros
==============

You may want to test Emdros.  In the tests/ directory, you will find
two programs:

- emdftry
- mqltry

You can run these programs to see whether Emdros works.  You should
see a lot of SUCCESS messages.  If you see a FAILURE message, then
something doesn't quite work right.  In this case, please drop the
author an e-mail telling him of your problem.  See the AUTHORS
document for the e-mail.




How to use Emdros
=================

You need to write a client
--------------------------

Emdros is a generic tool which can handle a large number of
application domains.  To use Emdros, you will need to write an
application on top of Emdros which takes care of your specific
application domain.


You will need the documentation
-------------------------------

You will need the documentation available from:

http://emdros.org/docs.html

in order to make sense of Emdros.  In particular, you will need the
MQL User's Guide and possibly the other documents specified on the
webpage as "User documentation".


Emdros architecture
-------------------

An Emdros architecture looks as follows:

+---------------+
|    Client     | User-written
+---------------+
       |
+---------------+
|     MQL       | Emdros
+---------------+
       |
+---------------+
|     EMdF      | Emdros
+---------------+
       |
+---------------+
|      DB       | PostgreSQL or MySQL or SQLite
+---------------+


Options for calling Emdros
--------------------------

Your client application can be written in almost any programming
language, including Ruby, Perl, Python, C++, C, Pascal, and any
programming language which can either:

1) use sockets 
2) call external programs
3) or link to C++ libraries.

Option 1) is available if you can find a way to use the mql(1) program
(built in src/) as a daemon.  This is possible with such programs as
inetd and xinetd, available on a number of platforms including Linux.
These programs listen on specified ports and start external programs
(in this case, the mql(1) program) when an incoming request comes in
on the port.  It then connects the port to stdin and stdout of the
program in question.  There is a sample xinted configuration file for
mql(1) in the xinetd.mql sample file, available in the documentation
directory.

Option 2) is probably the easiest if you don't have option 1)
available to you.  Just pass your MQL queries to the mql(1) program
and read back the stdout response.

Option 3) is useful if you want the best performance and are writing
in C++.  See the makefiles and sources for ideas on how to do this.
In particular, refer to src/mql.cpp and src/mqltry.cpp for ideas.


Use the MQL query language
--------------------------

You are advised to use the MQL query language as an interface to
Emdros rather than dealing with the EMdF layer directly.  See the MQL
User's Guide, available from the website (see below), for details on
the MQL query language.


Minimize the number of queries
------------------------------

The following maxim applies when designing Emdros database
applications:

"Minimize the number of queries to maximize throughput."

What this means is that you should normally issue as few queries as
possible.  For example, the queries GET MONADS FROM OBJECTS WITH ID_DS
and GET FEATURES FROM OBJECTS WITH ID_DS allow specification of as
many id_ds as you like.  Also, the query SELECT OBJECTS HAVING MONADS
IN allows arbitrarily large monad sets.  Take advantage of these facts
when designing applications on top of Emdros.

One caveat: It is the number of _SQL_ queries one should ideally
minimize, not necessarily MQL queries.  As a rule of thumb, it is
almost always safe to assume that fewer MQL queries result in fewer
SQL queries.  The exception to this is when an MQL query allows "ALL"
to be specified as a pseudo-object type.  In such cases, if all you
want is a few of the available object types, simply issue a series of
MQL queries with each desired object type, instead of wasting
resources by using the powerful "ALL" pseudo-object type.


A strategy for display of query results
---------------------------------------

Please see the Programmer's Reference Guide:

http://emdros.org/progref/


An in-memory EMdF database
--------------------------

Please see the Programmer's Reference Guide:

http://emdros.org/progref/


Populating a database
=====================

Please see the Programmer's Reference Guide:

http://emdros.org/progref/


Moving databases between backends
---------------------------------

In order to move already-existing databases between backends, you can
do the following.  Say you want to move a database from backend #1 to
backend #2.


- Install Emdros for backend #1

- Dump your MySQL database using the mqldump tool.

  $ mqldump --verbose -p <password> -u <username> -o db.mql <databasename>

- Uninstall Emdros for backend #1

- Install Emdros for backend #2

- Import the data exported with mqldump using mql

  $ mql -n -p <password> -u <username> db.mql



Website
=======

Emdros has a website at:

http://emdros.org/


Contacting the author
=====================

The author (Ulrik Petersen) can be contacted at:

                    ulrikp@users.sourceforge.net.  

Please feel free to ask questions, report bugs, etc.  The author may
take some time to answer, but that's what you can expect from free
support :-).

You can also ask questions in the fora at
<http://sourceforge.net/forum/?group_id=37219>
