NAME

Db::Ctree - Perl extension to interface with Faircom's CTREE product

SYNOPSIS

  use Db::Ctree qw(:all);

  InitISAM(10,2,4);
  $ptr = Db::Ctree -> new(0,'file.dat',&SHARED);
  $record = $ptr -> fetch_first();
  while ($record)
  {
     print $record."\n";
     $record = $ptr -> fetch_next();
  }

DESCRIPTION

This module allows the use of some ISAM and Low-Level CTREE routines from within perl. It is a PERL5 replacement for CTREEPERL by John Conover.

In addition to base CTREE functionality, the ability to tie a hash to a CTREE table, and some method based access is available.

Base CTREE support.

Support is provided for most low-level and ISAM routines as documented in the Faircom documentation. Those routines that use C structures (resource records, DODA) are not currently supported. A routine that reads DODA records is available in the METHOD access method.

Like in C it is very important to pre-allocate the destination on reads. Db::CTree just calls the Ctree routine... you *WILL* crash perl just as fast as you crash C without preallocating enough space.

Error code functions

With C, error status is available via global variables. Db::Ctree provides functions that access the following global "C" variables.

                    &isam_err
                    &isam_fil
                    &sysiocod
                    &uerr_cod

Perl hash TIE support

A limited Perl hash TIE implementation is available. If the file has been created by a C program, includes resource records, and uses unique keys, it can be TIED to a Perl hash. Unique keys are required because the tie uses the GetRecord facility which requires Unique keys.

TIE returns a pointer you can use for method access.

Preallocating of space is not required for TIE support.

The file is automatically closed when the hash (and ptr returned by TIE) is destroyed or reassigned.

Sample Code: InitISAM(10,2,4); tie %hash, "Db::Ctree",2, $testIfile,&SHARED; foreach (keys (%hash) ) { printf "%-10s=%s\n",$_,$hash{$_}; }

Perl METHOD support

A limited Perl method access is provided. The following methods are available. In case of error, most functions will return undef. For details, use the error function defined above.

These functions ensure enough space is available for the CTREE return values. There is no need to preallocate the space. Variable/Fixed functions are also selected for you.

new (fileno,filename,mode) returns an object reference to the open file.

fetch_first() returns the first record based on the current index.

fetch_gte {$key) note: key modified with current key returns the record just like getGTErecord

fetch_lte {$key) note: key modified with current key returns the record just like getGTErecord

fetch_prev {) returns the record just like getGTErecord

fetch_next {) returns the record just like getGTErecord

unpack_record($record) note: DODA must be stored in file returns hash with fields as keys

Sample Code: InitISAM(10,2,4); $dbptr = Db::Ctree -> new(2, $testIfile,&SHARED); $record = $dbptr -> fetch_first; while ($record) { %hash = $dbptr -> unpack_record($record); print "$hash{COLUMN}\n"; $record = $dbptr -> fetch_next; }

Notes

ISAM and LOW LEVEL calls do not preallocate space (like C). Be sure your variables are big enough! (Method and HASH access do this for you)

InitISAM sets a tag variable in a class with a DESTROY method that should issue a StopUser upon a normal Perl exit (including Die's). This prevents leaving shared memory segments around in server based systems. If you coredump (die without Perl cleaning up), these memory segments can be left around and eventually crash your server!

Ctree functions are not exported by default. EXPORTER tags are available for ALL,ISAM,LOWLEVEL,CONSTANTS and VARIABLES. Personally, I just import tag ":all" and live with the namespace pollution.

I've also included ctdump and ctload. These are some simple ctree perl routines I've written to dump and load tables. (The tables were created by a C program and have resource and DODA structures already.)

Author

Robert Eden CommTech Corporation rmeden@yahoo.com

SEE ALSO

perl(1), Faircom C-Tree Plus Function Reference Guide, Faircom C-Tree Plus Programmer's Guide

cpanm Db::Ctree

perl -MCPAN -e shell
install Db::Ctree