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:

...

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

...

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

...