Undocumented Debugging

by Dave Harms

Published 1999-08-17    Printer-friendly version

The ongoing discussion in the pages of Clarion Magazine regarding debugging prompted one reader to point out the following undocumented debugging functions built into Clarion.

NOTE: As these are undocumented functions and come with no promise of support you should not use them in production applications.

Listing 1 shows a small test program which uses the undocumented debugging functions.

Listing 1. An example program which generates an event log.

program

   map
      module('WSLDEBUG')
         PrintDebugHex(USHORT),NAME('WslDebug$PrintHex')
         PrintDebugString(STRING), NAME('WslDebug$Print')
         PrintDebugLine(), NAME('WslDebug$PrintLine')
         PrintDebugEvent(), NAME('WslDebug$PrintEvent')
      end
   end

Window WINDOW('Debug Test'),AT(,,117,40),|
         FONT('MS Sans Serif',8,,,CHARSET:ANSI),GRAY,DOUBLE
       BUTTON('Close'),AT(36,12,45,14),USE(?Close)
     END



   code
   open(window)
   accept
      ! Print the first line of text
      PrintDebugString('Event - Decimal: ' & event() & ', Hex: ')
      PrintDebugHex(event())
      PrintDebugLine()
      ! Print the second line of text
      PrintDebugEvent()
      if accepted() = ?Close
         PrintDebugString('closing window')
         PrintDebugLine()
         post(event:closewindow)
      end
   end

Running this program simply brings up a small window with a Cancel button. Press the cancel button, and when the program terminates a text file called c5log.txt contains the text in Listing 2.

Listing 2. The event log created by the test program.

Event - Decimal: 518, Hex: 206
EVENT:GainFocus           0
Event - Decimal: 515, Hex: 203
EVENT:OpenWindow          0
Event - Decimal: 257, Hex: 101
EVENT:Selected            ?CLOSE         (1)
Event - Decimal: 1, Hex: 1
EVENT:Accepted            ?CLOSE         (1)
closing window
Event - Decimal: 513, Hex: 201
EVENT:CloseWindow         0

I've made the log a bit more complicated than it needs to be just to demonstrate the use of the different functions. PrintDebugString just prints whatever string you give it. PrintDebugHex will translate the passed decimal number to a hex equivalent, useful since Windows equates are usually hex numbers. And PrintDebugLine simply prints a CRLF.

As you can see from Listing 1, you can use these functions to display information about the program's events, but a far easier and more complete solution is to just use the PrintDebugEvent function, which prints the Clarion equate of the current event, the field equate of whichever control received the event (a value of 0 refers to the window), and the field equate number.

These undocumented functions make a useful addition to any Clarion developer's toolkit.

Download the example source file and project.

---

David Harms is an independent software developer and the editor and publisher of Clarion Magazine. He is also co-author with Ross Santos of Developing Clarion for Windows Applications, published by SAMS (1995), and has written or co-written several Java books. David is a member of the American Society of Journalists and Authors (ASJA).

Printer-friendly version

Copyright © 1999-2008 by CoveComm Inc. All Rights Reserved. Reproduction in any form without the express written consent of CoveComm Inc., except as described in the subscription agreement, is prohibited.

Clarion Magazine ISSN 1718-9942