view release on metacpan or  search on metacpan

Appgen.pm  view on Meta::CPAN

is only a recomendation to call it.

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

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

=head2 ag_db_create('filename', 0, 1);

Creates new database or truncates existing one.

=head2 $db->delete_file;

=head2 ag_db_delete($db)

Deletes the file associated with the database. Be careful!

=head2 $db->lock;

=head2 ag_db_lock($db);

Locks database.

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

=head2 $db=ag_db_open('filename');

Opens existing database.

=head2 $db->rewind;

=head2 ag_db_rewind(*db);

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

=head2 $db->unlock;

=head2 ag_db_unlock($db);

Unlocks database.

=head1 RECORD LEVEL METHODS

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

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

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

=head2 $db->commit;

=head2 ag_db_write($db)

Writes changes made to the current record to the database.

=head2 $db->release;

=head2 ag_db_release($db);

Unlocks I<current record> if it is locked; I<current record> becomes
undefined.

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

=head2 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.

=head2 $db->drop;

=head2 ag_db_delrec

Deletes I<current record> which must be locked.

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

=head2 ag_readnext($db);

Moves I<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.

=head1 FIELD LEVEL METHODS

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

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

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

=over

=item $db->attributes_number;

Returns number of attributes in the I<current record>.

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

Returns number of values in the given attribute of the I<current record>.

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

Returns length of the given value in the given attribute of the
I<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).

=back

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

=head2 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.

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

=head2 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.

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

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

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