A Brief Introduction to SDB

[Rob Cozens]

 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