PHP Language Reference
To use the Dataman extension on Unix/Linux, you first need to build and install the Dataman library.
Source code and installation instructions are available at the Dataman Sourceforge page
here. Since the initial php release,
just the module code has been made available. The CVS and extnesion code are also available at
Sourceforge. To use it you need to have PHP 5.xx souce installed on your computer. The package
file needs to be extracted while in the 'ext' sub-directory of the PHP source root directory.
Next, change directories up one (cd ..) and run the command:
./buildconf
and proceed building PHP as normal.
The routines listed here are grouped functionally instead of alphabetically.
To get these functions to work, you have to compile PHP with -with-dataman[=DIR], where
DIR is the Dataman install prefix.
The PHP interface to the Dataman server consists of the following routines:
dataman_connect - init and connect to database
dataman_iopen - open an index
dataman_iclose - close an index
dataman_get - get a key from an index
dataman_get_next - get the next key from an index
dataman_get_prior - get the prior key from an index
dataman_get_current - get the current key from an index
dataman_get_first - get the first key from an index
dataman_get_last - get the last key from the named index
dataman_forward - get the next record from the datafile
dataman_back - get the prior record from the datafile
dataman_insert - insert a new record in a datafile
dataman_include - add a new key to an index
dataman_remove - remove a key from the named index
dataman_protect - protect the current record in the named index
dataman_clear - remove the protect bit from the record
dataman_save - save the current state of the named index
dataman_restore - restore the state of a saved index
dataman_delete - delete the current record from the named index
dataman_get_format - get the format number of the current record
dataman_get_key - get the key of the current index
dataman_key_str - get the string rep of the key of the current index
dataman_get_index - get the name of the current index
dataman_get_file - get the name of the current master file
dataman_put_data - put data into a field of the mater record
dataman_mark - mark the master record
dataman_start_transaction - start a new transaction
dataman_commit - commit a transaction to the database
dataman_rollback - cancel a transaction
Any of the routines that retrieves a data record will retrieve that record into a
globally available string array named $master. If the record has been updated with
either the dataman_put_data() function, or has been marked with the dataman_mark()
function, when a new record is retrieved the one currently in memory is automatically
written to the database. Be aware that if you assign values directly to the members
of the $master array, that it won't be written unless you mark the record.
PHP 5
Description
void dataman_connect(string hostname, string database_root);
dataman_connect establishes a connection to the database server on hostname,
and sets the database root directory to database_root.
Returns
None. If there is an error the appropriate message is displayed, and the script terminates.
PHP 5
Description
void dataman_iopen(string ixname, mode);
dataman_iopen opens the named index in the database_root established
during dataman_connect. The mode accepted is either of the constants UPDATE
or RDONLY, for read/write or read only access to the records. There may be
six different indexes open at a time.
Returns
None. If the named index is not in the root directory, or another error
occurs, the appropriate message is displayed and the script terminates.
PHP 5
Description
void dataman_iclose(string indexname);
dataman_iclose closes an open index previously opened with dataman_iopen.
Returns
None.
PHP 5
Description
bool dataman_get(string indexname, string key);
dataman_get retrieves the key and record associated with the key
from the named index. Upon successful return, the previous current
record associated with the $master global variable is written to the
database, and the new record associated with the key is stored in
the $master global variable.
Returns
True on success or False if the key was not found in the named index.
PHP 5
Description
bool dataman_get_next(string index);
dataman_get_next retrieves the next key and it's associated data
record from the named index. Upon successful return, the current
record associated with the $master global variable is written to
the database, and the new record associated with the 'next' key is
stored in the $master global variable.
Returns
True on success or False if the current key is the last in the index.
PHP 5
Description
bool dataman_get_prior(string index);
dataman_get_prior retrieves the prior key and it's associated data
record from the named index. Upon successful return, the current
record associated with the $master global variable is written to the
database, and the new record associated with the 'prior' key is
stored in the $master global variable.
Returns
True on success or False if the current key is the first in the index.
PHP 5
Description
bool dataman_get_current(string index);
dataman_get_current retrieves the current key and it's associated
data record from the named index. Upon successful return, the current
record associated with the $master global variable is written to the
database, and the new record associated with the 'current' key is
stored in the $master global variable.
Returns
True on success or False if the current key has been deleted from the index.
PHP 5
Description
bool dataman_get_first(string index);
dataman_get_first retrieves the lowest order key and it's associated
data record from the named index. Upon successful return, the current
record associated with the $master global variable is written to the
database, and the new record associated with the key is stored in
the $master global variable.
Returns
True on success or False if there are no keys in the index.
PHP 5
Description
bool dataman_get_last(string index);
dataman_get_last retrieves the highest order key and it's associated
data record from the named index. Upon successful return, the current
record associated with the $master global variable is written to the
database, and the new record associated with the key is stored in
the $master global variable.
Returns
True on success or False if there are no keys in the index.
PHP 5
Description
bool dataman_forward(string index);
dataman_forward retrieves the data record immediately following the one
referred to in the named index. Upon successful return, the previous
current record associated with the $master global variable is written
to the database, and the new record associated is stored in the $master
global array. The current key is -not- updated.
Returns
True on success or False if the current record is the last in the datafile.
PHP 5
Description
bool dataman_back(string index);
dataman_back retrieves the data record immediately preceding the one
referred to in the named index. Upon successful return, the previous
current record associated with the $master global variable is written
to the database, and the new record associated is stored in the $master
global variable. The current key is -not- updated.
Returns
True on success or False if the current record is the first in the datafile.
PHP5
Description
void dataman_insert(int fmt, where, string index);
dataman_insert will insert a new blank record of format fmt
into a datafile either before or after the record currently
referred to by index. Where may be either of the constants
BEFORE, or AFTER, for inserting the new record before or after
the specified record.
Returns
None.
PHP 5
Description
void dataman_include (string src_index, string dest_idx, string key);
dataman_include will associate the record referred to in the
src_index with key, and place that key in dest_idx.
Returns
None.
PHP 5
Description
bool dataman_remove(string index, string key);
dataman_remove removes the named key from the specified index. It
does -not- remove the associated data record.
Returns
True on success or False if the named key is not found in the index.
PHP 5
Description
bool dataman_protect(string index);
dataman_protect 'locks' the record currently referred to by the named index.
Returns
True on success or False if the record is already protected.
PHP 5
Description
void dataman_clear(string index);
dataman_clear unlocks the record currently referred to by the named index.
It is an unconditional clear; it will remove the lock regardless of who applied it.
Returns
None.
PHP 5
Description
void dataman_save(string index);
dataman_save saves the current state of the index; the current key
(last obtained from any of the get routines) and the current record
(not necessarily the record referred to by the current key). There
is only one level of save, if you do multiple saves with no intervening
restore, only the last state is saved.
Returns
None.
PHP 5
Description
bool dataman_restore(string index);
dataman_restore returns the index to the state it was in when
save was called. The current record associated with the $master
global variable is written to the database, the system key is
set to the index key, and the saved current record is stored
in the $master global variable.
Returns
True on success or False if the saved key has been removed, or the data record has been deleted.
PHP 5
Description
void dataman_delete(string index);
dataman_delete removes the record currently referred to by the
named index from it's datafile. Any keys referring to that record
will (eventually) be removed. The record stored in the $master data
record will be the record following the deleted one, or if the
deleted record was last in the data file, the one prior.
Returns
None.
PHP 5
Description
int dataman_get_format(void);
dataman_get_format retrieves the record format number of the record
currently associated with the $master data record.
Returns
The current format number
PHP 5
Description
string dataman_get_key(void);
dataman_get_key returns a string representing the internal system key
ie the key associated with last of any of the get*(index) functions.
This is particularly useful for retrieving a specific instance of a key,
as duplicate keys are allowed in the index.
Returns
A string representation of the system key.
PHP 5
Description
string dataman_key_str(void);
dataman_key_str returns a displayable string representing the internal
system key, ie the key associated with last of any of the get*(index) functions.
Returns
A displayable string representation of the system key.
PHP 5
Description
string dataman_get_index(void);
dataman_get_index returns the string name of the last accessed index.
Returns
The name of the last accessed index.
PHP 5
Description
string dataman_get_file(void);
dataman_get_file returns the filename that the current database record
was retrieved from. Not the full path name.
Returns
The data record's file name.
PHP 5
Description
void dataman_put_data(field, string value);
dataman_put_data stores data in a data field and marks the record.
This is the preferred way to store data in a field, and the only way
to correctly store blob data. The data field is the array element of
the $master global variable that you wish to store,the data in. The
value may also be of type string, int, float, or blob, but if storing
a blob, the field must have been defined as a blob during datafile
creation.
Returns
None.
PHP 5
Description
void dataman_mark(void);
dataman_mark marks the data record in the $master variable as having been changed.
Returns
None.
PHP 5
Description
void dataman_start_transaction(void);
dataman_start_transaction marks the start of a transaction. Any modifications to
the database are not written until a call to dataman_commit() is performed. If any
part of the transaction fails during the commit all parts fail. Another way to
terminate a transaction is with a call to dataman_rollback. This cancels the
transaction without writing anything to the database.
Returns
None.
PHP 5
Description
bool dataman_commit(void);
dataman_commit terminates a transaction and commits all modifications to the database
since dataman_start_transaction was called. The commit is atomic: if any part of the
commit fails, all fail and it is as if dataman_rollback() were called.
Returns
True if successful, else False.
PHP 5
Description
void dataman_rollback(void);
dataman_rollback terminates and cancels a transaction. None of the database modifications
since dataman_start_transaction() are written.
Returns
None.