Versions Compared

Key

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

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
%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 (WG2 BRKTHU.H:88, volatile unsigned long) is not declared in WG3.2; the tick counter is EXPGSBLV(volatile USHORT) ticker with btuTicker() (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() and ncudnt() return const CHAR * (DNTAPI.H:209,217,221,229), as do the new ncdatel() (:213) and ncedatl() (:225); the date/time arguments are USHORT (:209-231). The examples here declare char *ascdat; in WG3.x declare const CHAR *ascdat;, or copy the result with stlcpy(buf,p,sizeof buf) (GCOMM.H:409) before modifying it. The result is a library-local buffer reused by the next call. dcdate() now takes const CHAR * and returns USHORT (GCINVALIDDOT if 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.H and no struct fndblk in WGDEV/INC; fnd1st()/fndnxt() use struct ffblk (ff_reserved, ff_fsize, ff_attrib, ff_ftime, ff_fdate, ff_name[256], FIOAPI.H:37-44), and the time/date members are unsigned 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): VBTRUE is ((GBOOL)(0xFFFF)) (GCOMM.H:199) and GBOOL is typedef 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