Versions Compared

Key

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

Porting WG1/WG2 Source to Worldgroup 3.x

Applies to: v10

v10 changes to this chapter: LAYER.H and 2030.H (the Btrieve-name compatibility macros this chapter relies on) are not in the shared v10 inc/ (a project-local LAYER.H exists in the ported modules, e.g. src/isv/mjwmut/), so only dfa*() names work unless you copy it; whether the GALPORT renames still compile against v10 is unverified. The EXPORT_* macros changed signature (chapter 29, section 29.5), BBSVER is now BBSVERS (server.h:61), and ffblk.ff_name is 260 bytes (FIOAPI.H:44). The const 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 utility GALPORT.C (SRC/devutils/galport, identical to the copy in this repository), the headers themselves, and the header-level deltas in analysis/deltas. Every file:line citation 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:

...

  • It matches whole words only, longest match first (so unsigned long int wins over unsigned). The word must begin with a letter or digit; underscores are not word characters, so int_x is matched as int followed 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-1 aborts 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

oldnewnote
signedINTbare signed becomes INT.
intINTDOS 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 intUSHORTUSHORT.
unsigned intUINTUINT = typedef unsigned int (GCTYPDEF.H:71): 32-bit on NT, 16-bit on DOS.
signed intINTINT.
unsignedUINTUINT; 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 intSHORTSHORT.
shortSHORTSHORT typedef short (GCTYPDEF.H:95).
unsigned shortUSHORTUSHORT (GCTYPDEF.H:96).
signed shortSHORTSHORT.
long intLONGLONG.
longLONGLONG typedef long (GCTYPDEF.H:75).
unsigned long intULONGULONG.
unsigned longULONGULONG (GCTYPDEF.H:76).
signed longLONGLONG.
charCHARCHAR typedef char (GCTYPDEF.H:94).
unsigned charCHARGALPORT bug: maps to CHAR, dropping unsigned. UCHAR exists (typedef unsigned char UCHAR, GCTYPDEF.H:98). Hand-fix to UCHAR.
signed charSCHARSCHAR (GCTYPDEF.H:99).
doubleDOUBLEDOUBLE (GCTYPDEF.H:103).
floatFLOATFLOAT (GCTYPDEF.H:104).
BOOLGBOOLGBOOL 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.
voidVOIDVOID is a macro for void (GCTYPDEF.H:101, #ifndef VOID).
STATICstaticTable 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.
BTVFILEDFAFILEstruct 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).

...

oldnewchange
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, aabbtvdfaGetAbs, dfaAcqAbsthree-argument macros over dfaGetAbsLock/dfaAcqAbsLock (DFAAPI.H:169-170); the l suffix names the explicit lock-type argument

Compatibility layers

layerwhat it providesused 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.Hupper-case aliases (OPNBTV, CLSBTV, CLSNAM -> usrcls, BTVFILE) under #ifdef IS30not included by anything in the kit
GCOMM.H macrosgetmsg -> 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 namesWG2 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 textWG3.2header
usrptr->class (struct user)usrptr->usrcls; baud is now LONG; entstt and lingo were added, as were the 8-bit byecnt, col, ech, widMAJORBBS.H:105 (WG2 MAJORBBS.H:75)
NGROUPSNUMGRPS (17)MAJORBBS.H:62
FLNSIZ (13)GCMAXFNM for file names, GCSTRPTH for stored pathsFIOAPI.H:85-102
btuhrtticker, btuTicker() (USHORT)BRKTHU.H:214-217
STATICstaticWG2 GCOMM.H:257
BOOLGBOOL (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()HMCVFILEMCVAPI.H:54
sendmsg(), GME workbgmeSendMsg(), 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. -1GCOMM.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, clreolremoved from the 3.2 headersWG2 GCOMM.H

The const CHAR * versus CHAR * hazard

Hazard. The WG3.2 headers are the first to be const-correct: grep -c const over WGDEV/INC finds 1195 lines against 94 in the WG2 headers. The WG1/WG2 text, and any code written to it, is not. A char * argument converts silently to const CHAR *, so constant parameters cost nothing; but a return value that became const CHAR * breaks callers: CHAR *p = getfnm(fid); is a warning in C and an error in C++ (Borland -w/-A, or a .cpp file), and writing through the pointer is forbidden by contract because it points into engine tables or a reused static buffer. A parameter that is still CHAR * 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)

functionprototypeconsequence
prfGCOMM.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).
opnmsgMCVAPI.H:54 HMCVFILE opnmsg(CHAR *mcvfil)file name not const; returns HMCVFILE, not FILE *
register_textvarMAJORBBS.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.
skpwrdGCOMM.H:462 CHAR *skpwrd(CHAR *cp)non-const in and out
skpwhtGCOMM.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
fnmcseFIOAPI.H:307 CHAR *fnmcse(CHAR *fname)case-normalises the name in place; never pass a literal (GALPORT's own main does fnmcse(argv[1]))
getascGCOMM.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

  1. Show every read-only string parameter as const CHAR *; leave CHAR * only where the table above says the engine writes.
  2. For each function in the first table, the receiving variable is const CHAR *, or the result is copied with stlcpy(buf, p, sizeof buf) (GCOMM.H:409) before being edited.
  3. getfnm() returns NULL if the file does not exist (otherv3tov32 changes.txt).
  4. skpwht(), getasc() and fnmcse() are the only places where a string literal can still crash a module.
  5. GALPORT never touches constness: it renames char to CHAR, so const char * becomes const CHAR * correctly, unsigned char * becomes CHAR * (the defect noted above), and no const is added anywhere. The 3.2 prototypes must be compared by hand.