Versions Compared

Key

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

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 renamed dfa*() (DFAAPI.H); struct btvblk is struct dfablk, and BTVFILE is DFAFILE (#define DFAFILE struct dfablk, DFAAPI.H:167; the old spelling survives only as LAYER.H:3). Btrieve file pointer variables are DFAFILE *.

Old names still compile only through LAYER.H. LAYER.H ("V3 Layer to simplify things") keeps 17 of the old function names, plus opnbtv and the types BTVFILE/MSGFILE, as macros; no 3.2 header includes it, so a module must #include "LAYER.H" itself (or carry a local shim, as SRC/apps/BMEDIT/BTV.H:103 does). Every other old name (omdbtv, qrybtv, getbtvl, obtbtvl, geqbtv, ggebtv, crtbtv, ... ) is undeclared in 3.2 and must be renamed by hand or by GALPORT (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 (NULL if none): LAYER.H:6 is #define opnbtv(n,s) dfaOpen(n,s,NULL). A hand rename opnbtv(n,s) to dfaOpen(n,s) is a "too few arguments" error; write dfaOpen(n,s,NULL). GALPORT has no opnbtv entry and leaves the call alone. The separate opnbtvl(name,maxlen,owner) of this chapter is simply dfaOpen(). dfaCreate(const VOID *filnam, VOID *databuf, SHORT keyno, USHORT lendbuf) (DFAAPI.H:348) takes its last two arguments in the opposite order from crtbtv(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 the dfa*() calls are 16-bit (USHORT/SHORT).

Names used in this chapter (getbtv and obtbtv, the lock-less forms, have no 3.2 name of their own: the dfaGetEQ... macros show the replacement, dfaGetLock/dfaAcqLock with lock type 0, DFAAPI.H:183-204):

old nameWG3.2 namestill 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. The BTVFILE spelling existed only in the compatibility headers 2030.H/LAYER.H, which are not in the shared v10 inc/: the "include LAYER.H" advice in this chapter's WG3.x notes only works if you copy a local LAYER.H into your project (the ported modules do, for example src/isv/mjwmut/LAYER.H); otherwise rename every xxxbtv() to its dfa*() 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
>key[0] == 'Q') {
prf("Warning! Someone named \
%s
%s\ is in the registry!",regbb-
>key
>key);
}

Applies to: WG3.x

Header check: REGISTRY.H (regbb, struct regrec, sumlin; WG2 REGISTRY.H:28,30,32) is not in WGDEV/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
>key[0] == 'Q') {
gcrbtv(NULL,0);
prf("Warning! Someone named \
%s
%s\ is in the registry!",regbb-
>key
>key);
prf("\
nAnd
nAnd he has this to say about himself:\n\
%s
%s\\n",
((struct regrec *)regbb-
>data
>data)-
>sumlin
>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
>data[0] == 'Q') {
prf("Warning! Someone named \
%s
%s\ is in the registry!",regbb-
>key
>key);
prf("\
nAnd
nAnd he has this to say about himself:\n\
%s
%s\\n",
((struct regrec *)regbb-
>data
>data)-
>sumlin
>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: NGROUPS was removed in WG3.2; the constant is NUMGRPS (#define NUMGRPS 17, MAJORBBS.H:62; WG2 MAJORBBS.H:45), and struct sysvb3 is declared LONG 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 usracc is declared in UStructs.h (not MAJORBBS.H), its 16-bit members are short/ushort and strings are CHAR (UStructs.h:20-); birthd[DATSIZ] is at UStructs.h:51. DATSIZ (9) is now defined in DNTAPI.H:137 (and UStructs.h:16); see chapter 24 for the new YYYYMMDD birth-date format, fixBirthdate() and okbday().

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