More Routines And Variables
Character and String Routines
match=sameas(stg1,stg2); case-insensitive string match
...
The sameto() function is like sameas(), but it allows the first parameter to be just a portion of the second. For example:
| Code Block |
|---|
sameto("good","gooder") == 1
sameto("good","good enough") == 1
sameto("best","best") == 1
sameto("baddest","bad") == 0
sameto("women","womanhood") == 0 |
Another variation:
| Code Block |
|---|
match=samend(longs,ends); |
The samend() routine compares endings of strings, asking if the first string ends with the second string, ignoring case. Examples:
| Code Block |
|---|
samend("the end","end") == 1
samend("dogs","s") == 1
samend("gooder","ER") == 1
samend("end","the end") == 0
samend("sheep","s") == 0 |
We remember the parameter order for sameto() and samend() by thinking of the prefix (shorts) sitting next to the prefix side of the long string (longs), therefore to the left of it in sameto().
...
This function searches the string for any occurrence of the substring, and returns 1 if it finds any. Examples:
| Code Block |
|---|
samein("good","gooder") == 1
samein("s","UNITED STATES") == 1
samein("can't","cannot") == 0
samein("badder","bad") == 0 |
sprstg=spr(ctlstg,p1,p2,...,pn);
sprintf-like string formatter utility
| Code Block |
|---|
char *sprstg; result string pointer (max 120 bytes) char *ctlstg; control string ( |
%l, etc. allowed) TYPE p1,p2,...,pn; sprintf-type parameters (max 12 bytes) |
This routine is frequently used itself as an argument to prf(), prfmsg(), catastro(), or other printf() format functions. Those functions do not support long integer or floating point conversions (%ld or %f), but spr() does. Warning: the string created by spr() must not exceed 120 bytes, including the terminating \0. Violation of this rule may have insidious results.
...
stlcpy() is the same as stzcpy() except that it doesn't bother to pad with more than 1 nul:
| Code Block |
|---|
stlcpy(dest,source,maxbytes); |
Use the following routines for parsing character strings of one or more words separated by whitespace characters:
...
Both spr() and l2as() use a 4-stage rotating-buffer technique to avoid the problem of multiple calls pointing to the same physical location. This means you can have up to 4 calls in a single parameter list before overlap will cause difficulties. For example:
| Code Block |
|---|
prf("Shares traded today: %s %s %s",l2as(nyse),l2as(amex),l2as(otc)); |
Each of the three calls to l2as() will return the address of a different buffer — not overlap three conversions into the same buffer.
...
See also the memory handling routines movmem(), setmem(), and repmem() on page 67.
Real-Time Routines: rtkick(), rtihdlr()
rtkick(time,rouptr); “kick off” routine after time delay
...
If you have a routine that you need to execute more often than once a second, you could register it with rtihdlr(). Once you start this, it runs the entire time the Worldgroup Major BBS server is up (don’t keep calling rtihdlr() on the routine like you could do with rtkick()). This routine will be running at interrupt level, so don’t try any DOS or GSBL calls except the chixxx() routines (see GSBL Guide). And be sure the routine uses as short a time as possible, or the server will lose its real-time responsiveness.
...
Applies to: WG3.x
Header check:
btuhrt(WG2BRKTHU.H:88,volatile unsigned long) is not declared in WG3.2; the tick counter isEXPGSBLV(volatile USHORT) tickerwithbtuTicker()(BRKTHU.H:214-217).hrtval()is still declared (GCOMM.H:734). The 16-bit rate and width differ from the text.
Time and Date Routines
date=today(); Find out today’s date
...
Applies to: WG3.x
const CHAR * vs CHAR * hazard. In WG3.2
ncdate(),nctime(),ncedat()andncudnt()returnconst CHAR *(DNTAPI.H:209,217,221,229), as do the newncdatel()(:213) andncedatl()(:225); the date/time arguments areUSHORT(:209-231). The examples here declarechar *ascdat; in WG3.x declareconst CHAR *ascdat;, or copy the result withstlcpy(buf,p,sizeof buf)(GCOMM.H:409) before modifying it. The result is a library-local buffer reused by the next call.dcdate()now takesconst CHAR *and returnsUSHORT(GCINVALIDDOTif invalid,DNTAPI.H:248) and accepts four-digit years; the Date and Time API is described in chapter 27.
char *ascdat; local buffer for date
...
See also page 322 for reading and setting a file’s time and date.
Numeric Routines
smaller=min(a,b); Find the smaller of two numbers
...
This routine calculates a 16-bit CRC based upon the polynomial x^16+x^12+x^5+1. This is the same CRC as is computed for the XMODEM-CRC protocol.
Text File Scanning
This suite of routines can be handy for scanning one or more text files, especially if you’re looking for lines that start with some prefix string. We use these routines to scan all .MDF files for all the lines we’re interested in. For a really thorough demo of the tfsxxx() routines, see how this is done in INTEGROU.C (available with the Extended C Source Developer’s Kit).
...
Suppose you needed to scan all .MDF files on the server and pass all module names through a routine called modnam() and all developer names through another routine called develn().
| Code Block |
|---|
if (tfsopn("*.MDF") > 0) { while (tfsrdl() != TFSDUN) { switch(tfstate) { case TFSLIN: if (tfspfx("Module Name:")) { modnam(tfspst); } else if (tfspfx("Developer:")) { develn(tfspst); } break; } } } |
Notice how one or more spaces may follow the colons in the .MDF files, but they are skipped by tfspst.
...
This just makes sure that if a file is opened that it gets closed, which is usually a good idea. Otherwise, you need to keep calling tfsrdl() until it returns TFSDUN.
Disk I/O
bufptr=mdfgets(buffer,size,fp);
Read a line of text from a file
...
This is just like the standard fgets(), except it uses \r as a line terminator (a hard carriage return on Worldgroupthe Major BBS), and it won’t have a line terminator on the last line if the file doesn’t have it.
...
int ok; 1=ok 0=couldn’t find file
char *fname; file path
| Code Block |
|---|
int time; HHHHHMMMMMMSSSSS coding (see page 318) int date; YYYYYYYMMMMDDDDD coding (see page 318) ok=settnd(fname,gmt70); Set the time and date for a file (file must not be open at the time) |
int ok; 1=ok 0=couldn’t find file
...
This routine checks through the DOS list of device drivers and other reserved names to make sure a proposed filename will not be misinterpreted as a device. It’s a great idea to use this routine especially if the filename is something a user typed (even if it’s the Sysop user). Did you know that writing to PRN.TXT will output to your printer? Calling rsvnam("PRN.TXT") will return 1 and catch this and other disasters.
...
Find First Matching File, Find Next
...
The following routines can be used to find out if a file exists, or to get help from DOS with breaking down a wildcard file specification (such as *.EXE) into its component files:
...
The fnd1st() and fndnxt() functions make use of the following data structure, defined in DOSCALLS.H:
| Code Block |
|---|
struct fndblk { /* used by fnd1st,fndnxt in datntim.c */ char junk[21]; /* */ char attr; /* file attribute (see masks below) */ unsigned time; /* time in HHHHHMMMMMMSSSSS format */ unsigned date; /* date in YYYYYYYMMMMDDDDD format */ long size; /* size in bytes */ char name[12+1]; /* name of file "FFFFFFFF.EEE" */ }; |
Applies to: WG3.x
Header check: there is no
DOSCALLS.Hand nostruct fndblkinWGDEV/INC;fnd1st()/fndnxt()usestruct ffblk(ff_reserved,ff_fsize,ff_attrib,ff_ftime,ff_fdate,ff_name[256],FIOAPI.H:37-44), and the time/date members areunsigned short. See the note in chapter 5.
After either routine returns 1, you can consult the name, size, date and time fields of the fb structure for information on the file.
The attr parameter to fnd1st() restricts the search to certain types of files (or more accurately directory entries — fnd1st() and fndnxt() are really directory scanning routines). Here are the possible bit components to the attr parameter of fnd1st(), and to the attr field of the fndblk structure. These are also defined in DOSCALLS.H:
| Code Block |
|---|
#define FAMRON 0x01 /* File attribute: read only */ #define FAMHID 0x02 /* File attribute: hidden */ #define FAMSYS 0x04 /* File attribute: system */ #define FAMVID 0x08 /* File attribute: volume id */ #define FAMDIR 0x10 /* File attribute: sub-directory */ #define FAMARC 0x20 /* File attribute: archive */ |
The only useful values we ever found for the attr parameter of fnd1st() are 0, meaning roughly to scan for files only, not subdirectories or volume IDs, and FAMDIR, meaning to check if a given name exists as either a directory or a file. For example, if there is a file named SRC, fnd1st(&fb,"SRC",FAMDIR) will report that it exists even though you were anticipating it finding a directory by that name. To check, look at fb.attr for the FAMDIR flag. If set, it is a directory. If not set, it may be any of the other choices (volume id, hidden, etc.).
You can refer to a DOS technical manual on interrupt 21H, function 4EH, for details on the other bits.
Everything Else
cpu=cputype(); Returns 88, 186, 286, 386
...
pascrit(); Set the DOS critical error handler to a routine that retries three times then pops up a friendly window. Must run with the GSBL (Software Breakthrough).
Boolean Values Exchanged With Client Apps
Applies to: WG2+
In VB, True is -1 and False is 0. If ok is 1, the following line will work:
| Code Block |
|---|
If ok Then |
The following line won’t, though, if ok is 1 and ok2 is 2:
| Code Block |
|---|
If ok and ok2 Then |
The above line will evaluate to False (0). This is because 1 and 2 in VB is False, given that and is a bitwise operation. It’s important to keep boolean variables, although technically Integers, only containing True (-1) or False (0) values.
...
Applies to: WG3.x
Header check (3.2):
VBTRUEis((GBOOL)(0xFFFF))(GCOMM.H:199) andGBOOListypedef short(GCTYPDEF.H:105), so in WG3.2 it evaluates to -1, not 65535.
...
Previous: Major BBS v10: 10 Offline Utilities | Contents | Next: Major BBS v10: 12 Reliability