NAME
    MPE::IMAGE - Access MPEs TurboIMAGE/XL databases from within Perl

SYNOPSIS
      use MPE::IMAGE ':all';

      my $db = DbOpen('Dbase.Group.Account','Password',5);
      die "DbOpen Error: $DbError" unless $DbStatus[0] == 0;

      my %record = DbGet($db,2,'dataset','items');
      DbExplain unless $DbStatus[0] == 0;

      $db->DbClose(1);
      DbExplain unless $DbStatus[0] == 0;

DESCRIPTION
    MPE::IMAGE is designed to make access to TurboIMAGE/XL databases fairly
    comfortable to the Perl programmer. Please note that the calls differ in
    certain ways from the native intrinsic calls. In specific:

    * Anywhere a "number of elements" was given, it is no longer necessary.
    Perl knows how many elements are in an array and passes that information
    to the appropriate intrinsic. An example of this is in passing an
    item-number list to `DbGet'.
    * The status array is a globally defined perl array and so does not get
    passed to any of the routines.
    * The data returned from `DbGet' and passed to `DbPut' and `DbUpdate'
    can be either a single scalar value containing the entire buffer exactly
    as it is gotten or put, or a hash mapping item names to their values.
    * MPE::IMAGE will handle all the translation to and from the various
    IMAGE datatypes transparently.
    * `DbGet', `DbPut' and `DbUpdate' can each take a schema hash, allowing
    fields to be redefined.
    * Dataset and item names can be given in any case. They will be passed
    to the intrinsics uppercase.
    The following are provided by MPE::IMAGE. Note that for each call which
    expects a database argument, that argument should be a database object
    as returned by `DbOpen'.

  `@DbStatus'

    The array `@DbStatus' contains the status values from the most recent
    intrinsic call.

  `$DbError'

    `DBERROR' is implemented as a readonly variable called `$DbError'. When
    used in a string context, `$DbError' gives the text returned by a call
    to `DBERROR'.

    When used in a numeric context, it contains the same value as
    `$DbStatus[0]'. However, it is somewhat more expensive to use than
    `$DbStatus[0]' as using it includes the overhead of using a tied
    variable and, possibly, a call to `DBERROR'.

    In any of the following usages, the overhead should be negligible

      die "DbOpen Error: $DbError" unless $DbStatus[0] == 0;
      die "DbOpen Error: $DbError" if $DbError;
      dbfail($DbError) if $DbError != 0 and $DbError != 15;

    I would be much less likely to use it in this fashion:

      while ($DbError == 0) {
        %data = DbGet($db,5,'dataset');
        . . . 
      }

    because it makes a "method" call on every iteration and in the final
    pass, when the status comes up 15, it performs a `DBERROR' call to get
    an explanation for an expected condition, both problems which are
    avoided by using $DbStatus[0] instead:

      while ($DbStatus[0] == 0) {
        %data = DbGet($db,5,'dataset');
        . . . 
      }

  `DbBegin'

      DbBegin(Database,1);
      DbBegin(Database,1,text);
      $transid = DbBegin(Array of bases,3 or 4);
      $transid = DbBegin(Array of bases,3 or 4,text);

    Note that the $transid is more than just a number. It is the array, in
    binary form, containing not only the transaction id but all the base ids
    as well. Its only intended purpose is for passing to DbEnd.

  `DbClose'

      DbClose(Database,mode);
      DbClose(Database,mode,dataset);

  `DbControl'

      DbControl(Database,mode);
      $status = DbControl(Database,13,0);
      $status = DbControl(Database,13,function,set);
      $status = DbControl(Database,13,function,set,flags);
      $status = DbControl(Database,14,function);
      $status = DbControl(Database,14,7,wildcard);
      DbControl(Database,15);
      DbControl(Database,15,wildcard);
      DbControl(Database,16);

  `DbEnd'

      DbEnd(Database,1 or 2);
      DbEnd(Database,1 or 2,text);
      DbEnd(Array of bases,3 or 4);
      DbEnd(Array of bases,3 or 4,text);
      DbEnd($transid,3 or 4);
      DbEnd($transid,3 or 4,text);

  `DbExplain'

      DbExplain;

  `DbFind'

      DbFind(Database,dataset,argument);  # Assumed find mode 1 on key item
      DbFind(Database,dataset,item,argument);  # Assumed mode 1
      DbFind(Database,dataset,mode,item,argument);

  `DbGet'

      DbGet(Database,mode,dataset);
      DbGet(Database,mode,dataset,list);
      DbGet(Database,mode,dataset,undef,argument);
      DbGet(Database,mode,dataset,list,argument);
      DbGet(Database,mode,dataset,undef,undef,schema);
      DbGet(Database,mode,dataset,list,undef,schema);
      DbGet(Database,mode,dataset,undef,argument,schema);
      DbGet(Database,mode,dataset,list,argument,schema);

    `list' can be either an array of or a comma-separated list of item names
    or numbers (or a mixture of both). It can also be "0", "*" or "@" and
    can be semicolon/space-terminated or not as preferred. If `list' is
    omitted, it is assumed to be "*;" if the dataset has previously be used
    and "@;" if not.

    `schema' is the description of the fields and must describe a space of
    exactly the same size as the fields in `list'. There will be a helper
    function to allow a schema to be checked prior to use and this is highly
    recommended. If the schema is omitted, a schema derived from the IMAGE
    item descriptions is used instead. See the section on schemata for more
    information.

    When used in scalar context, DbGet returns the retrieved values as a
    single block. Otherwise it returns a hash where the keys are the item
    names (or the fields described in the schema) and the values are the
    values of those items/fields.

  `DbInfo'

    Since the return values from DbInfo must be parsed, and since the
    necessary buffer size varies widely depending on the mode, only the
    modes listed in the August 1997 (sixth) edition of the Image manual are
    supported (third-party indexing modes are not currently supported).

      $item_num = DbInfo(Database,101,item name or number);

      %item_info = DbInfo(Database,102,item name or number);

    `%item_info' will have elements with the following keys: "name", "type",
    "length", "count".

      @item_nums = DbInfo(Database,103);

    `@item_nums' will contain the item numbers (positive and negative). As
    with other modes which return arrays, the first element is *not* the
    number of items. Rather, the number of items is reflected in the size of
    the array.

      @item_nums = DbInfo(Database,104,set name or number);

      @btree_info = DbInfo(Database,113);

    `@btree_info' will be a six-element array, the 2nd and 6th elements of
    which contain the respective wild-card characters (see Image
    documentation).

      $set_num = DbInfo(Database,201,set name or number);

      %set_info = DbInfo(Database,202,set name or number);

    `%set_info' will have elements with the following keys: "name", "type",
    "length", "block fact", "entries", "capacity".

      @set_nums = DbInfo(Database,203);

      @set_nums = DbInfo(Database,204,item name or number);

      %set_info = DbInfo(Database,205,set name or number);

    `%set_info' will have elements with the following keys: "name", "type",
    "length", "block fact", "entries", "capacity", "hwm", "max cap", "init
    cap", "increment", "inc percent", "dynamic cap".

      $num_chunks = DbInfo(Database,206,set name or number);

      @chunk_sizes = DbInfo(Database,207,set name or number);

      @set_info = DbInfo(Database,208,set name or number);

    `@set_info' will be a seven-element array.

      @btree_info = DbInfo(Database,209,set name or number);

    `@btree_info' will be a two-element array.

      @path_array = DbInfo(Database,301,set name or number);

    `@path_array' will be an n-element array, where n is the number of paths
    for the specified dataset. Each element will be a reference to a hash
    containing elements with the following keys: "set", "search", and
    "sort". To report which sets are connected by paths to MYDETAIL, you
    could do something like this:

      my @path_array = DbInfo($db,301,'MYDETAIL');
      foreach (@path_array) {
        print $_->{'set'},"\n";
      }
      # end of example

      @key_array = DbInfo(Database,302,set name or number);

    `@key_array' will be a two-element array.

      %log_info = DbInfo(Database,401);

    `%log_info' will have elements with the following keys: "logid", "base
    log flag", "user log flag", "trans flag", "user trans num".

      %ILR_info = DbInfo(Database,402);

    `%ILR_info' will have elements with the following keys: "ILR log flag",
    "ILR date", "ILR time".

      %log_info = DbInfo(Database,403);

    `%log_info' will have elements with the following keys: "logid", "base
    log flag", "user log flag", "trans flag", "user trans num", "log set
    size", "log set type", "base attached", "dynamic trans", "log set name".

      %log_info = DbInfo(Database,404);

    `%log_info' will have elements with the following keys: "base log flag",
    "user log flag", "rollback flag", "ILR log flag", "mustrecover", "base
    remote", "trans flag", "logid", "log index", "trans id", "trans bases",
    "base ids". "base ids" will be a reference to an array containing the
    ids of the bases being used in a multiple-base transaction.

      %db_info = DbInfo(Database,406);

    `%db_info' will have elements with the following keys: "name", "mode",
    "version"

      $subsys_access = DbInfo(Database,501);

      @ci_update = DbInfo(Database,502);

    `@ci_update' will be a two-element array.

      $language_id = DbInfo(Database,901);

  `DbMemo'

      DbMemo(Database);
      DbMemo(Database,text);

  `DbOpen'

      $db = DbOpen(BaseName,Password,Mode);

    DbOpen returns a database object which can be passed to the other calls.

  `DbXBegin'

      DbXBegin(Database,1);
      DbXBegin(Database,1,text);
      $transid = DbXBegin(Array of bases,3);
      $transid = DbXBegin(Array of bases,3,text);

    Note that the $transid is more than just a number. It is the array, in
    binary form, containing not only the transaction id but all the base ids
    as well. Its only intended purpose is for passing to DbXEnd or DbXUndo.

  `DbXEnd'

      DbXEnd(Database,1 or 2);
      DbXEnd(Database,1 or 2,text);
      DbXEnd($transid,3);
      DbXEnd($transid,3,text);

  `DbXUndo'

      DbXUndo(Database,1);
      DbXUndo(Database,1,text);
      DbXUndo($transid,3);
      DbXUndo($transid,3,text);

