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:

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

oldnewold name still defined?
omdbtvdfaModeno
setbtvdfaSetBlkyes, LAYER.H
rstbtvdfaRstBlkyes, LAYER.H
qrybtvdfaQueryno
qnpbtvdfaQueryNPno
getbtvldfaGetLockno
obtbtvldfaAcqLockno
anpbtvlkdfaAcqNPLockno
llnbtvdfaLastLenno
absbtvdfaAbsyes, LAYER.H
gabbtvldfaGetAbsLockno
aabbtvldfaAcqAbsLockno
stpbtvldfaStepLockno
updbtvdfaUpdateyes, LAYER.H
upvbtvdfaUpdateVyes, LAYER.H
dupdbtvdfaUpdateDupno
insbtvdfaInsertyes, LAYER.H
invbtvdfaInsertVyes, LAYER.H
dinsbtvdfaInsertDupno
delbtvdfaDeleteyes, LAYER.H
clsbtvdfaCloseyes, LAYER.H
crtbtvdfaCreateno
cntrbtvdfaCountRecno
sttbtvdfaStatno
rlenbtvdfaRecLenno
unlbtvdfaUnlockno
wslbtvdfaWasLockedno
qeqbtvdfaQueryEQyes, LAYER.H
qnxbtvdfaQueryNXyes, LAYER.H
qprbtvdfaQueryPRyes, LAYER.H
qgtbtvdfaQueryGTno
qgebtvdfaQueryGEno
qltbtvdfaQueryLTno
qlebtvdfaQueryLEno
qlobtvdfaQueryLOyes, LAYER.H
qhibtvdfaQueryHIyes, LAYER.H
gcrbtvdfaAbsRecyes, LAYER.H
geqbtvdfaGetEQno
gnxbtvdfaGetNXno
gprbtvdfaGetPRno
ggtbtvdfaGetGTno
ggebtvdfaGetGEno
gltbtvdfaGetLTno
glebtvdfaGetLEno
globtvdfaGetLOno
ghibtvdfaGetHIno
aqnbtvdfaAcqNXno
aqpbtvdfaAcqPRno
anibtvdfaAcqNXino
apibtvdfaAcqPRino
acqbtvdfaAcqEQyes, LAYER.H
agtbtvdfaAcqGTno
agebtvdfaAcqGEno
altbtvdfaAcqLTno
alebtvdfaAcqLEno
alobtvdfaAcqLOno
ahibtvdfaAcqHIno
slobtvdfaStepLOno
snxbtvdfaStepNXno
sprbtvdfaStepPRno
shibtvdfaStepHIno
ulsbtvdfaUnlockOneno
ulmbtvdfaUnlockCurno
ulobtvdfaUnlockSelno
ulabtvdfaUnlockAllno
gabbtvdfaGetAbsno
aabbtvdfaAcqAbsyes, LAYER.H

opnbtv is not in GALPORT's table, and it is the one function whose signature gained a parameter. WG2 opnbtv(name,maxlen) is, in WG3.2, DFAFILE *dfaOpen(const CHAR *filnam, USHORT maxlen, const CHAR *owner) (DFAAPI.H:217-220); owner is the Btrieve owner name (NULL if none). GALPORT leaves every opnbtv(n,s) as it is, which compiles only if LAYER.H:6 (#define opnbtv(n,s) dfaOpen(n,s,NULL)) or a project-local shim is in scope; otherwise the call is an undeclared function. Renaming by hand needs the extra argument: dfaOpen(n,s,NULL) (this is what SRC/api/dfcapi/DFCCUST.C:127,132,144 writes).

crtbtv is also missing from GALPORT, and it swaps arguments: WG2 crtbtv(char *filnam, void *databuf, int lendbuf, int keyno) (BTVSTF.H:167) is WG3.2 VOID dfaCreate(const VOID *filnam, VOID *databuf, SHORT keyno, USHORT lendbuf) (DFAAPI.H:348). Both trailing parameters are integers, so a blind rename compiles and creates the file with the key number as its record length. Most modules create their files with .VIR/.BCR scripts, which is why this is easy to miss.

Other signature changes the rename does not address:

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

functionWG3.2note
getfnmGME.H:845 const CHAR *getfnm(USHORT fid)recorded by the kit author in otherv3tov32 changes.txt ("changes from v30 to 3.20": CHAR * becomes const CHAR *, "returns NULL if doesn't exist")
getftpc, tpcfnmGME.H:849, GME.H:989forum topic name; tpcfnm's parameter is also const
extAdrForNamGME.H:841printed as char * in the WG2 addendum
udlnam, ulname, dlnameGME.H:1085, 1524, 1528upload/download names (msg parameter also const)
accstr, gmexinf, exphlpGME.H:1855, 744, 1926
expaspGME.H:1891to and msg also const
expinfGME.H:1922 const struct expinfo *fields read-only
getdefp, fiddefp, seqdefp, nxtdefp, prvdefpGME.H:1199,1208,1217,1226,1235 const struct fordef *forum-definition walkers: copy the fordef before editing
tagmsgGME.H:1632 const struct message *
fharrGALTEXT.H:57 struct fmthlr const * const *
ncdate, nctime, ncedat, ncudntDNTAPI.H:209,217,221,229 const CHAR *highest impact: chapters 5 and 11 teach char *ascdat; ascdat=ncdate(date);. The result points into a library-local buffer that the next call overwrites. Declare the variable const CHAR *, or copy it out.
v2sdat, v2stimVBDATIM.H:44,53VB date to string

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.