Porting WG1/WG2 Source to Worldgroup 3.x
Applies to: v10
v10 changes to this chapter:
LAYER.Hand2030.H(the Btrieve-name compatibility macros this chapter relies on) are not in the shared v10inc/(a project-localLAYER.Hexists in the ported modules, e.g.src/isv/mjwmut/), so onlydfa*()names work unless you copy it; whether theGALPORTrenames still compile against v10 is unverified. TheEXPORT_*macros changed signature (chapter 29, section 29.5),BBSVERis nowBBSVERS(server.h:61), andffblk.ff_nameis 260 bytes (FIOAPI.H:44). Theconst CHAR *section of this chapter is the WG3.2 view; the v10 version, with the v10 prototypes, is chapter 29, section 29.4.
Applies to: WG3.x
Editor's note: this chapter is new. It is not part of the Developer's Addendum for Worldgroup 3.12 (
wg312dev); the addendum is silent on porting. It collects, for the WG3 layer, what happens when the WG1/WG2 source and the code printed in chapters 1-19 are built against the WG3.2 headers (/mnt/b/WG/WGDEV/INC). The sources are the kit utilityGALPORT.C(SRC/devutils/galport, identical to the copy in this repository), the headers themselves, and the header-level deltas inanalysis/deltas. Everyfile:linecitation is to the WG3.2 headers unless it says "WG2" (/mnt/b/WG/WGSERV2/SRC). The symbols in this chapter were checked against the headers (see CROSSCHECK.md).
GALPORT.EXE
GALPORT.EXE ships in \WGDEV\BIN; the addendum's list of new utilities (chapter 21) does not describe it. Its banner reads "developer's utility to help developers port their add-on source code from Worldgroup v2.x to Worldgroup v3.x" (C. Robert, 4/27/96, $Revision: 3 $). Usage:
| Code Block |
|---|
GALPORT filename |
The file is rewritten in place (through a work file GALPORT.OUT). The rules it follows, taken from the source:
- It matches whole words only, longest match first (so
unsigned long intwins overunsigned). The word must begin with a letter or digit; underscores are not word characters, soint_xis matched asintfollowed by_x. Check renamed identifiers that contain underscores. - It stops processing a line at the first
/*or//, and keeps no comment state, so the continuation lines of a multi-line comment are not ported if they look like code. - It does not recognise string literals: a
"int"inside quotes is rewritten. - A line longer than
BUFSIZ-1aborts the run (Line needing porting too long!). - Comment columns are realigned with spaces only; files that use real tabs will not line up.
Type and keyword renames
| old | new | note |
|---|---|---|
signed | INT | bare signed becomes INT. |
int | INT | DOS 16-bit int becomes INT (typedef int INT, GCTYPDEF.H:88): 32-bit under GCWINNT. Header structs were converted to short/ushort where width mattered (structs-wg2-to-wg32.json). |
unsigned short int | USHORT | USHORT. |
unsigned int | UINT | UINT = typedef unsigned int (GCTYPDEF.H:71): 32-bit on NT, 16-bit on DOS. |
signed int | INT | INT. |
unsigned | UINT | UINT; 32-bit on NT. WG3.2 headers use USHORT where WG2 had DOS unsigned and a 16-bit field was meant (e.g. getAdrForID returns USHORT, GME.H). |
short int | SHORT | SHORT. |
short | SHORT | SHORT typedef short (GCTYPDEF.H:95). |
unsigned short | USHORT | USHORT (GCTYPDEF.H:96). |
signed short | SHORT | SHORT. |
long int | LONG | LONG. |
long | LONG | LONG typedef long (GCTYPDEF.H:75). |
unsigned long int | ULONG | ULONG. |
unsigned long | ULONG | ULONG (GCTYPDEF.H:76). |
signed long | LONG | LONG. |
char | CHAR | CHAR typedef char (GCTYPDEF.H:94). |
unsigned char | CHAR | GALPORT bug: maps to CHAR, dropping unsigned. UCHAR exists (typedef unsigned char UCHAR, GCTYPDEF.H:98). Hand-fix to UCHAR. |
signed char | SCHAR | SCHAR (GCTYPDEF.H:99). |
double | DOUBLE | DOUBLE (GCTYPDEF.H:103). |
float | FLOAT | FLOAT (GCTYPDEF.H:104). |
BOOL | GBOOL | GBOOL is typedef short GBOOL (GCTYPDEF.H:105): 16-bit, not int-sized. 2030.H:92 also has #define GBOOL int in the old-compat branch; GCOMM.H:224 uses GBOOL in a prototype. Old BOOL is not defined in WGDEV/INC. |
void | VOID | VOID is a macro for void (GCTYPDEF.H:101, #ifndef VOID). |
STATIC | static | Table maps to lowercase keyword. STATIC was #define STATIC static in WG2 GCOMM.H:257 and is gone from every WG3.2 header (grep of WGDEV/INC: no hit; also listed under macros removed in analysis/deltas/SUMMARY.md). Un-ported STATIC fails to compile. |
BTVFILE | DFAFILE | struct dfablk (DFAAPI.H) replaces struct btvblk (btvblk is in the removed-structs list, structs-wg2-to-wg32.json). #define BTVFILE DFAFILE is LAYER.H:3. |
Two rows deserve care. unsigned char is mapped to CHAR, dropping unsigned; this is a defect in the tool. The UCHAR typedef exists (GCTYPDEF.H:98) and must be put back by hand wherever the sign matters. And int/unsigned become INT/UINT, which are 32 bits under Windows NT (GCTYPDEF.H:71,88): the 3.2 headers use short/ushort for any field that must keep its 16-bit on-disk width (structs-wg2-to-wg32.json), so code that wrote int fields to a data file must not be ported mechanically.
Btrieve function renames
The whole xxxbtv() family became dfa*() (DFAAPI.H). GALPORT renames the 67 names in this table. The last column says whether the old name is still defined by any WG3.2 header: only 17 are, all in LAYER.H (see "Compatibility layers" below).
...
| old | new | change |
|---|---|---|
setbtv(struct btvblk *) | dfaSetBlk(struct dfablk *) | the structure tag changed (btvblk is removed) |
clsbtv(struct btvblk *) | dfaClose(struct dfablk *) | same |
getbtvl(recptr,key,keynum,getopt,loktyp) | dfaGetLock(VOID*,const VOID*,SHORT,USHORT,USHORT) | integer widths narrowed to 16 bits; key is const |
gabbtvl(recptr,long abspos,int keynum,int loktyp) | dfaGetAbsLock(VOID*,LONG,SHORT,USHORT) | widths |
upvbtv, invbtv (recptr,int length) | dfaUpdateV, dfaInsertV (VOID*,USHORT) | width |
sttbtv(int len) | dfaStat(USHORT len) | width |
unlbtv(long abspos,int keynum) | dfaUnlock(LONG,SHORT) | widths |
opnmsg() returning FILE *; clsmsg(FILE *) | HMCVFILE opnmsg(CHAR *); clsmsg(HMCVFILE) | opaque handle (MCVAPI.H:54,66); not in GALPORT; LAYER.H:4 has #define MSGFILE HMCVFILE |
gabbtv, aabbtv | dfaGetAbs, dfaAcqAbs | three-argument macros over dfaGetAbsLock/dfaAcqAbsLock (DFAAPI.H:169-170); the l suffix names the explicit lock-type argument |
Compatibility layers
| layer | what it provides | used by |
|---|---|---|
LAYER.H ("V3 Layer to simplify things") | 18 function macros (opnbtv and 17 old Btrieve names) and the types BTVFILE -> DFAFILE, MSGFILE -> HMCVFILE (LAYER.H:3-23) | Opt-in. No header in WGDEV/INC includes it; the kit apps mjwcrb, MJWMAS, MJWMUT include it, and SRC/apps/BMEDIT/BTV.H:103 and SRC/apps/DIALCHAT/WG3CMP.H:62 carry their own opnbtv shim |
2030.H | upper-case aliases (OPNBTV, CLSBTV, CLSNAM -> usrcls, BTVFILE) under #ifdef IS30 | not included by anything in the kit |
GCOMM.H macros | getmsg -> getMsgBlk (GCOMM.H:195); sstatr(a) -> setatr(a) (GCOMM.H:140; WG2 had the reverse); movmem(s,d,n) -> galmovmem(s,d,n) (GCOMM.H:164-166) | built in |
COMPAT20.H (WG2) | #define dfaOpen(a,b,c) opnbtv(a,b) and friends, so WG2 code could already use the new names | WG2 only; not shipped with WG3.2 |
Note that analysis/deltas/SUMMARY.md ("Key finding for DOS porting") says that WG3.2 "keeps the old Btrieve names as compatibility macros". That is true only for the 18 names in LAYER.H, and only if a module includes LAYER.H: the other 50 old names (omdbtv, getbtvl, obtbtvl, geqbtv, agebtv, crtbtv, sttbtv, unlbtv, ...) have no definition in the 3.2 headers.
Renamed members, globals and constants
None of these are handled by GALPORT; the code in chapters 1-19 uses the old names.
| WG1/WG2 text | WG3.2 | header |
|---|---|---|
usrptr->class (struct user) | usrptr->usrcls; baud is now LONG; entstt and lingo were added, as were the 8-bit byecnt, col, ech, wid | MAJORBBS.H:105 (WG2 MAJORBBS.H:75) |
NGROUPS | NUMGRPS (17) | MAJORBBS.H:62 |
FLNSIZ (13) | GCMAXFNM for file names, GCSTRPTH for stored paths | FIOAPI.H:85-102 |
btuhrt | ticker, btuTicker() (USHORT) | BRKTHU.H:214-217 |
STATIC | static | WG2 GCOMM.H:257 |
BOOL | GBOOL (typedef short) | GCTYPDEF.H:105 |
struct fndblk (name, size, date, time) | struct ffblk (ff_name[256], ff_fsize, ff_fdate, ff_ftime) | FIOAPI.H:37-44 |
FILE * from opnmsg() | HMCVFILE | MCVAPI.H:54 |
sendmsg(), GME workb | gmeSendMsg(), VOID *pWork (GMEWRKSZ 518 under GCDOS, 1536 otherwise) | GME.H:1551, GME.H:38-42 |
getdfre(disk) | dskfre(const CHAR *path) (#define dskfre v3dskfre) | FIOAPI.H:222-225 |
VBTRUE (0xFFFF) | ((GBOOL)(0xFFFF)), i.e. -1 | GCOMM.H:199 |
"MJRBBS.CFG", "BBSREQ.FLG", "WGSDRAW %s" | "wgserv.cfg", "wgsreq.flg", "wgsdraw %s" | LINGO.H:50,47, INTEGROU.H:139 |
halloc(), hfree(), getml() | removed from GCOMM.H; getml(ln) is alcmem(ln) | GCOMM.H:84 |
chimove, chiset, calcrc, cputype, fnroot, fnwext, fnext, filnpart, pathpart, cpyfil, substi, prfspd, unfrez, clreol | removed from the 3.2 headers | WG2 GCOMM.H |
The const CHAR * versus CHAR * hazard
Hazard. The WG3.2 headers are the first to be const-correct:
grep -c constoverWGDEV/INCfinds 1195 lines against 94 in the WG2 headers. The WG1/WG2 text, and any code written to it, is not. Achar *argument converts silently toconst CHAR *, so constant parameters cost nothing; but a return value that becameconst CHAR *breaks callers:CHAR *p = getfnm(fid);is a warning in C and an error in C++ (Borland-w/-A, or a.cppfile), and writing through the pointer is forbidden by contract because it points into engine tables or a reused static buffer. A parameter that is stillCHAR *tells you the opposite: the engine may write into your buffer, so you must not pass it a string literal or read-only data.
Return values that became const (breaking for callers)
All 25 are return-type changes from WG2 char * / struct x * to WG3.2 const CHAR * / const struct x *.
...
Functions with a const return that did not exist in WG2 (no migration, but document them as const from the start): ncdatel (DNTAPI.H:213), ncedatl (:225), prndat (:315), prnday (:321), prntim (:310), strBirthdate (MAJORBBS.H:975), v2sdatl (VBDATIM.H:49), fmtname (GALTEXT.H:64), gmeGetAppInfo (GME.H:1140), gmeEmlSysUID (GME.H:779), gmeGetGrpP/gmeNamedGrpP/gmeNextGrpP/gmePrevGrpP, gmeGetGrpFDefP/gmeNextGrpFDefP/gmePrevGrpFDefP, mhsGatewayName (MHSALIAS.H:59), gmimctyp (MIMECTYP.H:36), smtpHost/cvtDate (SMTPEXP.H:75,122). 53 functions in WGDEV/INC return a const pointer in total.
Parameters that gained const (harmless to callers; the printed prototypes are out of date)
212 functions differ in constness between WG2 and WG3.2. Besides the 25 returns above, the rest are parameter-only: GME.H 99, GCOMM.H 27, LOCKNKEY.H 20, GALFILH.H 15, USRACC.H 14, FIOAPI.H 10, MAJORBBS.H 8, DNTAPI.H 6, BRKTHU.H 4, MHSALIAS.H 3, VBDATIM.H 3, TFSCAN.H 2, GALTEXT.H 1. The ones this guide uses everywhere are sameas, sameto, samein, samend, stlcpy (GCOMM.H:409), stlcat, stzcpy, skpwht, alcdup, itemcnt, itemidx, alldgs, allhex (GCOMM.H); uidxst, onsys, onbbs, instat, loadacc (MAJORBBS.H); haskey, givkey, rmvkey, othkey (LOCKNKEY.H); fnd1st, deldir, normspec (FIOAPI.H); and nearly the whole GME API. In WG3 text, print every read-only string parameter as const CHAR *.
Not const-only; do not describe these as "just const": crc16, crc32, c16, c32 (GCOMM.H:1025,1030) took unsigned char * and now take const CHAR *, so the signedness changed; clsize and dskfre (FIOAPI.H:191,225) took int drive and now take const CHAR *path; insfile (GALFILH.H:649) took struct fndblk * and now takes const struct ffblk *.
Still non-const in 3.2 (the engine may write; never pass literals)
| function | prototype | consequence |
|---|---|---|
prf | GCOMM.H:806 VOID prf(CHAR *fmt, ...) | the format string is not const (WG2 GCOMM.H:445). A literal works in C; C++ with const-literal warnings does not. Same for spr(CHAR *ctlstg,...) (GCOMM.H:392). |
opnmsg | MCVAPI.H:54 HMCVFILE opnmsg(CHAR *mcvfil) | file name not const; returns HMCVFILE, not FILE * |
register_textvar | MAJORBBS.H:767 INT register_textvar(CHAR *name, CHAR *(*varrou)()) | the callback must return CHAR *: a routine that does return ncdate(...) returns a const CHAR * and needs a cast or a copy into a static buffer. This affects the examples in chapters 3 and 4. |
skpwrd | GCOMM.H:462 CHAR *skpwrd(CHAR *cp) | non-const in and out |
skpwht | GCOMM.H:458 CHAR *skpwht(const CHAR *cp) | const in, non-const out: the classic cast-away-const helper; safe only if the caller's string was writable |
fnmcse | FIOAPI.H:307 CHAR *fnmcse(CHAR *fname) | case-normalises the name in place; never pass a literal (GALPORT's own main does fnmcse(argv[1])) |
getasc | GCOMM.H:515 CHAR *getasc(INT msgnum) | returns a writable pointer into the message buffer (GCOMM.H:512, "returns ptr to message buffer"); callers that edit it alter the loaded message. Treat as read-only by convention. |
Variables and structure members: curfn (the current .MCV/message file name) is EXPWGSV(const CHAR*) curfn (MSGRDR.H:43; WG2 extern char *curfn), so assigning to it or writing through it is no longer legal. DFAFILE *dfaOpen(const CHAR *filnam, USHORT maxlen, const CHAR *owner) (DFAAPI.H:217-220) and dfaCreate(const VOID *filnam, ...) (DFAAPI.H:348) are const in the file name (the implementation casts the constness away with the comment "btvu will not modify", SRC/api/gcommlib/DFAAPI.C:762). In the C++-only Active HTML headers DNF.H:276-277,369 declare const CHAR *filepath, *filedesc and const CHAR *sym[2].
Rules for the WG3 text
- Show every read-only string parameter as
const CHAR *; leaveCHAR *only where the table above says the engine writes. - For each function in the first table, the receiving variable is
const CHAR *, or the result is copied withstlcpy(buf, p, sizeof buf)(GCOMM.H:409) before being edited. getfnm()returnsNULLif the file does not exist (otherv3tov32 changes.txt).skpwht(),getasc()andfnmcse()are the only places where a string literal can still crash a module.GALPORTnever touches constness: it renameschartoCHAR, soconst char *becomesconst CHAR *correctly,unsigned char *becomesCHAR *(the defect noted above), and noconstis added anywhere. The 3.2 prototypes must be compared by hand.
...
Previous: Major BBS v10: 27 Date and Time API | Contents | Next: Major BBS v10: 29 Major BBS v10