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 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:
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./* or //, and keeps no comment state, so the continuation lines of a multi-line comment are not ported if they look like code."int" inside quotes is rewritten.BUFSIZ-1 aborts the run (Line needing porting too long!).| 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.
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 |
| 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.
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 |
const CHAR * versus CHAR * hazardHazard. 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.
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.
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 *.
| 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].
const CHAR *; leave CHAR * only where the table above says the engine writes.const CHAR *, or the result is copied with stlcpy(buf, p, sizeof buf) (GCOMM.H:409) before being edited.getfnm() returns NULL if the file does not exist (otherv3tov32 changes.txt).skpwht(), getasc() and fnmcse() are the only places where a string literal can still crash a module.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