[MacPerl] Butperl ready for beta test

[petechen@math.rutgers.edu (Peter Chen)]

I just completed a working version of Butperl (a module that enables
MacPerl to access Butler database).  I am now looking for beta testers.
Any volunteer?  If all goes well, I will put this on my home page, and make
it publicly available.  Enclosed is the README file.

Peter Chen
petechen@math.rutgers.edu
------
README for Butperl by Peter Chen, 2/21/96

I. What's Butperl? [Is it just me, or does this sound funny to you too. :-)]

Butperl is a Perl5 module that enables perl scripts to access the Butler
database.  Currently, this only works on Macs.  So this will only be
useful with MacPerl.

II. What's in the package?

        Butler.ph    - Butperl perl header file with useful constants defined
        Butler.pm    - Butperl module, package name "Butler".
        README       - this file
        testpl.pl    - simple example testing whether Butler.pm is 'require'
                       friendly
        testpm.pl    - simple example testing whether Butler.pm is 'use'
                       friendly

III. How do I install this?

Simply put Butler.ph, Butler.pm, in a folder/directory that's in your
perl library path.

*Important*
The XFCN file that's loaded by MacPerl to interface with Butler is not
included in this distribution.  I am still waiting for permission from
Everyware to include this.  For Butler owners who has the "Connection
Goodies" disk:

        Open "EDC DAM Externals v1.0.3a" stack in the HyperCard folder with
                ResEdit
        Copy all XFCN and XCMD resources to a new file
        Save the file as "Butler.XFCN"
        Move the file into a folder in your perl library path.

IV. How do I use this?

Butler.pm provides you with the following functions, if you "use Butler'.

        &but_connect
        &but_disconnect
        &but_finish
        &but_prepare
        &but_execute
        &but_fetch
        &but_rollback
        &but_version
        &but_errno
        &but_errstr
        &but_do
        &but_lookup
        &but_login
        &but_mkdbstr
        &but_commit
        &but_dbsep

If you 'require Butler.pm' instead, you will have to use
'Butler::connect', 'Butler::disconnect', etc instead.  The arguments are
documented in the source.  The easiest way to start is use "testpm.pl as
a template.

V. Bugs and caveats

The interface is modeled after DBD/DBI specification.

<http://www.hermetica.com/technologia/DBI>

A few known shortcomings:

        1. Only one statement handle per session. There is no way to prepare
        multiple statements in one session.     For one session, there is
only one
        active statement.  So in reality, the database handle and the statement
        handle are equivalent.  At this point, the statement handles are not
        being used at all.

        2. Error and status checking.  Butler gives more error status
        information then simply an error number and an error string.  Right now
        I combine all these information into &but_errno and &but_errstr.
In the
        future, I plan to provide functions to give more detail error
information.

VI. Disclaimer

        1. Use this at your own risk.  This is a purely alpha/beta software.  I
        made no guarantee of how well this will work for you.

        2. No connection with Everyware.  This package is provided without any
        connection/sponsorship from Everyware.  The only connection if there is
        any, is that I have been a happy customer of Everyware for over a year.

VII. Credit

        Many thanks to MacPerl-L, Butler-L, and DBI mailing lists, where
lots of
        useful discussions took place.

        Special thank to Sergey Goldgaber <sergey@el.net>, whose original
        posting on Butler-L inspired this module.

        Thanks to Jeff A. Shields <jas@everyware.com> and Douglas Getty
        <dgetty@everyware.com> from Everyware for their great technical/sales
        support.