scripts.carrubbers.org home scripts@carrubbers.org
ExplorerIndex phpBanners PhpiCalLib PhpXDb Php.XPath SCMS
*

PhpDBaseDb Documentation

Documentation for the dbasedb.php file version 2.1

Contents

Introduction

PhpDBaseDb by J.Jones / N.Swinson.

+======================================================================================================+
| A class for manipulation of dbase databases.
|
| It is based on the PhpXmlDb class and offers a way in which to use the same
| public interface for larger databases that would be too large to be handled
| efficiently by PhpXmlDb.
|
+======================================================================================================+
| Problems and issues
| -------------------
|
| ## FIELD NAMES
| Field names can only be 10 characters long - Only the first 10 characters are
| stored, and the db demands that the first 10 characters be unique for all field
| names in the db.  When you access with the field name that is the complete
| field name (longer than 10 characters) then it will cache the value you entered.
|
+-----------------------------------------------------------------------------------------------+
| ## ERROR REPORTING
| Need to set up some appropriate error reporting, rather than just using trigger error
|
+-----------------------------------------------------------------------------------------------+
| ### TABLE and RECORDS
| The XML version of the database allows us to store multiple tables each with
| possibly multiple record names, but dbase does not give us any convenient place
| to store this meta information and permit us to store multiple schemas 
| simultaneously, so our solution is to support only one table and one record 
| type.  This means that the dbase file has no idea what the name of the table
| or record type is, and will remember this from the first call that is made
| to it.
| 
| An alternative solution would be to have a meta xml file that maped from each
| table/record name pair to a separate dbase file, so one database would be 
| distributed between one XML file and several dbase files.  This would loose
| us the elegance ofhaving a single file solution, so until we actually have
| a robust need for this somewhat bizarre feature that the xml version gave us
| for free, we won't go ahead and try to support it.  Instead we will try to 
| build "relational" databases using some kind of external manually defined and
| policed schema.
|
+-----------------------------------------------------------------------------------------------+
| Copyright:
| 
| dbasedb.php: An abstraction of a dbase db conforming to the PhpXmlDb interface
|
| Copyright (C) 2001-2003 Jeremy Jones, jbjones@users.sourceforge.net
|						 Nigel Swinson, nigelswinson@users.sourceforge.net
|
| This program is free software; you can redistribute it and/or
| modify it under the terms of the GNU General Public License
| as published by the Free Software Foundation; either version 2
| of the License, or (at your option) any later version.
|
| 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
| GNU General Public License for more details.
|
| You should have received a copy of the GNU General Public License
| along with this program; if not, write to the Free Software
| Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
|
+======================================================================================================+

Class CDBaseDbSearch

The CDBaseDbSearch class extends the XPathEngine class.

Public Methods

Private Methods

You really shouldn't be raking about in these functions, as you should only be using the public interface. But if you need more control, then these are the internal functions that you can use if you want to get your hands really dirty.

Public Method Detail


public function Search($XPathSearch)

Do the search

Main entry point into this search class.

Parameter:

string $XPathSearch

An XPath predicate to search for. All records that match the predicate will be returned.

Return Value:

array

An array of recordIDs that match

Line:

Defined on line 144

Method Details: wholeText


public function wholeText($Context)

Obtain the text of a node

The search code calls this function when it needs the text stored at a
given context in the db.

Parameter:

string $Context

A dbasedb "context"

Return Value:

string

The string stored at the $Context in the db or "" if none or not found.

Line:

Defined on line 206

Private Method Detail

Method Details: __construct


public function __construct(&$aFileData, &$aRecordIdToKeyMap, &$aDbaseSchema, &$aIndexes, $aFieldNames)

Constructor

Build one of these per search, or one per session.  You might wanna check the
referencing code if you wanna build one and keep it.

Parameter:

CDBaseDb $DBaseDBObj

The CDBasaeDb object that we are searching.

Line:

Defined on line 124

Method Details: _GetRecord


private function &_GetRecord($RecordID)

Obtain a record by record ID.

Parameter:

			
string $RecordID
The ID of the record we would like to look up.

			
Return Value:
mixed
The array of data for this record, or FALSE if the record was not found
Line:
Defined on line 525

	 Method Details: _BuildIndex

private function _BuildIndex($Field)
Build an index for a given field
Parameter:

			
string $Field
The field we should build an index for.

			
Line:
Defined on line 542

	 Method Details: _FilterByIndex

private function _FilterByIndex($xPathSet, $Field, $Value)
Filter a node set based on the lookup on an index.
Parameter:

			
string $xPathSet
An array of contexts that we are filtering

			
string $Field
The indexed field we are filtering by

			
string $Value
The value of interest

			
Return Value:
array
Array of contexts from $xPathSet that match.
Line:
Defined on line 583
Class CDBaseDb
Public Methods
Private Methods
You really shouldn't be raking about in these functions, as you should only be
		using the public interface.  But if you need more control, then these are the
		internal functions that you can use if you want to get your hands really dirty.
