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@lists.runrev.com
Please visit this url to subscribe, unsubscribe and manage your subscription
preferences:
http://lists.runrev.com/mailman/listinfo/use-revolution
