A Brief Introduction to SDB

[Luis]

Hiya,

That sounds perfect for a Rev only DB. Any infos on availability?

Cheers,

Luis.


On 31 May 2007, at 16:41, Rob Cozens wrote:

> From the Database chapter of the Serendipity Reference stack (which  
> is, itself, an SDB front end).:
>
> Database handlers are used to create, access, and maintain stacks  
> created in the Serendipity Database--Binary (SDB) format.
>
> SDBs databases support:
>
> * single-user exclusive update access with multi-user read-only  
> access.
> * client-server exclusive update, shared update & read-only access.
> * multiple record types
> * variable-length records, fields, & keys
> * access by
> 	* Exact or approximate key
> 	* Relative position (first,prev,next,last)
> 	* Record Id (SDB card Id)
> 	* Raw record number (SDB card #-3)
> 	* Inverted key fields
> * update & retrieval of individual fields
> * selection based on field contents
>
> In general, data is passed between the calling stack & SDB via two  
> buffer areas, referred to in examples as "sdbBuffer" and  
> "binaryBuffer".  The contents of sdbBuffer can change from  
> operation to operation; but the general format for reads & writes  
> places the record type in word 1 of line 1, followed by the record  
> key.  Lines 2 to -1 contain the record data (or a portion thereof).
>
> BinaryBuffer is used to file or retrieve binary data which cannot  
> be stored in a Transcript field.
>
> Both buffers are passed by reference.  For example, the calling  
> handler would place the record type & key in sdbBuffer* before  
> calling getSDBRecord, and it would find the actual record type &  
> key in line 1 of sdbBuffer followed by the record content after  
> successful completion of the call.  If the record includes binary  
> data, it is returned in binaryBuffer.  Since binaryBuffer is passed  
> by reference, it must be initialized to empty even if no binary  
> data is sent or received.
> 	
> SDB record types are a maximum of 4 characters, and cannot contain  
> leading or embedded blanks.  Record types are case sensitive.
>
> There are six predefined record types:
>
> * "0" designates that word 2 of sdbBuffer contains the SDB record  
> id (ie: the Revolution card id) instead of a key.
>
> * "#" designates that word 2 of sdbBuffer contains the raw SDB  
> record number (ie: the Revolution card number - 3) instead of a key.
>
> * "+" designates the next record (of the same record type) relative  
> to the user's current position.
>
> * "-" designates the previous record (of the same record type)  
> relative to the user's current position.
>
> * "DICT" designates the SDB Data Dictionary Record.
>
> * "INVX" designates the SDB Inverted Field Index Record.
> 	
> SDB records are delimited lists of fields (items).  The field  
> delimiter used is specified by the calling handler.  IMPORTANT: Num- 
> to-char(30), End of Record, is used by SDB Utilities for database  
> backup & restore; thus its use in user data or as a field delimiter  
> is prohibited. Also, although SDB accepts any field delimiter  
> values from 1 to 256, it is recommended that a delimiter < 128 be  
> used to avoid potential conflicts when running cross-platform in  
> client/server mode.
>
> All SDB commands return true or false in word 1 of the result.  If  
> word 1 is true, an error occurred,	and the error description is in  
> line 2.  Otherwise the result (for reads & writes) returns the  
> record number in word 2, the record count in word 3, and the  
> Revolution card id for the record in word 4.  Note the record  
> number and record count are specific to the record type; so do not  
> confuse the returned record number with the raw SDB record number.
>
> The checkSDBResult command, when called immediately after a  
> database handler call, will sound an alert, display an error  
> message, and return true if the call generated an error.  If the  
> original call was successful, checkSDBResult returns the original  
> result.
> 	
> The SDB handlers determine what database to access by referencing  
> Library stack local variable, sdbDbId, which is returned by  
> openSDBFile.  A user stack can have more than one SDB database open  
> at the same time and maintain a current position in each; however  
> it is the responsibility of the user stack to maintain a table of  
> the ids of all open databases and to set the id of the correct  
> database before each call [see getSDBDbId & setSDBDbId].
>
> SDB includes three template stacks to be used to build standalone  
> applications:  SDB_Utilities.rev, SDB_Server.rev, and  
> SDB_Test_Client.rev.
>
> SDB_Utilities.rev, is used to build a standalone application to  
> create, open, backup, & restore SDB Database files, and to serve as  
> the application to open an SDB databse if the user double-clicks on  
> it instead of opening it from your application.  DO NOT use the  
> stack itself, but build a standalone for your platform using SDB  
> Utilities.rev, optionally including Revolution's animation  
> library.  If you are building for Mac OS, set the creator code for  
> the standalone to "sDIP".
>
> SDB_Server.rev is used to build the SDB Server application for use  
> in client/server mode.
>
> SDB_Test_Client.rev is used to build an exemplar of SDB syntax and  
> client application handlers
>
> SDB also includes sdbTools.rev, a developers' plugIn including  
> Windows registry set up and data dictionary access along with the  
> utility functions available in SDB Utilities, and reVise.rev,a  
> template stack for building a drag-and-drop application for  
> compressing/expanding files/folders.
> 	
> SDB Files are of four types:
>
> *Databases created by SDB Utilities, sdbTools, and the  
> createSDBFile handler are file type "sdb0" and end in ".sb0".
>
> *Compressed database backups created by SDB Utilities and sdbTools  
> are file type "sdb1" and end in ".sb1".
>
> *Compressed gzip files created by reVise, SDB Utilities, and  
> sdbTools are file type "sdb2" and end in ".sb2".
>
> *Compressed gzip archives created by reVise, SDB Utilities, and  
> sdbTools are file type "sdb3" and end in ".sb3"
>
> Apple creator code is "sDIP".
>
> In addition to documenting Library handlers and menus, this  
> Reference serves as an exemplar of the use of an SDB database.   
> Check the scripts throughout this stack for database-related  
> handlers, and use SDB Utilities to open English Reference  
> Text.sb0.  Click on the file cabinet key and enter a valid  
> password  ("Browse" or "Edit").  This enables the Edit menu and/or  
> the Browse menuItem of the File menu.
>
> The following commands and functions provide developer-level access  
> to SDB:
>
> addSDBComments
> changeSDBRecord
> checkSDBResult
> closeSDBFile
> createSDBFile
> deleteSDBRecord
> fileSDBRecord
> findSDBRecord
> getFirstSDBRecord
> getLastSDBRecord
> getSDBClientId
> getSDBComments
> getSDBDbId
> getSDBRecord
> logInSDBClient
> logOutSDBClient
> openSDBFile
> preOpenSDBFiles
> setSDBComments
> setSDBClientId
> setSDBDbId
> theSDBRecordIndex
> unlockSDBRecord
>
> Questions and comments are werlcomed.
>
> Rob Cozens, CCW
> Resident Foole
>
> _______________________________________________
> use-revolution mailing list
> use-revolution at lists.runrev.com
> Please visit this url to subscribe, unsubscribe and manage your  
> subscription preferences:
> http://lists.runrev.com/mailman/listinfo/use-revolution
>