You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

Databases

Database Functions: xxxbtv()

Btrieve, by Btrieve Technologies, Inc., provides a powerful collection of database-management primitives. 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 name WG3.2 name still defined?
BTVFILE DFAFILE yes (LAYER.H)
aabbtv dfaAcqAbs yes (LAYER.H)
absbtv dfaAbs yes (LAYER.H)
acqbtv dfaAcqEQ yes (LAYER.H)
agebtv dfaAcqGE no
agtbtv dfaAcqGT no
ahibtv dfaAcqHI no
alebtv dfaAcqLE no
alobtv dfaAcqLO no
altbtv dfaAcqLT no
aqnbtv dfaAcqNX no
aqpbtv dfaAcqPR no
clsbtv dfaClose yes (LAYER.H)
delbtv dfaDelete yes (LAYER.H)
dinsbtv dfaInsertDup no
dupdbtv dfaUpdateDup no
gabbtv dfaGetAbs no
gcrbtv dfaAbsRec yes (LAYER.H)
geqbtv dfaGetEQ no
getbtv dfaGetLock(recptr,key,keynum,getopt,0) no
ggebtv dfaGetGE no
ggtbtv dfaGetGT no
ghibtv dfaGetHI no
glebtv dfaGetLE no
globtv dfaGetLO no
gltbtv dfaGetLT no
gnxbtv dfaGetNX no
gprbtv dfaGetPR no
insbtv dfaInsert yes (LAYER.H)
invbtv dfaInsertV yes (LAYER.H)
llnbtv dfaLastLen no
obtbtv dfaAcqLock(recptr,key,keynum,obtopt,0) no
omdbtv dfaMode no
opnbtv dfaOpen(name,maxlen,owner) yes (LAYER.H)
opnbtvl dfaOpen(name,maxlen,owner) no
qeqbtv dfaQueryEQ yes (LAYER.H)
qgebtv dfaQueryGE no
qgtbtv dfaQueryGT no
qhibtv dfaQueryHI yes (LAYER.H)
qlebtv dfaQueryLE no
qlobtv dfaQueryLO yes (LAYER.H)
qltbtv dfaQueryLT no
qnxbtv dfaQueryNX yes (LAYER.H)
qprbtv dfaQueryPR yes (LAYER.H)
qrybtv dfaQuery no
rstbtv dfaRstBlk yes (LAYER.H)
setbtv dfaSetBlk yes (LAYER.H)
shibtv dfaStepHI no
slobtv dfaStepLO no
snxbtv dfaStepNX no
sprbtv dfaStepPR no
updbtv dfaUpdate yes (LAYER.H)
upvbtv dfaUpdateV yes (LAYER.H)
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         */
};
#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.

Warning: You must be careful not to forget to use setbtv(). If you do, your program might seem to work fine when you test it with a single user, but fail insidiously when you try it with multiple users.

Many of the database functions have an explicit recptr parameter for specifying where to get or put a record for writing or reading. If you use NULL for this value then you may use a default buffer specified in the btvblk data field.

There are three flavors of database record read procedures. All specify a record according to a key or according to the order by a key.

get Read the record. If missing, bomb with catastro() message

query Find out if the record is in the database

acquire Find out if the record is in the database, and if so, read it

Here are synopses of the routines in PLBTVSTF.C:

omdbtv(mode); set mode for next opnbtv() call

int mode; see codes below

This routine sets the Btrieve file mode for subsequent database files opened by opnbtv(). The following mutually exclusive values for the mode parameter are defined in BTVSTF.H:

PRIMBV default, pre-image (data integrity) mode

ACCLBV accelerated (faster write) mode

RONLBV read-only mode

VERFBV write-with-verify mode

EXCLBV exclusive (non-sharing) mode

bbptr=opnbtv(filnam,reclen);
open a Btrieve file for I/O

BTVFILE *bbptr; file identifier

char *filnam; filespec

int reclen; record length in bytes

If the file is not found, the catastro() error message BTRIEVE OPEN ERROR 12 is generated automatically by opnbtv() — you never have to check the return value for error conditions.

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:

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.

setbtv(bbptr); set BTVFILE ptr for subsequent ops

