Versions Compared

Key

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

Reliability

Debug Versions

Applies to: v10

Debugging a v10 add-on: to debug in Release mode, start the BBS, then in Visual Studio choose Debug, Attach to Process, and select wgserver.exe (MBBS10.txt section 3). Some bugs appear only in Release because, according to MBBS10.txt, Debug builds zero out pointers (so garbage memory does not always show up), and likewise for string-literal misuse (chapter 29, section 29.4). The Debug-pointer-zeroing statement is the author's observation: unverified.

You can build and run debug versions of the baseline and some or all add-ons during testing or when otherwise tracking down problems. There’s a small performance loss, so everyone doesn’t want to run debug versions of software all of the time. Once a product is released, it is generally released as a non-debugging release.

As a developer, you can take advantage of debug-only code in the debug versions of your .DLLs. In addition to writing basic debug-only code, you can make use of the debug-only tools described below. By simply building the debug version of the baseline, you can take advantage of the debug code Galacticomm included in the baseline.

See page 23 for details on building the debug version of the baseline. Also, see page 27 for details on making your own .MAK and .LNK files in such a way as to support a debug version. If you follow those guidelines, you can build a debug version of your own .DLL.

To write code that will only execute when it’s compiled for the debug version, use the DEBUG define:

#ifdef DEBUG
    for (i=0 ; i < MAXLST ; i++) {
        if (list[i] == NULL) {
            catastro("NULL list entry!");
        }
    }
#endif
Assertions

An easy to use debugging tool is the assertion. Assertions are failures triggered by the ASSERT() macro. ASSERT() is used to assert that a condition is always true. When DEBUG is not defined, ASSERT() calls are not evaluated. When DEBUG is defined, ASSERT() will fail if the passed condition is not true. In the failure message will be the filename, file version, line number, and specific condition that failed. By default, assertion failures take the form of catastro() crashes. But, assertions can be altered to fail in different ways, as described below.

Using an ASSERT is an excellent way to prove that assumptions made in the code are indeed correct assumptions: parameters are within range and things are generally the way you expected them to be. Not only do the ASSERT() calls help track bugs by failing from time to time, but they also help those reading the code understand the assumptions being made by the developer.

If you would like to use ASSERT() in one of your C files, you’ll first need to define the FILREV symbol at the top of it as the version number of the file. If your version control system doesn’t offer the ability to automatically fill in text with version numbers, you’ll have to maintain this number yourself:

#define FILREV "1.0.4.1"

To use ASSERT(), just call it like a function, passing it a condition to test:

ASSERT(ptr != NULL);

The ASSERTM() macro is the same as ASSERT(), except it allows you to specify a special message to appear in resulting failure messages in place of the condition string:

ASSERTM(ptr != NULL,"Developer passed NULL to rsp2read()!");

It’s critical that you are careful not to write any ASSERT()s or other debug-only code that will alter the manner in which non-debug code will run. For example:

ASSERT(i++ != 3);

In this example, the debug version will increment i, the non-debug version won’t. The following code may rely on i being incremented, and work fine as long as you’re running the debug version. Once you build final, non-debug shipping disks, you’ll be surprised to find a new bug. Bugs caused by debugging code are often the most painful.

Phase Transitions

Another helpful method of debugging involves using phase transitions. Phase transitions are used to track the basic flow of code by recording major events. The BEG_PHASE() and END_PHASE() macros are used to record the beginning and end of phases or events. The last x phase transitions are reported in catastro() and GP crashes to help understand what led to the crash. BEG_PHASE() and END_PHASE() both take a string and a long for a brief description of the phase and any relevant data. Generally, they are used to bracket some well-defined set of code:

BEG_PHASE("Status handling",0);
(*(module[usrptr->state]->stsrou))();
END_PHASE("Status handling",0);

In the above case, the phase transitions bracket a module’s handling of a status code. BEG_PHASE() and END_PHASE() calls don’t necessarily have to have a one-to-one correspondence:

BEG_PHASE("Global commands",0);
for (i=0 ; i < nglobs ; i++) {
    rc=(*globs[i])();
    END_PHASE("Global command",globs[i]);
    :
    :
}

In the above case, the address of the global command just executed is included as the extra parameter to END_PHASE(). This will report the address of the global command just executed along with the Global command end transition message.

Debug Options in CNF

