README for Emdros Perl bindings
Created: Late 2002
Last update: 7/17-2004


Attribution
===========

The groundwork for the Emdros SWIG Perl bindings was laid by Chris
Wilson <emdros@qwirx.com>.  Many thanks to Chris!  Also for his
willingness to assign the copyright to me.

Ulrik Petersen



Current status
==============

* Readiness:     EXPERIMENTAL, needs testing
* Completeness:  fairly COMPLETE (no known omissions)
* Documentation: UNDOCUMENTED (but see test.pl for code samples)
* Stability:     UNSTABLE, known memory leaks

This interface will probably change, as the changes listed in the TODO
section are implemented.

What works
----------
- connect to database
- Use the CEMdFDB interface
- Create a EMdFOutput object
- Create a MQLExecEnv object
- Execute MQL queries
- Determine whether the query succeeded or failed, and whether the result
  is a table or sheaf
- For tables, retrieve the contents of the table one cell at a time,
  and the whole table into a 2D array reference
- For sheaves, retrieve an array of straws (EmdrosPerl::Straw objects)
- For straws,  retrieve an array of matched objects (EmdrosPerl::MatchedObject)
- For matched objects, retrieve properties and the embedded sheaf

What doesn't work
-----------------
- Nothing known to be missing at this time, but:
- Everything not listed above is untested, and
- Your mileage may vary.


TODO
====

- Some accessor methods will become member methods
- A bug in SWIG needs to be fixed so that some shadow methods such as
  EmdrosPerl::Straw_to_array become usable (in the meantime use their
  equivalents from the EmdrosPerlc:: package instead)
- New classes may be created to provide more Perl-friendly interfaces
  than C++ iterators


Installation
============

If installed from RPM
---------------------

Follow the instructions for installing from source, from step 3).


If installed from source
------------------------

1) Make sure you pass the

--with-swig-language-perl

option to the configure script when you run it (see INSTALL in the
top-level directory).

2) Build and install as in the INSTALL file in the top-level
   directory.  

3) Use the following two lines at the top of your perl files:

   use lib "/usr/local/lib/emdros"
   use EmdrosPerl

   The directory "/usr/local/lib/emdros" is based on the prefix that
   was chosen when running configure.  If you used --prefix=/XXX when
   running configure, then use /XXX/lib/emdros in the perl file
   instead.

   Alternatively, do the following:

   a) Find out what the site-perl directory is.  To do this, run

      $ perl '-V:installsitearch'

   b) Make symlinks to the following files in the site-perl directory:

      $(pkglib)/EmdrosPerl.pm
      $(pkglib)/EmdrosPerl.so

   c) Use the following at the top of your perl files:

      use EmdrosPerl



Usage
=====

See the file 'test.pl' for examples of all currently supported
features and how to use them.  Note, however, that this script
requires the presence of a database called "wihebrew", which is our
production database.  So this script cannot currently be run by people
who do not have the "wihebrew" database.