Public Method Detail

	 Method Details: SetOptions

public function SetOptions($aOptions)
Sets options that affect behaviour
Possible options are:
		Indexes (string)
						Specifies a comma separated list of field names for which we want to build
						indexes.  An index will greatly improve the speed of FieldName = 'Value' queries,
						for the field, but this improvement has to offset the cost of building the index.
Parameter:

			
array $aOptions
Array of name = value options to set for the class.  If the 
 							value is unset then the option will be unset.

			
Return Value:
bool
FALSE if one of the options couldn't be set.  TRUE otherwise.
Line:
Defined on line 772

	 Method Details: Open

public function Open($DbFileName, $bCreateDatabase = FALSE, $bNeedWriteAccess = FALSE)
Opens the database file.
This call is part of the PhpXmlDb public interface.  Uptodate comments are kept in
the PhpXmlDb documentation rather than in this class.
Similar Functions:
PhpXmlDb documentation
Line:
Defined on line 793

	 Method Details: Close

public function Close($DbFileName='')
Closes the database by writing it out to a file.
This call is part of the PhpXmlDb public interface.  Uptodate comments are kept in
the PhpXmlDb documentation rather than in this class.
Similar Functions:
PhpXmlDb documentation
Line:
Defined on line 972

	 Method Details: GetTableNames

public function GetTableNames()
Get the table names from the db
The DbaseDb does not have table names, so we will just return an array with one element, TableTag

This call is part of the PhpXmlDb public interface.  Uptodate comments are kept in
the PhpXmlDb documentation rather than in this class.
Similar Functions:
PhpXmlDb documentation
Line:
Defined on line 1215

	 Method Details: GetRecordNames

public function GetRecordNames($TableTag)
Get the record names from a table in the db
The DbaseDb does not have record names, so we will just return an array with one element, RecordTag

This call is part of the PhpXmlDb public interface.  Uptodate comments are kept in
the PhpXmlDb documentation rather than in this class.
Similar Functions:
PhpXmlDb documentation
Line:
Defined on line 1247

	 Method Details: GetFieldNames

public function GetFieldNames($TableTag = '', $RecordTag = '')
Get the field names from the records of a table in the db
The DbaseDb does not have record names, so we will just return an array with one element, RecordTag

This call is part of the PhpXmlDb public interface.  Uptodate comments are kept in
the PhpXmlDb documentation rather than in this class.
Similar Functions:
PhpXmlDb documentation
Line:
Defined on line 1291

	 Method Details: GetSchema

public function GetSchema($TableTag, $RecordTag)
Get schema information for a given set of records in a table.
This call is quick for PhpDbaseDb

This call is part of the PhpXmlDb public interface.  Uptodate comments are kept in
the PhpXmlDb documentation rather than in this class.
Similar Functions:
PhpXmlDb documentation
Line:
Defined on line 1357

	 Method Details: AddRecord

public function AddRecord($TableTag, $RecordTag, $aElementData)
Add a record to the database.
This call is part of the PhpXmlDb public interface.  Uptodate comments are kept in
the PhpXmlDb documentation rather than in this class.
Similar Functions:
PhpXmlDb documentation
Line:
Defined on line 1423

	 Method Details: AddUniqueRecord

public function AddUniqueRecord($TableTag, $RecordTag, $aElementData, $XPathSearch)
Add a record to the database, but only if the Search returns no records for the database.
This call is part of the PhpXmlDb public interface.  Uptodate comments are kept in
the PhpXmlDb documentation rather than in this class.
Similar Functions:
PhpXmlDb documentation
Line:
Defined on line 1494

	 Method Details: ModifyRecord

public function ModifyRecord($TableTag, $RecordTag, $RecordId, $aElementData, $bPreserveContent = FALSE)
Modify a record in the the database.
This call is part of the PhpXmlDb public interface.  Uptodate comments are kept in
the PhpXmlDb documentation rather than in this class.
Similar Functions:
PhpXmlDb documentation
Line:
Defined on line 1582

	 Method Details: RemoveRecord

public function RemoveRecord($TableTag, $RecordTag, $XPathSearch)
Remove a record from the database.
This call is part of the PhpXmlDb public interface.  Uptodate comments are kept in
the PhpXmlDb documentation rather than in this class.
Similar Functions:
PhpXmlDb documentation
Line:
Defined on line 1725

	 Method Details: RemoveRecordId

public function RemoveRecordId($TableTag, $RecordTag, $aRecordIds)
Remove records from the database that are specified by their RecordIds
This call is part of the PhpXmlDb public interface.  Uptodate comments are kept in
the PhpXmlDb documentation rather than in this class.
Similar Functions:
PhpXmlDb documentation
Line:
Defined on line 1837

