Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

Code Block
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.

...

A pointer to a compare routine. You may use any of the default compare routines, or create your own.

smbClose()

Code Block
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.

...

Handle of the SMB returned from smbOpen.

smbCurrentData()

Code Block
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.

...

Pointer to the current SMB record.

smbCurrentNumber()

Code Block
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.

...

A number associated with the current record.

smbDelete()

Code Block
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.

...

Handle of the SMB to delete from.

smbGetBynum()

Code Block
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().

...

A pointer to the SMB record or NULL if not found.

smbGetEqual()

Code Block
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.

...

A pointer to the data matching KeyInfo, or NULL if the key was not found.

smbGetGreater() and smbGetLess()

Code Block
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            */
Code Block
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.

...

A pointer to the data matching KeyInfo, or NULL if the key was not found.

smbGetHigh() and smbGetLow()

Code Block
smbGetHigh(                        /*  Get highest record in the tree      */
SMBHANDLE smb,                     /*  Handle to smb information           */
UINT Key);                         /*  Key to get highest on               */
Code Block
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.

...

A pointer to the highest or lowest record.

smbGetPrevious() and smbGetNext()

Code Block
VOID *                             /* Pointer to data or NULL              */
smbGetPrevious(                    /*  Get previous from current record    */
SMBHANDLE smb);                    /*  Handle to current smb pointer       */
Code Block
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.

...

A pointer to the SMB record, or NULL if there are no more records.

smbInit()

Code Block
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()

Code Block
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.

...

A pointer to the newly created SMB record.

smbOpen()

Code Block
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.

...

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:

Code Block
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.

...

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:

Code Block
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.

...

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.

Code Block
#include “gcomm.h”
#include “smbapi.h”
Code Block
SMBHANDLE UserSMB;
Code Block
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.

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

...

Previous: Major BBS v10: 24 Year 2000 Issues  |  Contents  |  Next: Major BBS v10: 26 Audit Trail API