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", BC5 for BC50, 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 Btrieve dfa*() functions of chapter 9.

With the creation of 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;

Defines the the location, and the routines used to compare keys within the data being inserted into SMBs.

Offset

The offset, within inserted data, that the key starts.

Compare

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            */

Closes an opened SMB. This function deletes any swap files used, as well as freeing all allocated memory dealing with the opened SMB.

smb

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          */

Retrieves a pointer to the last record obtained using the smbGet... functions.

smb

Handle of the SMB to get the current record from.

Returns

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           */

Retrieves a number associated with the current SMB record. This is similar to the dfaAbs() function. This number can be used in cycled calls to smb data.

smb

Handle of the SMB to get the current record number of.

Returns

A number associated with the current record.

smbDelete()

VOID
smbDelete(                         /*  Deletes the current record pointer  */
SMBHANDLE smb);                    /*  Pointer to file to delete           */

Deletes the last record read by using one of the smbGet... functions.

smb

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       */

Retrieve a record by record number. The record number can be obtained using smbCurrentNumber().

smb

Handle of the SMB to get the record from.

Number

The record number of the record to retrieve.

Key

The key number to load the record by.

Returns

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            */

Retrieve a record that has a key equal to the one you provide.

smb

Handle of the SMB to get from.

KeyInfo

Pointer to a key you wish to look up by.

Key

Key Number to compare KeyInfo with. This corresponds to your SMBKEYTABLE structure passed to smbOpen().

Returns

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            */
VOID *
smbGetLess(                        /* Get less 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            */

Retrieve a record greater or less than a specified key value.

smb

Handle of the SMB to get a record from.

KeyInfo

Pointer to a key you wish to look up by.

Key

Key number to retrieve the record by. This corresponds to your SMBKEYTABLE structure passed to smbOpen().

Returns

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               */
VOID *                             /* Pointer to data or NULL              */
smbGetLow(                         /*  Get the lowest record in the tree   */
SMBHANDLE smb,                     /*  Handle to smb information           */
UINT Key);                         /*  Key to get lowest on                */

Get the highest or lowest record by key from an SMB.

smb

Handle of the SMB to get a record from.

Key

Key number to look up with. This corresponds to your SMBKEYTABLE structure passed to smbOpen().

Returns

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       */
VOID *                             /* Pointer to data or NULL              */
smbGetNext(                        /*  Get next from current record        */
SMBHANDLE smb);                    /*  Handle to current smb pointer       */

Get the previous or next record in sequence. The key used to retrieve the record is determined by the last call to a get function that requires a key.

smb

Handle of the SMB to get a record from.

Returns

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                      */

Inserts a record into an SMB.

smb

Handle of the SMB you want to insert to.

data

A pointer to the data. This data must be the length that you passed to your smbOpen() call.

Returns

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                    */

Creates a searchable memory block.

DataLength

Maximum length of the data that will be inserted into this SMB.

keyptr

Pointer to a SMBKEYTABLE structure specifying the different keys that are used during get operations.

CachedRecords

The number of records to be saved in memory at any one time.

Returns

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:

INT                                /* LEFTHIGH, EQUAL, or RIGHTHIGH        */
smbCompareString(                  /*  Generic string compare routine      */
const VOID *target,                /*  target string                       */
const VOID *test);                 /*  string to compare to                */

Compares 2 strings and returns which one is greater.

target

Pointer to first string to compare.

test

Pointer to second string to compare.

Returns

LEFTHIGH if target > test,

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:

typedef INT                        /* Returns comparison identifier        */\
(*smbCompFunc)(                    /*  Key comparison routine              */\
const VOID *target,                /*  Pointer to target object            */\
const VOID *test);                 /*  Pointer to object to compare to     */

target

Pointer to the first key to compare.

test

Pointer to the second key to compare.

Returns

LEFTHIGH if target > test,

RIGHTHIGH if target < test,

EQUAL if target = test.

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”.

Applies to: v10

Not in v10. The Client/Server (Visual Basic client app) mode was removed in v10 (MBBS10.txt section 2; the v10 history has the commit "Initial port of GALTELE including removal of AHTML and CS related code"). Read this passage as WG1-3.x history only. The sample still shows the SMB API; ignore the C/S-user part.

#include “gcomm.h”
#include “smbapi.h”
SMBHANDLE UserSMB;
SMBKEYHANDLE UserKey[]={
        {0,     smbCompareString},
        {0,     NULL},
};

Applies to: WG3.x

Header check: SMBKEYHANDLE is not defined; the type is SMBKEYTABLE (struct smbKeyTable, pSMBKEYTABLE, SMBAPI.H:62-65), as this chapter's own text says ("your SMBKEYTABLE") and as smbOpen() expects.

static VOID UsersDown(VOID);
static VOID UserDisconnect(VOID);
static VOID UserConnect(VOID);
static INT GlobalUsers(VOID);
VOID EXPORT
init__userlist(VOID)
{
        smbInit();
        UserSMB=smbOpen(UIDSIZ,UserKey,10);
        hook_shutdown(UsersDown);
        hook_connect(UserConnect);
        hook_disconnect(UserDisconnect);
        globalcmd(GlobalUsers);
}
static VOID
UserConnect(VOID)
{
        smbInsert(UserSMB,usaptr->userid);
}
static VOID
UserDisconnect(VOID)
{
        if (smbQueryEqual(UserSMB,usaptr->userid,0)) {
                smbDelete(UserSMB);
        }
}
static INT
GlobalUsers(VOID)
{
        CHAR *UserData;
        if (margc == 1 && sameas(margv[0],”/USERS”)) {
                prf(“C/S Users Online:\n”);
                if ((UserData=smbGetLow(UserSMB,0)) != NULL) {
                        do {
                                prf(“%s\n”,UserData);
                        } while ((UserData=smbGetNext(UserSMB)) != NULL);
                }
                return(1);
        }
        return(0);
}
static VOID
UsersDown(VOID)
{
        smbClose(UserSMB);
}