GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  ASCIIDB::TAGFILE (3)

.ds Aq ’

NAME

AsciiDB::TagFile - Tie class for a simple ASCII database

CONTENTS

SYNOPSIS



 # Bind the hash to the class
 $tieObj = tie %hash, AsciiDB::TagFile,
        DIRECTORY => $directory,
        SUFIX => $sufix,
        LOCK => $bool,
        READONLY => $bool,
        CACHESIZE => $cacheSize,
        FILEMODE => $mode,
        SCHEMA => {
                ORDER => $arrayRef
                KEY => {
                        ENCODE => $subRef,
                        DECODE => $subRef
                }
        };

 # Save to disk all changed records
 $tieObj->sync();

 # Remove all records from memory (and save them if needed)
 $tieObj->purge();

 # Remove all records from memory (and save them if needed)
 #      iif there are more than $cacheSize records in memory
 $tieObj->purge($cacheSize);

 # Get all record keys
 @array = keys %hash;

 # Check if a record exists
 exists $hash{$recordKey}

 # Get a field
 $scalar = $hash{$recordKey}{$fieldName};

 # Assign to a field
 $hash{$recordKey}{$fieldName} = $value;



DESCRIPTION

The <B>AsciiDB::TagFileB> provides a hash-table-like interface to a simple ASCII database.

The ASCII database stores each record in into a file:



        $directory/recordKey1$sufix
        $directory/recordKey2$sufix
        ...
        $directory/recordKeyI<N>$sufix



And a record has this format:



        [fieldName1]: value1
        [fieldName2]: value2
        ...
        [fieldNameI<N>]: value2



After you’ve tied the hash you can access this database as access a hash of hashes:



        $hash{recordKey1}{fieldName1} = ...



To bind the %hash to the class AsciiDB::TagFile you have to use the tie function:



        tie %hash, AsciiDB::TagFile, PARAM1 => $param1, ...;



The parameters are:
DIRECTORY The directory where the records will be stored or readed from. The default value is the current directory.
SUFIX The records are stored as files. The file name of a record is the key plus this sufix (if supplied).

For example, if the record with key ’josear’ and sufix ’.record’, will be stored into file: ’josear.record’.

If this parameter is not supplied the records won’t have a sufix.

LOCK If you set this parameter to 1 TagFile will perform basic locking. Record files will be share locked before reading them, and exclusive locked when syncing (writing) them.

This basic locking only guarantees that a record file is always written correctly, but as TagFile keep records in memory you can still suffer consistency problems reading fields.

The default value is 0, i.e. the database won’t be locked.

READONLY If you set this parameter to 1 the database will be read only and all changes will be discarted.

The default value is 0, i.e. the database can be changed.

CACHESIZE Records loaded from disk (or simply created) are keeped in memory till the tied hash is deleted. You can limit the number of records in memory setting this option to a value ($cacheSize).

All records are purged from memory if their count reach $cacheSize.

You can purge the records manually using the purge() method.

Of course, the $caseSize should be a positive number, and you can use the 0 value to turn off the caching (useful when testing).

The default value for CACHESIZE is ’infinite’ (more or less...)

FILEMODE Filemode assigned to new created files.

If this parameter is not supplied the new created files will have the default permissions.

SCHEMA This parameter is a hash reference that contains the database definition.

With ORDER you can specify in which order fields will be saved into the file.

For example,



 SCHEMA => {
        ORDER => [ fieldHi, field2There, fieldWorld ]
 }



will save the record this way:



        [fieldHi]: ...
        [fieldThere]: ...
        [fieldWorld]: ...



NOTE: this parameter is MANDATORY, and you have to specify all the fields. <B>If you forget to list a field it will not be savedB>.

With KEY,ENCODE and KEY,DECODE you can define an special encoding for keys when used as filenames.

For example, if using this SCHEMA:



 SCHEMA => {
         ORDER => [a, b, c],
         KEY => {
                 ENCODE => sub { $_[0] =~ s{/}{_SLASH_}g; $_[0] },
                 DECODE => sub { $_[0] =~ s{_SLASH_}{/}g; $_[0] },
         }
 }



a record with the key ’s1/s2’ will be saved into filename ’s1_SLASH_s2’. The DECODE subroutine is used to traslate back to the original key.

NOTE: You should use this feature if you allow filesystem metacharacters (as ’/’, used in Unix to split path components) in your keys.

The data will be saved to disk when the hash is destroyed (and garbage collected by perl), so if you need for safety to write the updated data you can call the <B>syncB> method to do it.

EXAMPLES



 $dbObj = tie %tietag, AsciiDB::TagFile,
        DIRECTORY => data,
        SUFIX => .tfr,
        FILEMODE => 0644,
        SCHEMA => { ORDER => [name, address] };

 $tietag{jose}{name} = Jose A. Rodriguez;
 $tietag{jose}{address} = Granollers, Barcelona, SPAIN;
 $tietag{cindy}{name} = Cindy Crawford;
 $tietag{cindy}{address} = YouBetIwouldLikeToKnowIt;

 my $key;
 foreach $key (keys %tietag) {
        print $tietag{$key}{name}, "\t", $tietag{$key}{address},
                "\n";
 }



Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 TAGFILE (3) 2001-02-02

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.