Bmd.pm functions

new
Creates an empty Bmd object. If you supply an indexfilename, it will run &readindexfile() for you. Then it won't be so empty.
Usage:
my $bmd = new Bmd; #In Perl, that's equivalent to: my $bmd = Bmd->new();
my $bmd = new Bmd("indexfile.bmd"); # Returns not-so-empty object ref

destroy
Obliterates everthing that isn't saved to files.
Usage:
$bmd->destroy(); # $bmd should be undefined now

findfile
Attempts to locate files in current directory and member directory. It returns the adjusted filename with member directory added if necessary. It searches web sites if the file name begins with "http://". Also returns an error in a second field if the name cannot be found.
Not meant for public usage:
($correctfilename, $err) = $bmd->findfile("filename.tbl");
# $err will be undef if nothing went wrong.

getfile
Uses &findfile() to locate supplied filename plus returns the lines of that file in an array of strings.
Not meant for public usage:
($correctfilename, $err, $filedata) = $bmd->getfile("filename.tbl");
# $filedata is an array ref. The rest comes from &findfile()

readindexfile
Opens supplied file name as an indexfile. Populates a lot of Bmd object values including the member directory, the schema objects (using Bmdschema->readschemafiles), and the filelist objects for schemas and tables. Also makes reject assignments and reads today's sync file if it exists, but will not read table files. Returns any errors in an array.
Usage:
my $bmd1 = new Bmd;
my @errs = $bmd1->readindexfile("indexfile.bmd");
# Almost equivalent to:
my $bmd1 = new Bmd("something.bmd"); # This will not return errors.
# To open a remote database...
my $bmd2 = new Bmd;
my @errs = $bmd2->readindexfile("http://www.whatever.net/~me/indexfile.bmd");

setsyncfile
Creates today's syncfile name by appending today's date to the prefix supplied and sets the days-to-live number. They are stored in object members Bmd->{"syncfile"} and Bmd->{"syncdtl"}. If no input is supplied, then the syncfile is named after the indexfile, and days-to-live is 90. Also reads the contents of today's sync file if it exists.
Not meant for public usage:
$bmd->setsyncfile("something.sync", 30);
$bmd->setsyncfile(); # Set everthing to default

getsyncfile
Returns the name of today's sync file.
Usage:
$name = $bmd->getsyncfile();

getsyncdtl
Returns the number days that sync files are supposed to last.
Usage:
$dtlnum = $bmd->getsyncdtl();

getmemberdir
Returns the name of the member directory.
Usage:
$mdirname = $bmd->getmemberdir();

savetest
Tests for write access to supplied indexfile, member directory, and modified table files and schema files. Returns any errors in an array. This is meant to be run before &saveallfiles() to find problems ahead of time. The indexfile name could be a new file name as if you are planning to "Save As". &savetest() will attempt to move the mdir and other files to the new indexfile's directory. Note this does not actually save files.
Usage:
my @errs = $bmd->savetest(); # Assumes current indexfile name.
my @errs = $bmd->savetest($indexfilename); # "Save As" new name

saveallfiles
This one saves all modified files including today's sync file. It's best to run &savetest() before. Supply a new indexfile name if you want to "Save As", but remember that will move the member directory and other files to the new indexfile's directory which is probably what you want anyway. Returns any errors in an array.
Usage:
@errs = $bmd->savetest(); # or @errs = $bmd->savetest("newname.bmd");
if (@errs) {die "Test failed!\n";}
@errs = $bmd->saveallfiles(); # or @errs = $bmd->saveallfiles("newname.bmd");
if (@errs) {die "Save failed!\n";}

savesyncfile
Used by &saveallfiles() to save today's syncfile. For a Save As, you must supply an new member directory. Returns a single error if it can't write to the file.
Not meant for public usage:
my $errs = $bmd->savesyncfile(); # Normal save
my $errs = $bmd->savesyncfile("newmdir"); # Save As

readtablefiles
Reads all table files or just the specified tables. Populates the Bmdtable object Bmd->{"tabledata"} using Bmdtable->readtablefiles(). Returns errors in an array.
Usage:
my $bmd = new Bmd();
my @errs = $bmd->readindexfile("indexfile.bmd");
if (@errs) {die "Problem reading indexfile\n";}
@errs = $bmd->readtablefiles(); # Reads all tables
if (@errs) {die "Problem reading the table files\n";}
# Or to read just a few tables...
@errs = $bmd->readtablefiles("tablename1", "tablename2"); # Reads two tables