public function Search($TableTag, $RecordTag, $XPathSearch)
Search a database and return an array of associative arrays of element=content data
This call is part of the PhpXmlDb public interface.  Uptodate comments are kept in
the PhpXmlDb documentation rather than in this class.
Similar Functions:
PhpXmlDb documentation
Line:
Defined on line 1960

	 Method Details: SortSearch

public function SortSearch($aSearchResults, $SortByKey = 0, $bReverseSortOrder = FALSE)
Sort an array of data which has been generated by the Search() function
This call is part of the PhpXmlDb public interface.  Uptodate comments are kept in
the PhpXmlDb documentation rather than in this class.
Similar Functions:
PhpXmlDb documentation
Line:
Defined on line 2020

	 Method Details: Display

public function Display($aSearchResults, $FunctionName, $aFunctionParameters, $bTestFlag = FALSE)
Display search results through a series of Javascript function calls.
This call is part of the PhpXmlDb public interface.  Uptodate comments are kept in
the PhpXmlDb documentation rather than in this class.
Similar Functions:
PhpXmlDb documentation
Line:
Defined on line 2132

	 Method Details: SearchAndDisplay

public function SearchAndDisplay($TableTag, $RecordTag, $XPathSearch, $FunctionName, $aFunctionParameters)
Search a Database and output javascript blocks containing a list of javacript function calls.
This call is part of the PhpXmlDb public interface.  Uptodate comments are kept in
the PhpXmlDb documentation rather than in this class.
Similar Functions:
PhpXmlDb documentation
Line:
Defined on line 2273
Private Method Detail

	 Method Details: __construct

public function __construct()
Constructor
Line:
Defined on line 749

	 Method Details: _FunctionPermitted

private function _FunctionPermitted($MethodName)
Determine if we have permissions to execute a method.
The call will look in the $aPermissions array and also if necessary at the bSecureMode
flag to detmine if the user has the permissions to execute the query.  This function will
trigger_error() if the permission is not granted.
Parameter:

			
string $MethodName
The name of the method that the user is calling

			
Return Value:
bool
TRUE if the user has permissions to run the query, FALSE otherwise.
Line:
Defined on line 2306

	 Method Details: _OpenScriptTag

private function _OpenScriptTag()
Simple helper to draw an open <SCRIPT> block
Line:
Defined on line 2336

	 Method Details: _CloseScriptTag

private function _CloseScriptTag()
Simple helper to draw a close </SCRIPT> block
Line:
Defined on line 2348

	 Method Details: _LockFile

protected function _LockFile($Action = NULL)
Maintains the lock status of the files
Parameter:

			
string $Action
'lock' / 'unlock'
 									if not specified, a locked file will be unlocked and vise-versa

			
Return Value:
bool
result
Line:
Defined on line 2363

	 Method Details: _GetAndProcessHeaders

private function _GetAndProcessHeaders($DbFileName)
Open up a dbase file, reads the header and stores the info in the object
Parameter:

			
string $DbFileName
The file name

			
Return Value:
int
file pointer to dbbase file is success FALSE if failure 
Line:
Defined on line 2483

	 Method Details: _ProcessFileData

private function _ProcessFileData()
Extract all data from a dbf file and save it to the object
Using a previously opened dbase file with the Dbase Identifier stored
in the object, extract all the data from the file and save it to the
object - header information will not be returned, so if field names
are required, use the _GetAndProcessHeaders method
Return Value:
an associative array of file data
Line:
Defined on line 2598

	 Method Details: _SchemaQuery

private function _SchemaQuery($Value, $SchemaId = '')
Evaluates whether or not the value fits the schema ($SchemaId)
Parameter:

			
mixed $Value
The value of the data that is being added

			
int $SchemaId
The position of the schema in the object
 							If it is empty, we assume we are adding a new field

			
Return Value:
bool
FALSE if the value doesn't fit the schema
Line:
Defined on line 2658

	 Method Details: _SetSchema

private function _SetSchema($Field, $Value = '', $SchemaId = NULL)
Evaluates an appropriate schema for the data and updates the schema
Parameter:

			
string $Field
The name of the field

			
mixed $Value
The value of the field: defaults to ''

			
int $SchemaId
The position that the field will hold in the Db	if no value is set one will be assigned

			
Return Value:
array
An associative array of file data
Line:
Defined on line 2778

	 Method Details: _BuildRecordIdMap

private function _BuildRecordIdMap()
Build a lookup map from RecordId to aFileData key
Return Value:
bool
TRUE if success, FALSE if failure
Line:
Defined on line 2941

	 Method Details: _FormatRecordId

