AccessDBM - A PHP3 Wrapper to the DBM functions
include("class.AccessDBM.php3");
$static = true;
$dbase = new AccessDBM("/path/to/file.dbm",$static);
register_shutdown_function($dbase->static_close());
if(!$dbase->add_entry("cdi","cdi@thewebmasters.net))
{
echo "Error adding entry: $dbase->ERROR\n";
}
$Values = $dbase->get_all()
while ( list ($key,$val) = each ($Values) )
{
echo "Key: $key Val: $val \n";
}
exit;
AccessDBM is a simple wrapper for the PHP3 dbm file functions. It's
primarily used for quick-and-dirty ``single-method'' programs.
This is the new() method, called as $dbm = new
AccessDBM (args). Older versions of PHP cannot accept args in the
new() method. If this is the case, use the
initialize() method. See the initialize() method
for the rest of the arg documentation.
The initialize() method requires the full path and name of the
dbmFile to manipulate, and optionally a numeric argument. If the optional
argument == 1, the dbm file will be opened and will be left open for the
life of the process. If you open the dbm file with the Static bit set, you must call the static_close() method to close the dbm file when
you're done. You can facilitate this very easily by using the PHP
register_shutdown_function() method. (See the PHP
documentation for this). Only use the static method if you absolutely have
to. The class will manage the dbmFile on it's own quite well but there are
instances where you need to have the file left open in order to work
properly. (eg, multiple writes to the file during the same process, etc..)
Adds key to the dbm file with the associated val. If the key already exists in the dbmfile, it will be overwritten with the new val. Returns true on success, false on failure or if the
dbmfile cannot be opened for writing.
Removes the specified key from the dbmfile. Returns true on success, false
if the key does not exist or if the file cannot be opened for writing.
Will open the dbm file (if not already open) in readOnly mode and retrieve
the value for the specified key. Returns the value on success, null if the
key does not exist or if the file could not be opened for reading.
This is an internal method and should never be called directly! Let the other methods worry
about when and how to open the dbm file.
Given a value, will attempt to find a similar key in the dbm file. It first
checks for an exact match and if that fails, does a case insensitive key
search looking for similar keys. If the key search gets an exact match, the
global variable EXACT is set to true. Otherwise EXACT is set to false, and
the closest matching key is returned. Returns null if no key comes close to
matching the search string. Keys are CASE SENSITIVE.
Given a value, find_val() searches the VALUES of the dbm file
for the closest, case sensitive match. If it finds an EXACT match, the
EXACT variable is set to true. Otherwise it does a search on the values
similar to find_key().
Returns an array of key=>value pairs as they appear in the dbm file.
(Unsorted).
This is an internal method and should never be called by your programs. Let the class worry
about when and how to close the dbm file.
This method must be called if the new() or initialize() methods
are given the static bit. Closes the dbm file. Returns false if the dbm
file was not opened staticly.
This variable contains the text of the last ERROR encountered. If a method
fails, the text description of why the method failed can be retrieved by
grabbing this variable. eg; echo ``Ooops $class->ERROR \n'';
The number of keys in the current DBM file. It is only set after a call to
get_all().
After a call to get_all(), the VALUES global variable will
contain the array that get_all() returns.
The global that points to the path and file name specified in the last
new() or initialize() method.
Set to true of the dbmfile pointed to by new() or
initialize() already exists. If the dbm file does not exist,
the first attempt to access the dbm file will create it. (Provided the
process has permission to create files in the directory specified by
new() or initialize(). )
Set to true and the next method invoked on the dbm file will leave the dbm
file open until a call to static_close() is made.
If either of the two search methods (find_key() or find_val())
find an exact match, this variable is set to true.
This var only exists if the file is opened staticly. It maintains the file
pointer during the life of the process.
see SYNOPSIS - this class is fairly easy to figure out.
You're reading it.
Copy the class file to the location specified in your PHP3.INI file.
Failing that, use the full path to the class file's location in your
include() directive.
This class works best with single-method processes, eg, one process to add
an entry, one process to remove an entry, show the contents etc.. Things
start to fall apart if you try to do too much at once with a dbm file due
to the file locking that PHP implements on the dbm file.
Not opening the dbm file in static mode will cause problems if you try to
do more than 1 thing to a dbm file. In non-static mode, any method that
accesses the dbm will generate an exclusive lock on the dbm file. The
moment that method returns, the dbm file is closed, but the lock DOES NOT
GET REMOVED until the end of the process, which means any further attempts
to access the file, even in readonly mode, will fail.
Version 1.1, 1999/02/20 CDI, cdi@thewebmasters.net
Copyright (c) 1999, CDI - cdi@thewebmasters.net. All Rights
Reserved.
This program is free software; you can redistribute it and/or modify it
under the GNU General Artistic License, with the following stipulations;
Changes or modifications must retain these Copyright statements. Changes or
modifications must be submitted to the AUTHOR, cdi@thewebmasters.net.
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the Artistic License for more
details. This software is distributed AS-IS.
http://www.thewebmasters.net/php/
http://php.codebase.org/
The PHP3 DBM function documentation.
none
Version 1.1 - Initial Public Release