readdataspacefiles
Reads all table files for just the tables in the specified dataspace. Uses Bmdtable->readtablefiles() just like &readtablefiles(). Without a dataspace, it just reads all tables. Returns errors in an array.
Usage:
@errs = $bmd->readdataspacefiles("normal"); # Reads all normal tables
@errs = $bmd->readdataspacefiles(); # Equivalent to $bmd->readalltables();

logchanges
Creates syncfile formatted lines for inserts, updates, etc and records them using &makesynclines(). This is used by Bmdtable->update() and Bmdtable->insert_pos().
Not meant for public usage:
# inserts: supply tbl, new recnum, new @record, and optional creation date, hopcount
$bmd->logchanges("insert","tablename", $recnum, $record, $cdate, $hopcount);
# updates: table, recnum, @flds changed, new @vals, and optional mod_time, hopcount
$bmd->logchanges("update","tablename",$recnum,$flds,$vals,$mod_time,$hopcount);

makesynclines
Used by &logchanges() to format syncfile lines and store them in Bmd->{"syncfiledata"} until they are saved to disk by &savesyncfile().
Not meant for public usage:
# Supply the same stuff the &logchanges() gets without the tablename
$bmd->makesynclines("insert", $recnum, $record, $cdate, $hopcount);
$bmd->makesynclines("update",$recnum,$flds,$vals,$mod_time,$hopcount);

deletesynclines
Used by Bmdtable->delete_pos to remove syncfile lines from Bmd->{"syncfiledata"} before they are save to disk. This effectively prevents the spread of a deleted record.
Not meant for public usage:
# Supply record number of deleted record before it is removed.
$bmd->deletesynclines("tablename", 15);

listsyncfiles
Returns a list of syncfile names that could be more recent than the supplied epoch relative time. It does not check the real modification times. Without a time input, it will list all syncfiles that exist.
Usage:
my @files = $bmd->listsyncfiles();
my $now = time();
@files = $bmd->listsyncfiles($now);

listallfiles
Returns a list of all database files including indexfile, syncfiles, table files, and schema files. Uses, &listsyncfiles(), Bmdfilelist->listfiles().
Usage:
my @files = $bmd->listallfiles();

getvalsfromarray
Returns the elements of an array that would be in same positions as the supplied fields if that array were a record in the supplied table.
Usage:
my $array = ["array_element_1", "elem2", "elem3"];
my $fldlist = ["fldname1", "fldname2"];
my @vals = $bmd->getvalfromarray("tablename", $array, $fldlist);

listtables
Wrapper for Bmdschema->listtables().

listtablefiles
Wrapper for Bmdfilelist->listfiles().

listschemafiles
Wrapper for Bmdfilelist->listgroups().

listfields
Wrapper for Bmdschema->listfields().

getfieldnum
Wrapper for Bmdschema->getfieldnum().

getfieldmap
Wrapper for Bmdschema->getfieldmap().

makereject
Wrapper for Bmdtable->makereject().

getreject
Wrapper for Bmdtable->getreject().

select
Wrapper for Bmdtable->select().

selectbykey
Wrapper for Bmdtable->selectbykey().

selectbynum
Wrapper for Bmdtable->selectbynum().

getrecnumbykey
Wrapper for Bmdtable->getrecnumbykey().

update
Wrapper for Bmdtable->update().

insert_pos
Wrapper for Bmdtable->insert_pos().

delete_pos
Wrapper for Bmdtable->delete_pos().

rejectbynum
Wrapper for Bmdtable->rejectbynum().

unrejectbynum
Wrapper for Bmdtable->unrejectbynum().

droptable
Wrapper for Bmdschema->destroy(). Identical to &dropfield().

dropfield
Wrapper for Bmdschema->destroy(). Identical to &droptable().

getschemaref
Wrapper for Bmdschema->getschemaref().

gettableref
Wrapper for Bmdtable->gettableref().

getprimarykey
Wrapper for Bmdschema->getprimarykey().

getdataspace
Wrapper for Bmdschema->getdataspace().