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:
...
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.
...
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
...
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
...
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:
...
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.
...
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.
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 Worldgroupthe 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 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:
...