Databases
Database Functions: xxxbtv()
Btrieve, by Btrieve Technologies, Inc., provides a powerful collection of database-management primitives. Worldgroup The Major BBS has a plethora of routines that provide a smooth C language interface.
Btrieve File Identifiers
The functions opnbtv(), setbtv(), and clsbtv() are the only functions that explicitly deal with a single database. All other database functions implicitly deal with a single database using the file identified by the most recent setbtv(). A Btrieve file identifier is a pointer to a structure defined in BTVSTF.H:
Applies to: WG3.x
Header check (WG3.2): the whole
xxxbtv()family was renameddfa*()(DFAAPI.H);struct btvblkisstruct dfablk, andBTVFILEisDFAFILE(#define DFAFILE struct dfablk,DFAAPI.H:167; the old spelling survives only asLAYER.H:3). Btrieve file pointer variables areDFAFILE *.Old names still compile only through
LAYER.H.LAYER.H("V3 Layer to simplify things") keeps 17 of the old function names, plusopnbtvand the typesBTVFILE/MSGFILE, as macros; no 3.2 header includes it, so a module must#include "LAYER.H"itself (or carry a local shim, asSRC/apps/BMEDIT/BTV.H:103does). Every other old name (omdbtv,qrybtv,getbtvl,obtbtvl,geqbtv,ggebtv,crtbtv, ... ) is undeclared in 3.2 and must be renamed by hand or byGALPORT(chapter 28).
opnbtv()gained a parameter.DFAFILE *dfaOpen(const CHAR *filnam, USHORT maxlen, const CHAR *owner)(DFAAPI.H:217-220) takes the Btrieve owner name as a third argument (NULLif none):LAYER.H:6is#define opnbtv(n,s) dfaOpen(n,s,NULL). A hand renameopnbtv(n,s)todfaOpen(n,s)is a "too few arguments" error; writedfaOpen(n,s,NULL).GALPORThas noopnbtventry and leaves the call alone. The separateopnbtvl(name,maxlen,owner)of this chapter is simplydfaOpen().dfaCreate(const VOID *filnam, VOID *databuf, SHORT keyno, USHORT lendbuf)(DFAAPI.H:348) takes its last two arguments in the opposite order fromcrtbtv(filnam,databuf,lendbuf,keyno); both are integers, so a blind rename compiles and creates the file with the key number as the record length. The record-length, key-number and lock arguments of thedfa*()calls are 16-bit (USHORT/SHORT).Names used in this chapter (
getbtvandobtbtv, the lock-less forms, have no 3.2 name of their own: thedfaGetEQ... macros show the replacement,dfaGetLock/dfaAcqLockwith lock type 0,DFAAPI.H:183-204):
old name WG3.2 name still defined? BTVFILEDFAFILEyes ( LAYER.H)aabbtvdfaAcqAbsyes ( LAYER.H)absbtvdfaAbsyes ( LAYER.H)acqbtvdfaAcqEQyes ( LAYER.H)agebtvdfaAcqGEno agtbtvdfaAcqGTno ahibtvdfaAcqHIno alebtvdfaAcqLEno alobtvdfaAcqLOno altbtvdfaAcqLTno aqnbtvdfaAcqNXno aqpbtvdfaAcqPRno clsbtvdfaCloseyes ( LAYER.H)delbtvdfaDeleteyes ( LAYER.H)dinsbtvdfaInsertDupno dupdbtvdfaUpdateDupno gabbtvdfaGetAbsno gcrbtvdfaAbsRecyes ( LAYER.H)geqbtvdfaGetEQno getbtvdfaGetLock(recptr,key,keynum,getopt,0)no ggebtvdfaGetGEno ggtbtvdfaGetGTno ghibtvdfaGetHIno glebtvdfaGetLEno globtvdfaGetLOno gltbtvdfaGetLTno gnxbtvdfaGetNXno gprbtvdfaGetPRno insbtvdfaInsertyes ( LAYER.H)invbtvdfaInsertVyes ( LAYER.H)llnbtvdfaLastLenno obtbtvdfaAcqLock(recptr,key,keynum,obtopt,0)no omdbtvdfaModeno opnbtvdfaOpen(name,maxlen,owner)yes ( LAYER.H)opnbtvldfaOpen(name,maxlen,owner)no qeqbtvdfaQueryEQyes ( LAYER.H)qgebtvdfaQueryGEno qgtbtvdfaQueryGTno qhibtvdfaQueryHIyes ( LAYER.H)qlebtvdfaQueryLEno qlobtvdfaQueryLOyes ( LAYER.H)qltbtvdfaQueryLTno qnxbtvdfaQueryNXyes ( LAYER.H)qprbtvdfaQueryPRyes ( LAYER.H)qrybtvdfaQueryno rstbtvdfaRstBlkyes ( LAYER.H)setbtvdfaSetBlkyes ( LAYER.H)shibtvdfaStepHIno slobtvdfaStepLOno snxbtvdfaStepNXno sprbtvdfaStepPRno updbtvdfaUpdateyes ( LAYER.H)upvbtvdfaUpdateVyes ( LAYER.H)
| Code Block |
|---|
struct btvblk { /* btrieve file data block def */ long posblk[128/4]; /* position block */ char *filnam; /* filename */ int reclen; /* record length */ char *key; /* key for searching, etc. */ char *data; /* actual record contents */ int lastkn; /* last key number used */ int keylns[SEGMAX]; /* lengths of all possible keys */ }; |
| Code Block |
|---|
#define BTVFILE struct btvblk /* shorthand for btrieve file id */ |
Applies to: v10
v10:
#define DFAFILE struct dfablk(DFAAPI.H:167), unchanged from WG3.2. TheBTVFILEspelling existed only in the compatibility headers2030.H/LAYER.H, which are not in the shared v10inc/: the "includeLAYER.H" advice in this chapter's WG3.x notes only works if you copy a localLAYER.Hinto your project (the ported modules do, for examplesrc/isv/mjwmut/LAYER.H); otherwise rename everyxxxbtv()to itsdfa*()equivalent. Record structs: mind packing (chapter 29, section 29.3).
opnbtv() is the source of all Btrieve file identifiers. setbtv() is used to set the Btrieve file for all subsequent database functions.
...
Btrieve allows you to create Btrieve files with an owner for security over who can open the file. You can only open such a file if you specify the file’s owner name. The opnbtvl() function can be used instead of opnbtv() to specify an owner name when opening a Btrieve data file:
| Code Block |
|---|
agtbb=opnbtvl("ZZZAGENT.DAT",maxlen,owner); |
The owner parameter is a nul-terminated, case sensitive string between 0 and 8 characters in length. The return value and other parameters are the same as for the standard opnbtv() function.
...
These routines search the database in the physical order in which records are stored. The sequence defined by the database keys usually doesn’t matter in this case, and neither does chronology — records could appear in any order. The advantage of the snxbtv()/sprbtv() routines over the qnxbtv()/qprbtv() routines (which are keyed-sequential — see below) is their speed: physical access can be about eight times as fast as keyed-sequential.
Database Update Routines
updbtv(recptr); update current record
...
int length; number of bytes for new record contents
Database Insert Routines
insbtv(recptr); insert new fixed-length record
...
int length; number of bytes for new record
Deleting a Database Record
delbtv(); delete current record
This function must be called immediately following a get-record call of some kind (queries are not enough, but gcrbtv() will suffice after a query).
Variable Record Length
reclen=llnbtv(); find the record length of the most recently read record
This function is handy after reading a variable length record to find out how many bytes are actually in the record. In that case, this is the same value that was passed to invbtv() or upvbtv() as the length parameter when the record was put into the database.
Closing a Database File
clsbtv(bbptr); close a Btrieve file when finished
BTVFILE *bbptr; file identifier from opnbtv()
Database Query Routines
The following database utilities are implemented as macros (defined in BTVSTF.H). They actually generate calls to functions qrybtv(), getbtv(), and others.
...
The above query routines set the key buffer reserved for the database. For example, the following code might be used to find out if there are any users in the Registry database whose User-ID starts with the letter Q (see REGISTRY.C for the variables and structure of this database — the regrec structure).
| Code Block |
|---|
setbtv(regbb); if (qgebtv("Q",0) && regbb- |
>key[0] == 'Q') { prf("Warning! Someone named \ |
%s\ is in the registry!",regbb- |
>key); } |
Applies to: WG3.x
Header check:
REGISTRY.H(regbb,struct regrec,sumlin; WG2REGISTRY.H:28,30,32) is not inWGDEV/INC.
Database Get Routines
geqbtv(recp,key,keynum); get record equal to specified key
...
In all of these routines you may specify where to put the data, using the recp parameter. You may also pass NULL for this parameter, and the data record will go into the standard data buffer for the database. Expanding upon the query example, gcrbtv() can be used to read in a database record that passed the query test:
| Code Block |
|---|
setbtv(regbb); if (qgebtv("Q",0) && regbb- |
>key[0] == 'Q') { gcrbtv(NULL,0); prf("Warning! Someone named \ |
%s\ is in the registry!",regbb- |
>key); prf("\ |
nAnd he has this to say about himself:\n\ |
%s\\n", ((struct regrec *)regbb- |
>data)- |
>sumlin); } |
This technique of casting the data buffer to a special purpose structure is usually required to use this buffer, because the data field of the btvblk structure (see page 280) is just a general purpose character pointer — you must overlay the structure of the actual database record.
Database Acquire Routines
is=acqbtv(recptr,key,keynum);
“acquire” record with specified key
...
These routines combine a query and a get into the useful combination where you want to see if a record is in a database, and if it is, to read it. Using these routines we could code:
| Code Block |
|---|
setbtv(regbb); if (agebtv(NULL,"Q",0) && regbb- |
>data[0] == 'Q') { prf("Warning! Someone named \ |
%s\ is in the registry!",regbb- |
>key); prf("\ |
nAnd he has this to say about himself:\n\ |
%s\\n", ((struct regrec *)regbb- |
>data)- |
>sumlin); } |
Here are two special-purpose acquire routines:
...
Use these routines only for databases with a single non-unique key that’s a nul-terminated string. Each of these routines returns false if the two records (the current one and the next/previous one) compare unequal (case-sensitive) when treated as strings.
Creating your own Databases
If you purchase the Btrieve development kit from Btrieve Technologies, you can use the following command to create new databases:
...
The .BCR file is an editable text file that you will define that specifies the format of your database. See the Btrieve manual. Tip: use the zstring format for nul-terminated string fields. The .VIR is an empty “virgin” form of the database that you’ll always keep online. During the installation process, an empty .VIR file is copied to a .DAT file if no .DAT file exists.
System Variables Database
Worldgroup The Major BBS maintains several variables on disk in BBSVBL.DAT. These are available at run-time, are changed as necessary, and are automatically saved back to disk every 300 seconds (default value of SVRATE). The following code from MAJORBBS.H shows the fields of the system variables in sv, sv2 and sv3:
| Code Block |
|---|
extern struct sysvbl { /* system-variable btrieve record layout */ char key[4]; /* 4-character dummy key of "key" */ char dspopt[6]; /* display options by position number */ long calls[8]; /* number of calls this month/baud rt */ char lonmsg[MTXSIZ]; /* log-on message in effect */ long dwnlds; /* total downloads to date */ long uplds; /* total uploads to date */ long msgtot; /* msg (E-mail/Forums) total to date */ unsigned emlopn; /* E-Mail open at the moment */ unsigned sigopn; /* Forum messages open at the moment */ int hisign; /* highest Forum number used to date */ char monmal; /* Aux. CRT display selector */ char savmin; /* Minutes to save screen */ long oldsec[8][24]; /* old sec/grp/hr (now in sv3.secghr) */ char spare[1300-1230]; /* spare space for graceful upgrades */ } sv; |
| Code Block |
|---|
extern struct sysvb2 { /* second system variable btrieve layout */ char ky2[4]; /* 4-character dummy key of "ky2" */ unsigned matrix[NCOMTY][NAGEBK]; /* matrix of accts (computer/age) */ long oldcrd[8][24]; /* old crd/grp/hr (now in sv3.crdghr) */ int nliniu[48]; /* number of lines in use per hlf/hr */ int lstzer; /* date of last zeroing of stats */ long x25kps; /* X.25 kilopackets sent or received */ unsigned x25ps; /* fractional X.25 kilopackets */ long x25mbs; /* X.25 megabytes sent or received */ long x25bs; /* fractional X.25 megabytes */ unsigned numact; /* total number of user accounts */ unsigned numfem; /* number of female users */ unsigned numcor; /* number of corporate users */ unsigned numans; /* number of ANSI users */ unsigned long paidpst; /* credits paid-for so far */ unsigned long freepst; /* credits given away free so far */ long totcalls; /* total calls-to-date */ int lastmcu; /* date of last midnight cleanup */ char spare[1300-986]; /* spare space for graceful upgrades */ } sv2; |
| Code Block |
|---|
extern struct sysvb3 { /* third system variable btrieve layout */ char ky3[4]; /* 4-character dummy key of "ky3" */ long secghr[NGROUPS-1][24]; /*seconds used (channel grp/hr) */ long crdghr[NGROUPS-1][24]; /*credits consumed channel grp/hr) */ } sv3; |
Applies to: WG3.x
Header check:
NGROUPSwas removed in WG3.2; the constant isNUMGRPS(#define NUMGRPS 17,MAJORBBS.H:62; WG2MAJORBBS.H:45), andstruct sysvb3is declaredLONG secghr[NUMGRPS-1][24]; LONG crdghr[NUMGRPS-1][24];(MAJORBBS.H:407-408). Same value (17).
User Account Database
The following code from USRACC.H shows the fields of the user accounting database, BBSUSR.DAT. This same structure is used for the dynamically allocated usracc[] array, which stores the information in memory for users who are online. Note: that array may be bigger than 64K. Use uacoff() to get information on online users — see page 114.
| Code Block |
|---|
struct usracc { char userid[UIDSIZ]; /* user-id */ char psword[PSWSIZ]; /* password */ char usrnam[NADSIZ]; /* user name */ char usrad1[NADSIZ]; /* address line 1 (company) */ char usrad2[NADSIZ]; /* address line 2 */ char usrad3[NADSIZ]; /* address line 3 */ char usrad4[NADSIZ]; /* address line 4 */ char usrpho[PHOSIZ]; /* phone number */ char systyp; /* system type code */ char usrprf; /* user preference flags */ char ansifl; /* ANSI flags */ char scnwid; /* screen width in columns */ char scnbrk; /* screen length for page breaks */ char scnfse; /* screen length for FSE stuff */ char age; /* user's age */ char sex; /* user's sex ('M' or 'F') */ unsigned int credat; /* account creation date */ unsigned int usedat; /* date of last use of account */ int csicnt; /* classified-ad counts used so far */ int flags; /* various saved bit flags */ int access[AXSSIZ]; /* array of remote Sysop access bits */ long emllim; /* e-mail limit reached so far (new/old bdy) */ char prmcls[KEYSIZ]; /* class to return user to if necessary */ char curcls[KEYSIZ]; /* current class of this user */ long timtdy; /* time user has been online today (in secs) */ unsigned int daystt; /* days left in this class (if applicable) */ unsigned int fgvdys; /* days since debt was last "forgiven" */ long creds; /* credits available or debt (if negative) */ long totcreds; /* total credits ever posted (paid & free) */ long totpaid; /* total credits ever posted (paid only) */ char birthd[DATSIZ]; /* this user's birthday date */ char spare[USRACCSPARE]; /* spare space, for graceful upgrades */ }; /* ansifl bit definitions */ #define ANSON 1 /* ANSI on=1; off=0 */ #define ANSMAN 2 /* ANSI manual override (0=auto sensing) */ /* flags bit definitions */ #define HASMST 1 /* user has the "MASTER" key */ #define UNDAXS 2 /* this account cannot be deleted */ #define SUSPEN 4 /* this account is "suspended" */ #define DELTAG 8 /* this account is tagged for deletion */ #define GOINVS 16 /* this account is "invisible" upon logon */ /* usrprf bit definitions */ #define PRFLIN 1 /* always use line editor? yes=1 */ |
Applies to: WG3.x
Header check: in WG3.2
struct usraccis declared inUStructs.h(notMAJORBBS.H), its 16-bit members areshort/ushortand strings areCHAR(UStructs.h:20-);birthd[DATSIZ]is atUStructs.h:51.DATSIZ(9) is now defined inDNTAPI.H:137(andUStructs.h:16); see chapter 24 for the newYYYYMMDDbirth-date format,fixBirthdate()andokbday().
User Class Database
This database records information on the user classes. Classes are defined by the Sysop using the Remote Operator Menu ACCOUNT submenu, CLASS command.
| Code Block |
|---|
extern struct acclass { /* accounting class structure */ char clname[KEYSIZ]; /* class name */ char nxtcls[4][KEYSIZ]; /* class to return to when expires */ int limcal; /* limit per call (-1=no limit) */ int limday; /* limit per day (-1=no limit) */ int dftday; /* default days before expiring (-1=never)*/ long dbtlmt; /* debt limit (0=none) */ int fgvday; /* wait how many days before "forgiving" */ int idlday; /* inactive days before delete (-1=never) */ int flags; /* general bit flags */ long seconds; /* seconds used so far this month */ unsigned users; /* total number of users in this class */ char msgs[2][XMSGSZ]; /* exiting class messages */ char spare[2032-2022]; /* spare space - decrease when needed */ }; /* indexes for nxtcls[] when a user... */ #define DOUTTIM 0 /* is out of time for the day */ #define DLOAFER 1 /* hasn't logged in for x number of days */ #define DEXPIRE 2 /* has been around x number of days */ #define DCREDIT 3 /* has/doesn't have credits */ /* struct acclass bit flag definitions */ #define KCKOFF 1 /* out of time: knock the user offline */ #define CLSCHG 2 /* out of time: temporarily change class */ #define NOCRED 4 /* expire when: credits < 1 */ #define DBTLMT 8 /* expire when: user reaches a debt limit */ #define HASCRD 16 /* expire when: credits > 0 */ #define DAYEXP 32 /* expire when: x number of days passes */ #define IDLEXP 64 /* expire when: no log on for x # of days */ #define MONDAY 128 /* forgive: every Monday */ #define FSTMTH 256 /* forgive: on the first of each month */ #define NUMDAY 512 /* forgive: every x number of days */ #define HITLMT 1024 /* forgive: when they hit their debt limit*/ #define REPDBT 2048 /* report debt when forgiven? */ #define CRDXMT 4096 /* this class exempt from credit charges? */ |
Using Spare Space in Galacticomm Databases
If you’re developing your own Add-on Option for Worldgroupthe Major BBS, you should make your own databases rather than add onto the spare spaces in Galacticomm databases. Otherwise you’ll run into conflicts with other developers trying to use the same space.
On the other hand, if you’re customizing your own WorldgroupMajor BBS, and you want to add fields to a database, there might be a way. Add your fields after the spare[] field.
When customizing the database on your own system, add fields at the end of the structure — between the spare[] field and the } — and decrease the spare size accordingly, so the size of the overall structure is unchanged.
In new versions of Worldgroupthe Major BBS, Galacticomm will try to add new fields before the spare[] field.
Be conservative and use as few bytes as possible. If you use a lot of bytes in a database, and Galacticomm eventually uses them too, you’re going to be in for some complex conversion activity to be able to update to a new release of Worldgroupthe Major BBS.
Generic User Database
This database, BBSGEN.DAT, may be used by any application to store information about users. To create your own records in BBSGEN.DAT, first define a structure. The first two fields should be User-ID and module name. Say you wanted to store a user’s score in a game:
| Code Block |
|---|
struct bggame { /* generic user data records for my game */ char userid[UIDSIZ]; /* User-ID */ char modnam[MNMSIZ]; /* Module Name ("My Game") */ int score; /* score */ }; |
To store a record for the current user, with a score of 50, you could code:
| Code Block |
|---|
struct bggame bgbuff; : : strcpy(bgbuff.userid,usaptr- |
>userid); strcpy(bgbuff.modnam,"My Game"); bgbuff.score=50; setbtv(genbb); invbtv(&bgbuff,sizeof(bgbuff)); |
Notice how the module name was not obtained from the descrp field of your module structure (see page 44 about gmdnam()). That field is a copy of the module name in your .MDF file. If the Sysop innocently edits the .MDF file to change the module name, you probably don’t want him to suddenly be missing all of your records in BBSGEN.DAT. That’s why it might be a good idea to hard-code your module name in your records of BBSGEN.DAT.
...
To read the current user’s score, you could code:
| Code Block |
|---|
struct bggame bgbuff; : strcpy(bgbuff.userid,usaptr- |
>userid); strcpy(bgbuff.modnam,"My Game"); setbtv(genbb); if (acqbtv(&bgbuff,&bgbuff,0)) { prf("Score: %d",bgbuff.score); } else { prf("No score recorded"); } |
This sure beats making a whole separate .DAT file for one measly integer.
...
Previous: Major BBS v10: 08 Operator Services | Contents | Next: Major BBS v10: 10 Offline Utilities