[MacPerl] Butler module released

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

Butler Module for Perl has been released.  I have set up a Butler Module
home page where you can download the package.

<http://www.math.rutgers.edu/~petechen/Butler/Butlerpm.html>

In case you don't know what Butler Module is, enclosed is the README file.
I apologize for the lack of anonymous ftp service.  I haven't quite got the
chance to get in touch with the local sysadmin to set this up.

Peter Chen
petechen@math.rutgers.edu
-----
README for Perl Butler Module

by Peter Chen <petechen@math.rutgers.edu>, 2/21/96
Last updated 2/26/96

I. What's Butler Module?

Butler module is a Perl5 module that enables perl scripts to access the Butler
SQL 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".
        Butler.XFCN  - Everyware's DAM Externals
        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, and Butler.XFCN in a folder/directory
that's in your perl library path.  I recommend adding a "local lib" into
your MacPerl library path, and put the files in the "local lib" folder
instead.  This makes it easier to differentiate them from the files
distributed with the standard library.

IV. How do I use this?

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

        &btlr_connect
        &btlr_disconnect
        &btlr_finish
        &btlr_prepare
        &btlr_execute
        &btlr_fetch
        &btlr_rollback
        &btlr_version
        &btlr_clnt_errno
        &btlr_errno
        &btlr_errno2
        &btlr_errstr
        &btlr_rv
        &btlr_do
        &btlr_lookup
        &btlr_login
        &btlr_mkdbstr
        &btlr_commit
        &btlr_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 (loosely, as Tim Bunce
<Tim.Bunce@ig.co.uk> pointed out).

<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.  You can use them interchangeably.  The session
        switching part has not been tested rigorously though.

VI. Disclaimer/Legalism

        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.

        3. Butler.XFCN included in this distribution is copyrighted 1994
Everyware
        Development.

VII. Credit

        Many thanks to MacPerl-L, Butler-L, and DBI mailing lists, where many
        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.

        Thanks to Butler product manager, Don J. Reith <donr@everyware.com> for
        giving me the permission to distribute Butler.XFCN, copyright 1994
        Everyware Development.

        Thanks to Tim Bunce <Tim.Bunce@ig.co.uk> for setting me straight on the
        naming of Butler module instead of using the anachronism, Butperl.

        Function names are changed from &but_ to &btlr_ as requested by
Gilbert Rankin
        <gilbert@netcom.com>.

VIII. Change Log

0.1
        Initial working version
0.2
        Change name from Butperl to Butler module.
        Change function names from &but_ to &btlr_.
        Add &btlr_clnt_errno, &btlr_errno2, &btlr_rv to provide detail
                status/error information.
        Fully comment all function calls in the source.

Peter Chen <petechen@math.rutgers.edu> 2/26/96