NAME

DB::Appgen - Perl interface to APPGEN databases

SYNOPSIS

Object oriented:

  use DB::Appgen;

  my $db=new DB::Appgen file => "order.db";

  $db->seek(key => 'Test);

  my $data=$db->record;

  print "quantity=", $data->[123]->[2];

  $db->replace(attribute => '1', value => '2', text => 'Test Data 1-2');

  $db->commit;

  $db->close;

Function oriented (mimics appgen C toolkit):

  use DB::Appgen qw(:all);

  my $db=ag_db_open('sales.db');

  ag_db_newrec($db,'Test',0);

  ag_insert($db,1,2,'Test Data 1-2');

  ag_db_write($db);

  ag_db_close($db);

DESCRIPTION

This is DB::Appgen - low-level functions for APPGEN database manipulations (you probably already know what appgen is if you loaded this module, but if you don't please visit http://appgen.com/ - in short it is the sytem behind these green salesman terminals you see in various ikeas, sears and so on).

All this was made in about ten hours including reading perlxstut and perlpod manpages, so do not expect something pretty. Although it appears to be working OK in my tests.

Whenever possible it is recommended to use object oriented interface to appgen. The list of all methods and their equivalent functions follows.

FILE LEVEL METHODS

$db->close;

ag_db_close($db);

Closes underlying database handler. Function must be called in order for the database to be in correct state, while for object oriented method it is only a recomendation to call it.

Object would be closed by perl's garbage collector if you forget about it.

$db=new DB::Appgen file => 'filename', create => 1, hsize => 0, truncate => 1;

ag_db_create('filename', 0, 1);

Creates new database or truncates existing one.

$db->delete_file;

ag_db_delete($db)

Deletes the file associated with the database. Be careful!

$db->lock;

ag_db_lock($db);

Locks database.

$db=new DB::Appgen file => 'filename';

$db=ag_db_open('filename');

Opens existing database.

$db->rewind;

ag_db_rewind(*db);

Re-positions current record pointer to the first record in file.

$db->unlock;

ag_db_unlock($db);

Unlocks database.

RECORD LEVEL METHODS

$db->seek(key => "key", lock => 1);

ag_db_read($db, "key", $lock);

Attempts to find and, if specified, lock the record by given key. Moves current record on success. In case of of error current record is not defined.

$db->commit;

ag_db_write($db)

Writes changes made to the current record to the database.

$db->release;

ag_db_release($db);

Unlocks current record if it is locked; current record becomes undefined.

$db->seek(key => "key", create => 1, size => $size);

ag_db_newrec($db, "key", $size);

Finds and locks existing records or creates new one. Size can be set to the total record size in bytes if you know it, otherwise do not supply it at all.

$db->drop;

ag_db_delrec

Deletes current record which must be locked.

$db->next(lock => 1);

ag_readnext($db);

Moves current record to the next record in the database in random order locking it if required. Returns key text or undef if no more records exist.

FIELD LEVEL METHODS

ag_db_stat($db, $attr, $value);

This method determines the size and composition of a field in the current record. Consult appgen documentation for details.

A number of methods exists to get the same functionality in more straight forward way:

$db->attributes_number;

Returns number of attributes in the current record.

$db->values_number(attribute => $attr);

Returns number of values in the given attribute of the current record.

$db->value_length(attribute => $attr, value => $value).

Returns length of the given value in the given attribute of the current record. If value is not set or is zero then length of entire attribute is returned (for multi-valued attributes this includes value separators).

$db->delete(attribute => $attr, value => $value);

ag_delete($db,$attr,$value);

Deletes given value or attribute in its entirety if no value number is given. Attributes or values after deleted one are renumbered to fill the gap, be careful.

$db->extract(attribute => $attr, value => $value, size => $size);

ag_extract($db,$attr,$value,$size);

Returns the content of the given value or the given attribute if value is zero. Size is not required, by default entire string is returned.

$db->insert(attribute => $attr, value => $value, text => $text);

ag_insert($db,$attr,$value,$text);

Inserts new field into the current record. If there is already a field at $attr/$value it is renumbered one higher.

$db->replace(attribute => $attr, value => $value, text => $text);

ag_replace($db, $attr, $value, $text);

Replaces the field pointed to by attribute and value. Any fields between the end of the current record and the specified field will be created if required.

SUPPORTING METHODS

$db->attribute(attribute => $attr);

Reads entire attribute returning array of all values even if only one exists. Values are numbered from 0, not form 1, be careful!

Returns array reference or array itself in array context.

$db->record;

Reads entire current record into array of the following structure: [ 'key', [ 'multi', 'valued', 'attribute' ], 'single valued attribute', ... ]

Returns array reference or array itself in array context. Values are numbered from 0, not form 1, be careful!

EXPORT

None by default.

AUTHOR

Copyright (c) 2000 XAO Inc., Andrew Maltsev

SEE ALSO

http://xao.com/, http://sourceforge.net/projects/dbappgen/, http://appgen.com/

cpanm DB::Appgen

perl -MCPAN -e shell
install DB::Appgen