TextDb 5.0 Changes
From MyUPBWiki
The TextDB 5.0 differs so much from TextDB 4.
Note Revision 5 was originally revision 4.4, but was later renamed to V5 so that users don't try to use incompability versions.
Note V5.0's db structure also differs from previous versions of TextDB. Download and Update all your tDBs before trying to use the new tdb.class.php. File not created yet
Developer's Note If you are retrieving the entire header, and are only wanting to use the fields, there are now eight non-field entries instead of five. What this means is for loops, you have to adjust you count($header) to subtract eight instead of five. One new header entry is the "lastBlank" or the fileId of the next blank record to be written. The second new header entry is labelled "blockLength" and is the memo block size. The third new header entry is lablled "blankPos" and is the position of where to find the "blockLength", simular to the "recPos". The new header entries are more for internal purposes.
The first and most important aspect of V5.0 is the new method of storing memo data. The old method would store the begining of and end of memo file reference points in the main table file, taking up 21 bytes of space. The new method of storing memo data only takes up seven bytes of space simply by storing the beginning of memo file reference point. Also it stores them in predefined 108 byte blocks. This number can be changed by the new optional third argument in the tdb::createTable() function. If a memo entry is larger than the defined block, it will use multiple blocks, leaving a reference to the next block in the chain. When deleting/adding blocks, the method is the same as deleting/adding records. See the next paragraph for explaination. Note that Block #0 (the first block) stores the location of the first deleted block, and cannot be used to store data. Furthermore, the new memo data storage method makes the 4.3.5 contribution [tdb::rewriteMemo()] obsolete.
The second most important addition to V5.0 is the physical record storage and deletion method. In previous versions, new records would append the list of records in the file. When deleting records, the table would have to be rebuilt [tdb::rebuild()] to update the *.ref file and remove the blank records from the table file. With the new method of storing and deleting records, the table never has to be rebuilt. When a record is deleted, the bytes are overwritten, but the blank record is not removed. The fileId of the last blank record is stored in the header and every subsequent fileId of the blank records are stored in blank record before it. When adding a record, the tdb::add() will write the new record in the blank record if one exists, if not, it appends it to the end of the table file. the *.ref file is updated after each deletion and not in the tdb::rebuild() function.
The new record storage and deletion method has another effect on the tDB system. Because the table is no longer rebuilt in any functions besides editing/deleting/adding fields, methods of retrieval are also changed. tdb::listRec(), tdb::query(), and tdb::sortAndBuild() are the functions that changed the most, but are not the only ones. Retrieval is now based on order of which the fileId associated with the recordId appear in the *.ref file. In short, in previous versions the "order of records" was physically maintained in the file. In V4.4, the "order of records" is preserved in the *.ref file. tdb::sortAndBuild() rebuilds the *.ref file (or rebuilds the "order of records") to the specifications of the arguments of the function.
Also new in V5 is a change in the table file names. Each table file name is prepended with the database name that it is kept. This is to allow multiple databases to exist in a single directory without confliction. When specifying a table in the tdb::setFp [or tdb::createTable() and tdb::removeTable()], it isn't nessessary to prepend the db name. It is done automatically if you didn't prepend the db name. However when using the tdb::getTableList(), it will return table names with the db prepend.
Fourthly, the new TextDB adds the extention ".ta" to the main table file name. The four extentions of a table are now "ta", "memo", and "ref". This addition was more for developers who access the table directly without the use of a tdb.class.php for debugging purposes, etc.
Next, A tiny bit of space was sacraficed in the tdb.class.phpto add descriptions to the functions, descriping what is returned and what arguments are. These comments comply with Zend Development Environment coding.
Lastly, the function check() has been expanded. Before V5.0, it would only check to make sure the tdb::workingDir was set. It now makes sure the tdb::Db and tdb::workingDir are set and exist. If the tdb::fp[$fp] exists, it also verifies that.
Some minor changes include modify all functions to use the new memo storage method and the new file storage method. tdb::getNumberOfRecords() calculates the number of records using a different proccess. tdb::rebuild() is obsolete and will print an error upon execution. tdb::bytesToSeek() will return a false upon failure, instead of a -1. tdb::sendError has an optional second argument for the line, and uses the trigger() function instead of printing it.
Make sure to thank Tim a.k.a. Pilot on creating an excellent TextDb, a worthy opponent to SQL. I just improve upon his coding. If you have any suggestions for the TextDb, Be sure to first search the forum to make sure no one has posted a simular topic and then if not, then create a new topic, so that we can discuss it.