HELPER FUNCTIONS
    MPE::IMAGE also provides a set of helper functions

    * dset_info(Database,Dataset)
    * dset_name(Database,Dataset)
    * dset_num(Database,Dataset)
    * item_info(Database,Item)
    * item_name(Database,Item)
    * item_num(Database,Item)
    These functions return information about datasets or items either by
    making the necessary DbInfo calls or from cache, so they can be
    considerably faster that making a DbInfo call. `dset_info' returns all
    of the mode 205 information except number of entries, capacity and
    high-water mark--those things which cannot be safely cached. `item_info'
    returns the mode 102 information. All of the calls can take either a
    dataset/item name or number. That way, one can use, for example,
    `item_num' passing it whatever item identification one currently has and
    receive back an item number.

SCHEMAS
    Yet to be written

NOTES
    * ONLY those calls/modes which are in the test suite are guaranteed to
    be tested. There are some things, such as Priv Mode DbControl calls and
    things relating to B-Trees and Jumbo sets which I couldn't very well
    test.
    * MPE::IMAGE can handle packed-decimal fields of any length, but as a
    P28, for example, can hold a larger number than a 64-bit integer, P
    fields are always translated into strings. If the number is within
    range, Perl will translate it into binary format when necessary.
    * IMAGE allows the definition of I, J and K types greater than 64 bits.
    MPE::IMAGE, however, gets very confused by such things.
AUTHOR
        Ted Ashton, ashted@southern.edu

SEE ALSO
        perl(1).