BTVFILE *bbptr; file to be used hereafter

This important utility specifies the Btrieve database for all other xxxbtv utility functions (except opnbtv() and clsbtv()). See about Btrieve File Identifiers, above.

rstbtv(); restore the current BTVFILE to what it was before the corresponding recent setbtv()

Calls to setbtv()/rstbtv() use a stack and can be nested up to 10 levels deep.

is=qrybtv(key,keynum,qryopt);
query whether a record exists

int is; 1 if record exists, else 0

char *key; key to be used for lookup

int keynum; key position number to use

int qryopt; search option (used via macro)

getbtv(recptr,key,keynum,getopt);
get a record (bomb if not there)

char *recptr; destination record buffer ptr (NULL to use bbptr->data)

char *key; key to be used for lookup

int keynum; key position number to use

int getopt; search option (used via macro)

is=obtbtv(recptr,key,keynum,obtopt);
acquire a record (if you can)

int is; 1 if record exists, else 0

char *recptr; destination record buffer ptr (NULL to use bbptr->data)

char *key; key to be used for lookup

int keynum; key position number to use

int obtopt; search option (used via macro)

The above three routines are almost exclusively called out in the source code only by using macros that are defined in BTVSTF.H. For example, all the q??btv() “functions” are actually macros that generate special-purpose calls to qrybtv().

abspos=absbtv(); find current absolute position

long abspos; absolute (direct) file position

gabbtv(recptr,abspos,keynum);
get a record by absolute position

char *recptr; destination record buffer ptr (NULL to use bbptr->data)

long abspos; “absolute” (direct) file position

int keynum; key number to establish there

is=aabbtv(recptr,abspos,keynum);
acquire a record by absolute position

int is; 1 if record could be read, else 0

char *recptr; destination record buffer ptr (NULL to use bbptr->data)

long abspos; absolute (direct) file position

int keynum; key number to establish there

The return value of absbtv() may be used to identify the physical position of a record in a database. The record may be accessed using gabbtv() or aabbtv() with that position. This type of access is much faster than any of the keyed access methods. We have determined that this absolute position value is never zero for a legitimate record. Therefore, we sometimes use 0L as a special value to represent a pointer to no record at all.

is=slobtv(recptr); Read the physically first record in the database

int is; 1=there was one 0=database empty

is=snxbtv(recptr); Read the physically next record in the database

int is; 1=there was one 0=already read last

is=sprbtv(recptr); Read the physically previous record in the database

int is; 1=there was one 0=already read first

is=shibtv(recptr); Read the physically last record in the database

int is; 1=there was one 0=database empty

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

char *recptr; replacement record buffer ptr (NULL to use bbptr->data)

ok=dupdbtv(recptr); (more tolerant) update current record

int ok; 1=updated 0=duplicate collision

char *recptr; replacement record buffer ptr

These functions must be called immediately following a get-record call of some kind (queries are not enough, but gcrbtv() will suffice after a query). updbtv() and dupdbtv() are the same except that when the new record contents produce an illegally duplicate key, updbtv() bombs with a catastro() error, while dupdbtv() simply returns a 0. These routines cannot be called on a database with variable length records. Instead, use upvbtv():

upvbtv(recptr,length); update variable length record

char *recptr; replacement record buffer ptr NULL to use bbptr->data)

int length; number of bytes for new record contents

Database Insert Routines

insbtv(recptr); insert new fixed-length record

char *recptr; new record buffer ptr (NULL to use bbptr->data)

ok=dinsbtv(recptr); (more tolerant) insert new record

int ok; 1=inserted 0=duplicate collision

char *recptr; new record buffer ptr (NULL to use bbptr->data)

insbtv() will automatically generate the fatal error BTRIEVE INSERT ERROR 5 if you try to insert a record with the same key as another record in a database (if that key does not allow duplicates). dinsbtv() will simply return a 0 in that case. Otherwise, the routines have identical effects.

invbtv(recptr,length); insert variable length record

char *recptr; new record buffer ptr (NULL to use bbptr->data)

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.

is=qeqbtv(key,keynum); query for “equal to” specified key

int is; 1 if record exists, else 0

char *key; key specification

int keynum; key number involved