private function _FormatRecordId()
Format the $this->RecordIdFieldName field in the databsae
The RecordId field must always be at position 0 in the database and each record
must have a RecordId.
Return Value:
bool
TRUE if success, FALSE if failure
Line:
Defined on line 2962

	 Method Details: _TestRecordIds

private function _TestRecordIds()
Private member that ensure that the RecordIds are set and unique
Return Value:
bool
TRUE is success, FALSE if failure 
Line:
Defined on line 3084

	 Method Details: _GetRecord

private function &_GetRecord($RecordID)
Obtain a record by record ID.
Parameter:

			
string $RecordID
The ID of the record we would like to look up.

			
Return Value:
mixed
The array of data for this record, or FALSE if the record was not found
Line:
Defined on line 3170

	 Method Details: _GetRecordKey

private function _GetRecordKey($RecordID)
Obtain the key into the aFileData that holds the record with the given record ID.
Parameter:

			
string $RecordID
The ID of the record we would like to look up.

			
Return Value:
mixed
The key of the record in aFileData that has $RecordID, or FALSE  if the record was not found
Line:
Defined on line 3191

	 Method Details: _GetAssocRecord

private function _GetAssocRecord($RecordID)
Obtain a record by record ID as an associative array of FieldName => FieldValue
The RecordID itself will not be part of the returned associative array.
Parameter:

			
string $RecordID
The ID of the record we would like to look up.

			
Return Value:
mixed
The associative array for this record, or FALSE if the record was not found.
Line:
Defined on line 3212

	 Method Details: _ConvertToAssocRecord

private function _ConvertToAssocRecord($aRecord)
Convert from a db record to an associative record suitable for returning from the Search() call
Parameter:

			
array $aRecord
A db record, taken from $this->aFileData

			
Return Value:
array
A representation of $aRecord, with no RecordId key, and name=value assoc pairs
Line:
Defined on line 3225

	 Method Details: _GetNewRecordId

private function _GetNewRecordId()
Private member that will get the next RecordId that should be set
Assumes that the record ID is the first field in the record and that record IDs are 
in ascending order.
Return Value:
int
The next available RecordId
Line:
Defined on line 3263

	 Method Details: _TestDatabaseTags

private function _TestDatabaseTags($TableTag, $RecordTag, $bParentDebugFlag=FALSE)
Private method for testing whether database tags are appropriate
PhpDbaseDb can only support one table and one record type per file - therefore if
a user attempts to modify or search for data in a different table or record, we must
FAIL.  At first declaration of TableTag, RecordTag or RecordIdName, the value is saved
and then all subsequent calls must be made using the same values.
Parameter:

			
string $TableTag
Name of the Table, if NULL, will not be tested or cached

			
string $RecordTag
Name of the Record, if NULL, will not be tested or cached

			
bool $bParentDebugFlag
The parent debug flag, will log the result if TRUE.

			
Return Value:
bool
TRUE if the params do not conflict with previously  declared params FALSE if failure.
Line:
Defined on line 3297

	 Method Details: _IsValidFieldName

private function _IsValidFieldName($Name)
Determine if a given name is suitable for using as a field name
Parameter:

			
string $Name
The name of the field we are querying

			
Return Value:
bool
TRUE if the name was valid.  Else FALSE
Line:
Defined on line 3369

	 Method Details: _AddRecord

private function _AddRecord($aElementData, $RecordID = NULL)
Internal method for adding records to the object
Parameter:

			
array $aElementData
Associative array of name => value pairs constituting data

			
int $RecordID
The record ID of the record - default NULL

			
Return Value:
int
0 if addition failed, else the record id of the new record in the db
Line:
Defined on line 3382

	 Method Details: _Search

private function _Search($XPathSearch)
Internal method that will evaluate searches.
Parameter:

			
string $XPathSearch
Definition of the search as valid XPath predicate.

			
Return Value:
array
Associative array of RecordId => Record of search results where the Record is an associative of name => value pairs
Line:
Defined on line 3583

	 Method Details: _RemoveColumns

private function _RemoveColumns()
Filter out columns that are never set, to permit the dynamic deletion of columns.
Return Value:
bool
TRUE on a Successfull scan of the database, FALSE otherwise.
Line:
Defined on line 3666
Class CTestDBaseDb
The CTestDBaseDb class extends the 
		CDBaseDb
		class.
Public Methods
Public Method Detail

	 Method Details: LockFile

public function LockFile($Action = true)
Maintains the lock status of the files.
Testing needs to unlock files without closing.
Parameter:

			
bool $Action
TRUE (default) locks the file, FALSE unlocks it

			
Return Value:
bool
FALSE if the operation failed.
Line:
Defined on line 3799

		
		

	

		
		
	
		

		
		

			Last updated: 17 April 2008 02:15:13.		

		
			© 2008 Carrubbers Christian Centre | Registered Charity No. SC011455

			Conditions of Use |
			Privacy Policy