Searchable Memory Blocks
Applies to: WG3.x
Editor's note: this chapter is new in the WG3 layer. It is from section 7 ("Searchable Memory Blocks") of the Developer's Addendum for Worldgroup 3.12 (
wg312dev; the earlier 3.10 edition,devad3, is the same text apart from "3.10" for "3.12",BC5forBC50, InstallShield V5.0 for V5.1 and spelling). The addendum has no figures. Prose is unrewritten; "Header check" notes record where the printed text disagrees with the WG3.2 headers. Searchable memory blocks (smb*(),SMBAPI.H) are non-persistent in-memory keyed tables, the counterpart of the Btrievedfa*()functions of chapter 9.
With the creation of WorldLink MajorLink it became obvious that we needed a mechanism for storing large amounts of information on DOS systems. The realization that we could have hundreds, or even thousands of simultaneous users intermingling prompted us to create the Searchable Memory Block API or (GALSMB).
SMBs (searchable memory block) are similar to Btrieve, however, the data is not persistent. You create an SMB by calling smbOpen(), then you can insert, remove or retrieve records on an as needed basis. You specify the number of records to store in memory, and the rest are swapped out to file. Once the server is shut down, all SMBs are closed and the data is lost.
SMB API
SMBKEYTABLE structure
typedef struct smbKeyTable { /* Key table structure for datafile */
USHORT Offset; /* Offset of where the key starts */
smbCompFunc Compare; /* Key comparison routine */
} SMBKEYTABLE, *pSMBKEYTABLE;...
A pointer to a compare routine. You may use any of the default compare routines, or create your own.
smbClose()
VOID
smbClose( /* Close an SMBHANDLE */
SMBHANDLE smb); /* Pointer to file to close */...
Handle of the SMB returned from smbOpen.
smbCurrentData()
VOID * /* Pointer to data or NULL */
smbCurrentData( /* Gets data of current record */
SMBHANDLE smb); /* Pointer to smb information */...
Pointer to the current SMB record.
smbCurrentNumber()
SMBPTR /* Absolute number of current record */
smbCurrentNumber( /* Gets current position of record */
SMBHANDLE smb); /* Handle to smb information */...
A number associated with the current record.
smbDelete()
VOID
smbDelete( /* Deletes the current record pointer */
SMBHANDLE smb); /* Pointer to file to delete */...
Handle of the SMB to delete from.
smbGetBynum()
VOID * /* Pointer to data or NULL */
smbGetBynum( /* Get record by absolute number */
SMBHANDLE smb, /* Handle to smb information */
SMBPTR Number, /* Record number to get */
UINT Key); /* Key number to load as current */...
A pointer to the SMB record or NULL if not found.
smbGetEqual()
VOID * /* Pointer to data or NULL */
smbGetEqual( /* Get a record from a database */
SMBHANDLE smb, /* Pointer to file to update */
const VOID *KeyInfo, /* Key we are searching for */
UINT Key); /* Key number to look up by */...
A pointer to the data matching KeyInfo, or NULL if the key was not found.
smbGetGreater() and smbGetLess()
VOID *
smbGetGreater( /* Get greater than a key */
SMBHANDLE smb, /* Pointer to file to update */
const VOID *KeyInfo, /* Key we are searching for */
UINT Key); /* Key number to look up by */...
A pointer to the data matching KeyInfo, or NULL if the key was not found.
smbGetHigh() and smbGetLow()
smbGetHigh( /* Get highest record in the tree */
SMBHANDLE smb, /* Handle to smb information */
UINT Key); /* Key to get highest on */...
A pointer to the highest or lowest record.
smbGetPrevious() and smbGetNext()
VOID * /* Pointer to data or NULL */
smbGetPrevious( /* Get previous from current record */
SMBHANDLE smb); /* Handle to current smb pointer */...
A pointer to the SMB record, or NULL if there are no more records.
smbInit()
VOID
smbInit(VOID); /* initialize SMB API before using */Initializes the Searchable Memory Block API. This function must be called before any other SMB APIs are used.
smbInsert()
VOID *
smbInsert( /* Insert a record into datafile */
SMBHANDLE smb, /* Pointer to file to insert to */
const VOID *data); /* Data to insert */...
A pointer to the newly created SMB record.
smbOpen()
SMBHANDLE /* Pointer to open file */
smbOpen( /* Open an in memory file */
size_t DataLength, /* Maximum length of file to open */
pSMBKEYTABLE keyptr, /* Pointer to the key table */
UINT CachedRecords); /* Records to Cache */...
A handle to the newly created SMB.
The Query Routines
The functions smbQueryEqual(), smbQueryPrevious(), smbQueryNext(), smbQueryGreater(), smbQueryLess(), smbQueryLow() and smbQueryHigh() can be used instead of the smbGet... functions. The query set of routines take the same paramaters, but return TRUE or FALSE instead of a pointer to the data.
The default compare functions
The functions smbCompareString(), smbCompareLONG(), smbCompareINT(), and smbCompareSHORT() are generic routines created to compare key types. You may create your own conversion functions to suite your specifc needs. Each function is similar to this one:
...
RIGHTHIGH if test > target,
EQUAL if test = target.
Compare functions
When records are inserted, it is necessary to compare the inserted key data with existing key data. As records are being inserted into an SMB, a tree is also built for each key. When a new record is inserted, it is continuously compared against the nodes on the tree to find the proper place of insertion. The proper format for a compare routine is as follows:
...
A number of default compare routines are provided to aid you in creation of your SMB.
Sample SMB application
The following is a sample program using the SMB API to store a list of Client/Server users. The users can be listed out by using the global “/USERS”.
...