NAME

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

SYNOPSIS

  use MPE::IMAGE;

  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');
    . . . 
  }

DbClose

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

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

  DbInfo(Database,mode);
  DbInfo(Database,mode,qualifier);

DbOpen

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

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

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

• 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).

cpanm MPE::IMAGE

perl -MCPAN -e shell
install MPE::IMAGE