If you create any debug-only CNF options, put them in CNF’s level 95. That’s the level where all debugging options go by default. A Sysop can edit those options by running CNF directly from DOS with a special command-line parameter:

CNF -L95
The Baseline's Debugging Module

The Debugging in baseline module is installed automatically as part of the Client/Server Developer’s Kit. By default, it’s disabled. To enable it, go to Basic Utilities (choice 7 on the Introductory Menu), run WGSDMOD (the Enable/Disable Modules utility), and move Debugging in baseline from the Expressly Disabled column to the Available column.

Applies to: v10

Not in v10. The Client/Server (Visual Basic client app) mode was removed in v10 (MBBS10.txt section 2; the v10 history has the commit "Initial port of GALTELE including removal of AHTML and CS related code"). Read this passage as WG1-3.x history only. This paragraph says the module is installed with the Client/Server Developer's Kit; whether a "Debugging in baseline" module ships with v10 is unverified.

This module provides for a number of special debugging features. Some only take effect when running the debugging version of MAJORBBS.EXE. Others take effect under all circumstances.

Once you enable the module, you may notice various text flying by at the top of your Main Console when your server is up and running. That’s one of the features of the debugging module. It can display execution addresses and phase transitions on the Main Console in case the server locks up or otherwise crashes.

Check out CNF level 95 once you’ve enabled the debugging module. All of its features can be turned on or off from there. The available options are briefly described in the option help messages. Two of the most notable are:

    the ability to debug memory allocations in order to detect memory under/overflow bugs; andthe ability to alter assertion failures to be quietly ignored or logged to disk rather than catastro(). Some Philosophy on Debugging

    Your best debugging work takes place long before you test-run any of your software. A programming task that’s well thought through and meticulously coded has the best chance of long term success.

      Design with vision and foresightCode with attention to detailTest thoroughlyDebugging work is inevitable. But you can save yourself lots of time and grief if you avoid slipping into the habit of using debugging as a programming tool. Routines should account for all possible conditions and be 100% predictable in the mind of the programmer before they are executed.

      You’re probably trying to increase your programming speed just like we are. Nothing will help your overall productivity more than an ingrained habit of completing highly reliable foundations before you proceed to use them. There are many techniques for making your foundations highly reliable: code walk-throughs, rigorous testing by the developer, line-by-line testing of source code, branch-by-branch testing, routinely retesting “repaired” code, alpha-testing (in-house), beta-testing (by motivated customers). The goal is to get software done fast, put it to use, and move on to other projects, without your customers having to find the problems and you solving them over the phone.

      Programming Tips for the Major BBS

      There are several unique things about the programming environment of the Major BBS. The multi-user single-tasking aspects mean that your code can’t wait very long for any one thing to happen.

      Once you become proficient in programming for the Major BBS, there are a few classes of problems you’ll want to be on guard against. If you review these problems and develop an eagle eye for them, then your code can be much more reliable and free from frustrating bugs.

      Don’t forget to set the message pointer with setmbk():

      Wrong wayRight way
      intint
      hdlstt(void)hdlstt(void)
      {{
      prfmsg(NOTAVAIL);setmbk(lclmb);
      return(0);prfmsg(NOTAVAIL);
      }return(0);
      }
      (lclmb is the return value of the original call to opnmsg())

      Remember to set the database pointer with setbtv():

      Wrong wayRight way
      intint
      lookup(char *name)lookup(char *name)
      {{
      return(qeqbtv(name,0));setbtv(gnfbb);
      }return(qeqbtv(name,0));
      }
      (gnfbb is the return value of the original call to opnbtv())

      Don’t call outprf() multiple times (resulting in double prompts):

      Wrong wayRight way
      prfmsg(GREETING);prfmsg(GREETING);
      if (problem) {if (problem) {
      prfmsg(WARNING);prfmsg(WARNING);
      outprf(usrnum);}
      }outprf(usrnum);
      outprf(usrnum);

      General Protection Faults

      The best thing and the worst thing about protected mode operation is the “General Protection” fault, or GP. Protected mode is designed to halt at the slightest sign of a program gone awry. The first time you try to unravel and debug a GP will be an adventure. But after all the work of tracking it down, it will probably lead you directly to a bug in your code.

      What is a GP?

      A General Protection fault is the computer CPU’s way of saying “I give up” or “I can’t do this”. Usually it has to do with an invalid or restricted memory address. There are other GP causes, like privilege violation, executing the wrong code, or “switching to a busy task”, whatever that is. If you’re getting one of these, your program has probably gotten pretty out of control.

      GP’s don’t catch every bug, not by a long shot. But they can catch certain thorny problems way before they get out of hand. The worst kinds of bugs to find are intermittent with inconsistent symptoms: you can’t make them happen when you want to, and it’s always something different when they go wrong. Or this variation: you make what should be an irrelevant modification, perhaps to add some debugging or probing code, and the symptoms change. This is exactly what can happen from random unintentional memory reads or writes, and this is exactly the kind of thing that a GP is likely to catch in the act, with a bull’s-eye on the instruction that made the memory reference. With some patience, you can sift through the clues at the scene of the crime and find out exactly what went wrong. This chapter is all about helping you get started with GP detective work.

      Kinds of GPs

      Illegal memory accesses can happen in hundreds of unusual ways, some of which may even be completely harmless in a program running in real mode. In protected mode, however, they cause a GP fault. Here are three common programming errors that can result in GP’s:

      ####### A. NULL passed to a routine that uses it as a pointer

      For example, consider the following code fragments:

                      ...
                            blah(margv[0],NULL);
                      ...
                      blah(stg1,stg2)
                      char *stg1,*stg2;
                      {
                              if (strcmp(stg1,stg2) == 0) {
                                    ...

      This will cause a GP when strcmp() is called, because although NULL is not an illegal value for a pointer, to access memory through it is an illegal operation. Right? When you pass NULL as a pointer, you never mean “go to the memory at absolute memory location zero and look at whatever bytes are there.” You mean “this here is the absence of a pointer”. This is not a problem in real mode ordinarily because absolute memory location zero has some garbage in it that is unlikely to match a normal string. Referring to NULL may be similar to referring to the empty string, "", and it is possible when writing real mode programs to form the bad habit of using the two interchangeably. Protected mode is not going to let you get away with this.

      A special case of this class of problem worth noting is the use of any of the macros from STDIO.H: getc, putc, getchar, putchar, ferror, feof, or fileno, with a NULL file pointer. You might think that attempting to do file I/O with a NULL or garbage file pointer would have no result. It turns out that it results in arithmetic being done on some illegal location in memory which, in protected mode, causes an immediate GP.

      ####### B. Accessing off the front or end of an array

      The high scrutiny mode available with the Debugging in baseline module vastly increases the likelihood of catching these errors with GPs.

      The most common way this happens in practice is if you use invalid array indices. However, not every invalid array access attempt will cause a GP. It is complicated, because protected mode will only detect an attempt to go outside a whole segment, and one segment may contain several arrays, variables, structures, etc. A classic example of this kind of bug is the innocent looking little binary search routine in none other than Kernighan & Ritchie’s revered tome “The C Programming Language”, first edition, page 129 (we reformatted the code to match our own formatting standards):

               1      struct key *binary(word,tab,n)
               2      char *word;
               3      struct key tab[];
               4      int n;
               5      {
               6           int cond;
               7           struct key *low,*mid,*high;
               8
               9           low=&tab[0];
              10           high=&tab[n-1];
              11           while (low <= high) {
              12                mid=low+(high-low)/2;
              13                if ((cond=strcmp(word,mid->keyword)) < 0) {
              14                     high=mid-1;
              15                }
              16                else if (cond > 0) {
              17                     low=mid+1;
              18                }
              19                else {
              20                     return(mid);
              21                }
              22           }
              23           return(NULL);
              24      }

      This code begins to come unglued if the sought keyword fits sequentially before all entries in the sorted tab[] array, and the tab[] array just happens to physically reside at the beginning of a segment or selector (that is, its offset is 0x0000). Then the instruction in line 14 eventually does this: high=&tab[-1]. That pointer computation results in an offset of 0xFFFF or thereabouts. This does not generate a GP yet, because the high pointer is not dereferenced.

      But now things go from bad to worse, because the test in line 11, which is supposed to fail and halt the loop, instead succeeds, and mid is inexorably dragged upward until it points beyond the end of the region allowed for the selector. Finally, a GP occurs in the strcmp() routine invoked in line 13.

      To fix this code, you could put the following three lines between lines 13 and 14:

              13.1            if (mid == low) {
              13.2                 break;
              13.3            }

      And, to be truly thorough about it (in protected mode this tends to be a good idea), you can guard against the possibility that the top of the table is flush up against the high bound of a full 64K data segment by inserting the following between lines 16 and 17:

               16.            if (mid == high) {
               16.2                break;
               16.3           }

      Another example of this is a situation in which you wish to truncate a string to a certain maximum length, without knowing in advance just how much storage has been allocated for the string. Consider the following code fragments:

              :
                   speak("hi there");
              :
              speak(stg)
              char *stg;
              {
                   char temp;
                   temp=stg[20];
                   stg[20]='\0';
                   printf(stg);
                   stg[20]=temp;
              }

      In real mode, this is not a problem because even if the memory location that is 20 beyond the start of stg is in some other segment, you are putting it back to what it was when you are through. In protected mode, though, this type of thing can generate an immediate GP, depending on how close the "hi there" string is to the end of the segment in which it is allocated.

      ####### C. Too few arguments in a call to printf() or prf() or prfmsg()

      If your control string has more %s place-holders in it than there are pointers in your argument list, the machine will find itself picking up random stack contents as a pointer, and accessing memory there. Actually, the mere loading of a random stack value into a selector register is likely to generate a GP right off. If not, then accessing memory through a random offset is likely to exceed the length bounds of the selected segment.

      Sysop GP Handling

      When a Major BBS Sysop wants maximum up-time for his server, he sets CNF option GPHDLR in Hardware Setup to YES:

      GPHDLR Continue operation after “GP” errors? YES

      This causes the server to attempt to recover from GP errors after reporting them in the Audit Trail (see Sysop’s Guide for details). To be on the safe side, the user being serviced at the time of the GP is logged off immediately, and his channel is reset. But the server stays up and running (or tries to).

      This also helps with hacker protection if a user discovers a way to generate an otherwise harmless GP: with GPHDLR set to YES, a GP simply logs him off.

      Developer GP Handling

      But developers should use GP’s on their demo or support the Major BBS server to maximum advantage for tracking down bugs.

      GPHDLR Continue operation after “GP” errors? NO

      In this mode, extensive information on the GP is captured in a text file \WGSERV\GP.OUT.

      Reading a GP.OUT Report

      A GP is a software interrupt 13. You could also get other software interrupts for other disastrous conditions like interrupt 12 for a stack fault. One possible cause of interrupt 12 is an infinitely recursive routine. But only a GP can provide you with a lengthy report.

      Keep in mind that GP.OUT accumulates reports, so you’ll want to look at the bottom of the file. Here is an example of one report in a GP.OUT file:

              WORLDGROUP GP @ 2d4f:031a EC 0000 (recorded 12/16/94 17:11:17)
              GP'ed between 2d4f:0000 _INIT__TELECON and 0000:0000 Unknown
              AX=0000 BX=0000 CX=0000 DX=0787 SI=0005 DI=0054 BP=2a88 ES=0000 DS=2d57 Flags=3246
              Current CS:IP==>26 83 0f 01 b8 f7 04 8e c0 26 c4 1e 87 08 26 c7
      
              YOUR SYSTEM NAME HERE
              Server Version: 1.00
              User 3  channel 00  User-ID "Sysop"  status 3
              Online level 6, state 5, substate 0
              MSG:galtlc.mcv/-1
              Module "Teleconference"
              Input "T"
      
              0167=C:\WGSERV\MAJORBBS.EXE
              0717=C:\WGSERV\GALGSBL.DLL
              073f=C:\WGSERV\BBSBTU.DLL
              075f=C:\WGSERV\DOSCALLS
              2a5f=C:\WGSERV\GALMSG.DLL
              2cff=C:\WGSERV\GALRSY.DLL
              2d3f=C:\WGSERV\GALTLC.DLL
              2d6f=C:\WGSERV\GALTXV.DLL
              2d97=C:\WGSERV\GALUIE.DLL
              2dbf=C:\WGSERV\GALXIT.DLL
              2de7=C:\WGSERV\GALTST.DLL
              Stack:
              0707:2a78  04ff  0746  04ff  0054  2f47  04ff  0054  0005               0707:2a88 >2aaa< 0ba3  0197  04ff  0000  098a  0197  04f7               0707:2a98  0000  4f54  0050  2aaa  0029  039f  0074  0065               0707:2aa8  04f7 >2ac0< 529a  018f  0039  28ef  0001  0000               0707:2ab8  04f7  1b32  0003  0000 >2ace< 3579  018f  04f7               0707:2ac8  000e  4f84  018f >2b30< 3099  018f  04f7  022f               0707:2ad8  018f  0707  1b14  0000  0000  0000  0000  0000
              0707:2ae8  0000   0000   0000   011f   96c7  0017   0006  0000          0707:2af8  0707   0000   011f   966b   0017  0e29   0000  0e29          0707:2b08  0000   2b36   0707   0707   0001  1330   26cc  0147          0707:2b18  1b32   0707   1b32   1b14   2b36  4c48   016f  0578          0707:2b28  0707   0587   0707   000f  >0000< 014f   016f  0000          0707:2b38  0000   0000   fdcc   077f  ----  ----  ----  ---             0707:2b48  ----  ----  ----  ----  ----  ----  ----  ---                        0707:2b58  ----  ----  ----  ----  ----  ----  ----  ---                0707:2b68  ----  ----  ----  ----  ----  ----  ----  ---                0707:2b78  ----  ----  ----  ----  ----  ----  ----  ---                0707:2b88  ----  ----  ----  ----  ----  ----  ----  ---                        Routines:
              0197:07c5 _GOPAGE         <     0197:0ba3       <   0197:0e3d _DSPMNU
              018f:4e23 _NXTLOF         <     018f:529a       <   018f:53be _CURUSR           018f:3487 _HDLINP         <     018f:3579       <   018f:35e4 _CLRXRF           018f:2502 _KILETC         <     018f:3099       <   018f:3145 _CONDEX           0000:0000 Unknown         <     016f:014f       <   016f:0155 __CLEANUP
      GP Location

      The first line of GP.OUT has the CPU instruction pointer CS:IP (or CS:EIP depending on the CPU) contents, which reflect the location (address) of the fault. Usually this points to an instruction that the CPU refused to execute for some reason. This line also tells you when the GP occurred. If you see GPCNT here, then the Sysop has GPHDLR set to YES and the GP reported is not the first (and perhaps not the most informative — have them set GPHDLR to NO and get you another GP.OUT).

      GP Vicinity

      The second line of GP.OUT attempts to place the CS:IP between two public symbols that you can search for in your source files. Only symbols declared EXPORT are included here though. The only EXPORT routine in your whole .DLL is probably your init__xxx() routine (page 42). If the GP occurred in a source file with no EXPORT routines, you’re likely to see some irrelevant addresses. You can still get an idea what file the GP is in from the .DLL list. More on that below.

      For a reproducible GP (one you can make happen any time you want), you might declare some routines EXPORT just to get more information here. Often, narrowing the problem down to one routine is enough to start studying the routine and to find the problem.

      Registers

      This section shows the contents of the assembly language registers right when the GP occurred.

      Code at the GP Location

      Here on the fifth line of GP.OUT are 16 bytes of executable code starting from the GP location. This includes the actual instruction that caused the GP. This object code can come in handy when searching for the exact locations in an assembly listing (more below).

      User Conditions

      The next section of GP.OUT shows information on the most recent server activity on a user’s channel.

      Server Version: 1.00 the Major BBS server software version

      User 3 User number (usrnum, see page 56)

      channel 00 Channel number (hexadecimal, page 56)

      User-ID "Sysop" User-ID on channel most recently serviced

      status 3 Status code from the channel

      Online level 6 usrptr->class, 6 is ACTUSR — online and active

      Applies to: WG3.x

      Header check: usrptr->usrcls in WG3.2 (MAJORBBS.H:105; chapter 3).

      state 5 usrptr->state (see page 45)

      substate 0 usrptr->substt

      MSG:galtlc.mcv the current .MCV file being read

      /-1 the last message read from this file (-1=none)

      Module From the usrptr->state code (5 in this example)

      "Teleconference"

      Input "T" Most recent status-3 input line on the server

      The usrptr->state code represents the module the user was in. Sysops choose the module by name when they create a module page during offline Menu Tree Design. Module names are also listed in the Miscellaneous Statistics screen of the main console.

      In many cases this information at the top of a GP report can be very helpful. But don’t trust it too much. The most recent user activity is not necessarily related to the GP at all. In fact, you should carry a highly skeptical attitude into all of your debugging efforts, always seeking a thorough and precise understanding of what your program is doing, while understanding thoroughly how it is supposed to work.

      To put more debugging information into GP.OUT, you can carefully add some code to the lower part of appgprept() in PLBBS.C. You’ll see the fprintf() calls that formatted all of this information, along with careful checking in case pointers are not usable. Using a bad pointer inside the GP report routines is like accidentally exploding a bomb at the crime scene — you’ll lose the evidence from the original crime due to the new one on your hands.

      .DLL Selectors

      This is a list of the starting selectors for each of the .DLL’s you have loaded on the server. You can find out in which .DLL the GP occurred by finding the highest .DLL starting selector that is less than the GP selector.

      In the example above, the GP occurred at address 2d4f:031a. That’s somewhere in GALTLC because GALTLC.DLL starts at 2d3f and the next one, GALTXV, starts at 2d6F. There’s a little more you can find out here. Selectors are created in increments of 8 hexadecimal.

              2d3f    GALTLC starting selector
              2d47    \run286\bc4\lib\c0phdll.obj
              2d4F    \WGSERV\phobj\mjrtlc.obj
              2d57
              2d5f    }(other selectors used by GALTLC)
              2d67
              2d6f    GALTXV starting selector
              2d77    :
              2d7f    :

      After the starting selector, selectors are created for each of the .OBJ files in the order they are listed in the .LNK file. In GALTLC.LNK there are two .OBJ files. The GP occurred in the code from MJRTLC.OBJ, which of course comes from MJRTLC.C. The offset starts at 0000 in the code from that file, so the error occurred 031a bytes into the object code produced from MJRTLC.C.

      Note: This selector counting falls apart if you see a .LIB file called out in the .LNK file — this may link the equivalent of several .OBJ files and use up several selectors. There is a .LIB file linked among the .OBJ files in LTBBS.LNK, for example, the linker response file that goes into making MAJORBBS.EXE.

      Once you get a feel for these things you’ll know that 031a should be pretty near the beginning of a file as big as MJRTLC.C.

      Stack Dump

      The stack dump is very relevant to “the crime” of the GP, and it’s rich with data — too rich. Let’s jump ahead to the Routines section with the return address chain at the bottom. That’s where the most meaningful information is pulled from the stack dump and given symbols from the source code where possible. We’ll come back to the stack dump later.

      Routines in the Return Address Chain

      At the bottom of GP.OUT are the chain of return addresses pulled from the stack. These reflect the nesting of subroutines that the CPU was executing at the moment of the GP. The first one in the list, 0197:0ba3, is pulled from the stack at 0707:2A8A or at SS:BP+2. If you know how C language subroutines are implemented in assembly language, it’s not hard to realize that this is the return address to some ancestor routine that called (perhaps indirectly) the routine in MJRTLC.C where the GP was triggered.

      The first thing that happens in some subroutines is PUSH BP then MOV BP,SP. This means the 2 bytes at [BP+0] are the old BP, and the 4 bytes at [BP+2] are the return address. But not all routines save and reload BP. Since it’s the chain of BPs in the stack that we trace, not actually the return addresses, some routines get “skipped”. If a routine doesn’t save and reload BP, we won’t find the return address to its parent that was pushed when the routine was called. So its parent will appear to be skipped in the list of routines at the bottom of GP.OUT.

      So far we know:

      1. Somewhere in a routine early in MJRTLC.C a GP was triggered.

      2. That routine was called (perhaps indirectly) by a routine between gopage() and dspmnu().

      A grep of source files turns up gopage() and dspmnu() in MENUING.C. The call to the routine in MJRTLC.C must be somewhere between these points. That is, in one of the routines gopage(), gomodl(), gocond(), gomenu(), or gofile(). The call couldn’t be in dspmnu() itself because 0197:0ba3 is less than 0197:0e3d, the start of dspmnu().

      The call must be in gomodl(), because that fires off the sttrou() entry point for a module page (page 48), and early in MJRTLC.C is telecn(), the sttrou() entry point for the Teleconference module.

      The next ancestor of gomodl() shown in the return address chain is between nxtlof() and curusr(). This has a different selector than gomodl() (018f versus 0197) so it must come from a different file. In fact it comes from MAJORBBS.C. You’ll notice that there’s no call to gomodl() in all of MAJORBBS.C, but there’s one in MENUING.C inside of gopage(). Hmm, this is making sense. There are reams of calls to gopage() in MAJORBBS.C for menu tree pages in general. And gopage() calls gomodl() for module pages in particular. gopage() was skipped in the return address chain. That’s probably because gomodl(), after various compiler optimizations and shenanigans, didn’t need to save and reload BP.

      Stack Dump, Revisited

      The notations like >2aaa< in the stack dump are BP save locations. When traversing the chain of saved and loaded BPs to generate the return address chain at the bottom of GP.OUT, the BP save locations are flagged with little "> <" symbols. The return addresses shown at the bottom immediately follow each of the "> <" symbols. For example, the >2aaa< is followed by 0ba3 and 0197. 0197:0ba3 is the first return address in the list.

      Close scrutiny of the stack dump can help us determine the values of parameters passed between routines, and the values of automatic stack variables. In some cases, the values of pushed registers are also of some help in investigating the circumstances of the crime. But to do any of this, we have to look at the assembly language listing of the code where the GP happened and where the ancestor routines did their subroutine calling. And an assembly language listing lets us find out the exact instruction that caused the GP. Let’s start with the routine where the GP occurred, probably telecn(), definitely in MJRTLC.C.

      Assembly Listing

      To get the assembly language listing of MJRTLC.C, we have to generate assembly source code and then assemble it and make a listing:

              CD \WGSERV\SRC
              CTDLL -S MJRTLC
              CD \WGSERV\PHOBJ
              TASM MJRTLC,NUL,MJRTLC;

      Use CTPH -S for getting the assembly listing of files that are part of the kernel — that go to make up MAJORBBS.EXE. The -S parameter (capital S, not small s) asks for an .ASM assembly source file to be output instead of an .OBJ. Then TASM assembles \WGSERV\PHOBJ\MJRTLC.ASM and makes a listing file in \WGSERV\PHOBJ\MJRTLC.LST. (The nul means don’t generate an .OBJ file from the .ASM file.) That .LST file is pretty big. It’s where the offsets and object code can be found. To find what we’re looking for, there are two clues: The GP location is 2d4f:031a, so we can look in the vicinity of the offset 031a. And the code somewhere near there should be 26 83 0f 01 .... (from the fifth line of GP.OUT). Turns out it’s somewhere exactly at 031a:

      Turbo Assembler         Version 3.1        07/13/92 11:19:52       Page 10
      mjrtlc.ASM
      530                     ;
      531                     ;         case 0:
      532                     ;              tptr->flags¦=NOPAGE;
      533                     ;
      534 0316  C4 1E 0077r        les     bx,dword ptr tptr
      535 031A  26: 83 0F 01       or      word ptr es:[bx],1
      536                     ;
      537                     ;              usrptr->substt=1;
      538                     ;
      539 031E  B8 0000s             mov     ax,seg _usrptr
      540 0321  8E C0                mov     es,ax
      541 0323  26: C4 1E 0000e      les     bx,dword ptr es:_usrptr
      542 0328  26: C7 47 08 0001    mov     word ptr es:[bx+8],1

      Notice that the sixteen bytes of code don’t match exactly where 0000s goes with f7 04? Those 0000s and 0000e symbols means that the exact object code is not known at compile (or assembly) time. It will take linking and loading to find out those exact values. So, the object code confirms that we’re looking at the right instruction (the or instruction).

      So, here’s the crime scene, what was the crime? The instruction was or word ptr es:[bx],1. That’s a bitwise OR of the value 1 into some memory location. Notice that the very helpful assembly comments show the original C source code near the relevant assembly code. Turns out the NOPAGE constant is 1, so tptr->flags¦=NOPAGE is for sure the guilty instruction. A quick look at the registers in line 3 of GP.OUT shows that es:bx is 0000:0000. That’s pretty wild, isn’t it?. OR’ing to the location addressed by NULL is definitely GP territory. From MJRTLC.C we see that flags is the first field of the tlc structure (tptr is type struct tlc *), so tptr itself must be NULL.

      A scrutiny of the C source logic reveals that tptr is not expected to be initialized here: it’s just a low-level looping pointer. We cheated of course; this is exactly the line we inserted to make this GP happen.