is=qnxbtv(); query for next record in sequence

int is; 1 if record exists, else 0

is=qprbtv(); query for previous record

int is; 1 if record exists, else 0

exists=qgtbtv(key,keynum);
query for “greater than” key

int exists; 1 if record exists, else 0

char *key; key specification

int keynum; key number involved

exists=qgebtv(key,keynum);
query for “greater/eq (>=)” key

int exists; 1 if record exists, else 0

char *key; key specification

int keynum; key number involved

exists=qltbtv(key,keynum);
query for “less than” key

int exists; 1 if record exists, else 0

char *key; key specification

int keynum; key number involved

exists=qlebtv(key,keynum);
query for “less/equal (<=)” key

int exists; 1 if record exists, else 0

char *key; key specification

int keynum; key number involved

exists=qlobtv(keynum); query for lowest record present

int exists; 1 if record exists, else 0

int keynum; key number involved

exists=qhibtv(keynum); query for highest record present

int exists; 1 if record exists, else 0

int keynum; key number involved

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

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; WG2 REGISTRY.H:28,30,32) is not in WGDEV/INC.

Database Get Routines

geqbtv(recp,key,keynum); get record equal to specified key

char *recp; destination record buffer pointer

char *key; key specification

int keynum; key number involved

gnxbtv(recp); get next record in sequence

char *recp; destination record buffer pointer

gprbtv(recp); get previous record in sequence

char *recp; destination record buffer pointer

ggtbtv(recp,key,keynum); get first record > specified key

char *recp; destination record buffer pointer

char *key; key specification

int keynum; key number involved

ggebtv(recp,key,keynum); get first record >= specified key

char *recp; destination record buffer pointer

char *key; key specification

int keynum; key number involved

gltbtv(recp,key,keynum); get highest record < specified key

char *recp; destination record buffer pointer

char *key; key specification

int keynum; key number involved

glebtv(recp,key,keynum); get highest record <= specified key

char *recp; destination record buffer pointer

char *key; key specification

int keynum; key number involved

globtv(recp,keynum); get lowest record present

char *recp; destination record buffer pointer

int keynum; key number involved

ghibtv(recp,keynum); get highest record present

char *recp; destination record buffer pointer

int keynum; key number involved

gcrbtv(recp,keynum); get (or re-get) “current” record

char *recp; destination record

buffer ptr int keynum; key number to establish

The above get routines read in a full record from a database. By contrast, the query routines simply tell you if the record is there, and read in the key fields.

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:

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

int is; 1 if record exists, else 0

char *recptr; destination record buffer pointer

char *key; key value to search for

int keynum; key number

is=agtbtv(recptr,key,keynum);
acquire first record > key

int is; 1 record exists, else 0

char *recptr; destination record buffer pointer

char *key; key specification

int keynum; key number involved

is=agebtv(recptr,key,keynum);
acquire first record >= key

int is; 1 if record exists, else 0

char *recptr; destination record buffer pointer

char *key; key specification

int keynum; key number involved

is=altbtv(recptr,key,keynum);
acquire highest record < key

int is; 1 if record exists, else 0

char *key; key specification

int keynum; key number involved

is=alebtv(recptr,key,keynum);
acquire highest record <= key

char *recptr; destination record buffer pointer

char *key; key specification

int keynum; key number involved

is=alobtv(recptr,keynum); acquire lowest record in database

int is; 1 if record exists, else 0

char *recptr; destination record buffer pointer

int keynum; key number involved

is=ahibtv(recptr,keynum); acquire highest record in database

int is; 1 record exists, else 0

char *recptr; destination record buffer pointer

int keynum; key number involved

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:

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:

is=aqnbtv(recptr); acquire next record in sequence

int is; 1 if another record exists, else 0

char *recptr; destination record buffer pointer

is=aqpbtv(recptr); acquire previous record in sequence

int is; 1 if previous record exists, else 0

char *recptr; destination record buffer pointer

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:

BUTIL -CREATE <filename>.VIR <filename>.BCR

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

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:

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

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.

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 the 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 the Major 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 the 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 the 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:

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:

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.

The global variable genbb is declared in MAJORBBS.H.

To read the current user’s score, you could code:

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.

  • No labels