...
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 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).
...
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.
...
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.
...
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.
...
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.
...
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.
...
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.
...
Applies to: v10
Not in v10. The Client/Server (Visual Basic client app) mode was removed in v10 (
MBBS10.txtsection 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:
SMBKEYHANDLEis not defined; the type isSMBKEYTABLE(struct smbKeyTable,pSMBKEYTABLE,SMBAPI.H:62-65), as this chapter's own text says ("your SMBKEYTABLE") and assmbOpen()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); } |
| Code Block |
|---|
static VOID UserDisconnect(VOID) { if (smbQueryEqual(UserSMB,usaptr- |
>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\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