Click above to get retro games delivered to your door ever month!

 Low Level Debugging Techniques
--------------------------------------------------------------------------------

  Besides the standard Clipper errors, the world of Windows brings us a
  new and terrible kind of problems: GPFs. As once a Windows programmer
  excellent described them: "Go and Pray Faithfully!".

  GPF is the shortname for General Protection Fault. All the Clipper
  programmers used to build MsDos Clipper apps in protected mode have
  ever experienced this kind of problem. Windows works in protected
  mode, so when we get a GPF under Windows, we are in a very similar
  situation as when we got them under MsDos.

  When a GPF ocurrs, Windows 3.1 shows a very uggly white modal window
  indicating that a GPF has ocurred and reports the name of the application
  that caused the error and the address inside of it where the error
  has been located. If the name of the application is a DLL and not our
  application name, it could means that our app did something wrong that
  finally made a DLL to crash (this is normally when experiencing any GPF
  at Windows USER.DLL), or that a DLL is not working properly and it is
  experiencing problems under a certain circunstance.

  Many Clipper programmers start building their own C language functions
  to use from Clipper, and in the beginning it is quite normal that they
  generate some errors that finally manifest as GPFs. In one case or in
  the other, it is good to get some basics to solve a GPF problem.

  Both linkers Blinker and Microsoft LINK let us generate a MAP file that
  describe the containts of our app. Using Blinker, you may use the
  following LNK sentence:

  MAP A, S                 // Generates a MAP file when using Blinker

  If you use Microsoft LINK, then you can specify a third comma separated
  parameter that indicates the name of the MAP file to generate:

  Link /se:2000 /NOE %1,, %1, FiveWin WinApi Clipper Extend 501_520...

  The second %1 tells Link.exe to generate a MAP file with the same name
  of our application.

  Now, using that MAP file we can locate the GPF source code location.
  Windows 3.1 reported the GPF address directly, and Windows 95 offers
  a 'details' button where that address is also shown. This address is
  normally shown using this format: SSSS:OOOO where SSSS is the segment
  address and OOOO is the offset address. Windows 95 uses a 32 bits
  offset SSSS:0000OOOO. Just discard the leftmost 0000, so you must look
  for SSSS:OOOO.

  Normally the address you are looking for will not exactly show at the
  MAP file, but instead you will need to look for a range. Look for the
  inmediate lower range to a given GPF address. If you are reviewing a
  Blinker MAP file, then you will normally be able to locate twice the
  address. The first one refeers to the 'segment code' where the function
  that generated the GPF is located, and the second time it may be the
  function code itself.

  On the Windows 95 GPF reporting DialogBox there is also another very
  usefull information "Bytes at CS:EIP:". Write down this sequence
  of bytes as they shown exactly the assembler source code where the GPF
  is beeing produced. If you have a debugger like Borland Turbo Debugger
  you will be able to locate that sequence of bytes, so you will find
  exactly the code that generates the GPF.

  FiveWin includes a very usefull dummy function named __GenGPF() that
  does nothing except generating a GPF. This is a good test you can try
  to get some experience. Simply place a call to __GenGPF() in your code
  and you will get a sure GPF. See the address we have described here,
  and try to locate the address of the offending code at your MAP file.
  If you have successfully done this test then you should have located
  the following addresses:

  0002:8E3D 001D0H     TOOLHELP_TEXT          CODE

  (these figures will be different in your code) and

  0002:8FC5  Res  __GENGPF

  TOOLHELP is the name of the C module where __GenGPF() is located. As
  you see, you get here agood feedback to start looking for a specific
  problem. If you don't get an idea why a certain GPF ocurrs even if
  you locate its origin, please contact us and we will try to assist
  you.

  Another source of problems that may end as a GPF, comes from a bad
  use of certain Windows API services. This type of error are more
  difficult to locate as the GPF point normally is far away from our
  wrong code. Here we recommend you to use a different strategy:

  Windows 3.1 provides an utility named DrWatson.exe that if a GPF
  occurs, will generate a LOG file where the latest Windows API missuse
  is reported. Many times this information is very usefull to locate
  the possible error origin.

  Once again the best assistant to locate an error is your own experience,
  that is why we strongly recommend you not to fight so hard, and if
  you don't get sollowing the above recommendations, simply contact us
  and we will try to assist you.