You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Current »

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

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 old name still defined?
omdbtv dfaMode no
setbtv dfaSetBlk yes, LAYER.H
rstbtv dfaRstBlk yes, LAYER.H
qrybtv dfaQuery no
qnpbtv dfaQueryNP no
getbtvl dfaGetLock no
obtbtvl dfaAcqLock no
anpbtvlk dfaAcqNPLock no
llnbtv dfaLastLen no
absbtv dfaAbs yes, LAYER.H
gabbtvl dfaGetAbsLock no
aabbtvl dfaAcqAbsLock no
stpbtvl dfaStepLock no
updbtv dfaUpdate yes, LAYER.H
upvbtv dfaUpdateV yes, LAYER.H
dupdbtv dfaUpdateDup no
insbtv dfaInsert yes, LAYER.H
invbtv dfaInsertV yes, LAYER.H
dinsbtv dfaInsertDup no
delbtv dfaDelete yes, LAYER.H
clsbtv dfaClose yes, LAYER.H
crtbtv dfaCreate no
cntrbtv dfaCountRec no
sttbtv dfaStat no
rlenbtv dfaRecLen no
unlbtv dfaUnlock no
wslbtv dfaWasLocked no
qeqbtv dfaQueryEQ yes, LAYER.H
qnxbtv dfaQueryNX yes, LAYER.H
qprbtv dfaQueryPR yes, LAYER.H
qgtbtv dfaQueryGT no
qgebtv dfaQueryGE no
qltbtv dfaQueryLT no
qlebtv dfaQueryLE no
qlobtv dfaQueryLO yes, LAYER.H
qhibtv dfaQueryHI yes, LAYER.H
gcrbtv dfaAbsRec yes, LAYER.H
geqbtv dfaGetEQ no
gnxbtv dfaGetNX no
gprbtv dfaGetPR no
ggtbtv dfaGetGT no
ggebtv dfaGetGE no
gltbtv dfaGetLT no
glebtv dfaGetLE no
globtv dfaGetLO no
ghibtv dfaGetHI no
aqnbtv dfaAcqNX no
aqpbtv dfaAcqPR no
anibtv dfaAcqNXi no
apibtv dfaAcqPRi no
acqbtv dfaAcqEQ yes, LAYER.H
agtbtv dfaAcqGT no
agebtv dfaAcqGE no
altbtv dfaAcqLT no
alebtv dfaAcqLE no
alobtv dfaAcqLO no
ahibtv dfaAcqHI no
slobtv dfaStepLO no
snxbtv dfaStepNX no
sprbtv dfaStepPR no
shibtv dfaStepHI no
ulsbtv dfaUnlockOne no
ulmbtv dfaUnlockCur no
ulobtv dfaUnlockSel no
ulabtv dfaUnlockAll no
gabbtv dfaGetAbs no
aabbtv dfaAcqAbs yes, 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:

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

function WG3.2 note
getfnm GME.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, tpcfnm GME.H:849, GME.H:989 forum topic name; tpcfnm's parameter is also const
extAdrForNam GME.H:841 printed as char * in the WG2 addendum
udlnam, ulname, dlname GME.H:1085, 1524, 1528 upload/download names (msg parameter also const)
accstr, gmexinf, exphlp GME.H:1855, 744, 1926
expasp GME.H:1891 to and msg also const
expinf GME.H:1922 const struct expinfo * fields read-only
getdefp, fiddefp, seqdefp, nxtdefp, prvdefp GME.H:1199,1208,1217,1226,1235 const struct fordef * forum-definition walkers: copy the fordef before editing
tagmsg GME.H:1632 const struct message *
fharr GALTEXT.H:57 struct fmthlr const * const *
ncdate, nctime, ncedat, ncudnt DNTAPI.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, v2stim VBDATIM.H:44,53 VB 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)

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

  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.

Previous: Major BBS v10: 27 Date and Time API  |  Contents  |  Next: Major BBS v10: 29 Major BBS v10

  • No labels