home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / fpdemo.zip / README < prev   
Text File  |  1994-02-23  |  7KB  |  150 lines
  1. ********************
  2. **  Introduction  **
  3. ********************
  4.  
  5. Footprints 1.0 has been in use since early 1992 at petrochemical
  6. refineries in France, Italy, Canada, and here in Houston.  It was
  7. conceived by a group of HSS developers who wanted to avoid the
  8. excessive overhead associated with the frequent file I/O of
  9. conventional tracing techniques.  We were developing an I/O Driver
  10. that was a crucial link between an OS/2 1.3 gateway (to a
  11. mainframe) and a process plant instrumentation system.  The IOD
  12. had to handle thousands of transactions per second for 24 hours
  13. a day, so any delays would significantly hinder performance.  In
  14. addition to the demands imposed by a realtime system, all the I/O
  15. Driver code was developed in the lab using only simulators in place
  16. of the instrumentation system; once installed, the IOD would be
  17. difficult to support without expensive plant visits.
  18.  
  19. So Footprints was developed to enable HSS developers to trace
  20. and debug different sections of code dynamically, without
  21. recompiling to go from debug code to production code and back
  22. again.  We couldn't use a debugger during the development phase
  23. of projects, because other timing dependent code would crash if
  24. we slowed a thread down to a crawl.  And, after we installed the
  25. code, and a user in Europe called us, we were able to tell him to
  26. turn on a specific trace ids from the external Footprints interface
  27. while his process was running, duplicate his problem, and send us
  28. the trace file.  All without slowing, stopping, or restarting his
  29. process.  This made the customer happy, because his productivity
  30. wasn't affected while we were trying to solve a problem, and it
  31. made us happy, because we were able to get an accurate picture
  32. of exactly what code was executed at the plant when the reported
  33. problem occurred.
  34.  
  35. Footprints 2.0 is the commercial release of this product.  While the
  36. internals are the same as those in the original utility, the code has
  37. been migrated to 32-bit and the interface has been upgraded to
  38. Presentation Manager.
  39.  
  40. How It Works
  41. ------------
  42. Footprints consists of a DLL and a PM executable. The DLL
  43. contains four API calls that developers use to implement tracing.
  44. The calls are simple:  there is an Initialize and a Terminate, there
  45. is a Trace, and a Check Trace id routine.  The executable simply
  46. sets any of 64 trace ids, monitors trace activity, and creates
  47. archive files of traced data.
  48.  
  49. Your program will use the DLL to implement tracing.  You first call
  50. our initialization routine, HfpInit; this will set up a 64K buffer in
  51. named shared memory and an output file for your traces, and it will
  52. return a handle to you.  You can then call HfpTrace using the
  53. handle, passing a pointer, a length argument, and eight character
  54. label, and a trace id number.  HfpTrace will check the trace id (a
  55. single bit in shared memory) and return immediately if it is not set.
  56. If it is set, the data to be traced is written to the 64K trace buffer.
  57. This is fast, because during runtime, you can leave the HfpTrace
  58. calls in your code, and it costs you only a few machine instructions
  59. to check the bit and return.   Once you want to actually trace, you
  60. bring up the executable and set the trace bits in which you're
  61. interested.
  62.  
  63. There are 64 optional trace bits that you can use.  Which ones you
  64. use is up to you.  If you have a very large complex program, you
  65. may want to use a different trace bit for each task in the program;
  66. bit 1 can trace file I/O and bit 2 your RS-232 connection, for
  67. example.  If you wish to use the trace facility for an error log, you
  68. can pass zero as the trace id, and the data passed to HfpTrace will
  69. always be captured.  Or, if you do not want to rely simply on the           
  70. hex and ASCII character dump that HfpTrace generates, you can
  71. use the HfpIsItOn function.  This can be used anywhere you
  72. normally use the #ifdef DEBUG or #ifdef SIMULATOR
  73. preprocessor directives.  So, instead of defining debug or simulator
  74. situations and recompiling to test code, you can use HfpIsItOn to
  75. check a trace bit that you can set externally while your program is
  76. running.  If the bit is on, you can write out information to a file in
  77. debugging situations, or call simulation stubs if you are in
  78. simulation mode.  When you get to production mode, you do not
  79. have to change your code or recompile; you simply leave the trace
  80. bit turned off.
  81.  
  82. Operating Environment
  83. ---------------------
  84. Footprints currently works with OS/2 version 2.0 and up.  It
  85. supports both 16-bit and 32-bit compilers.  
  86.  
  87. This Demo Package
  88. -----------------
  89. This demo does not contain the DLL that the above documentation
  90. mentions (otherwise, you would have nearly the whole product!).
  91. the two demonstration programs, mtfp.exe and fpdemo.exe illustrate
  92. how one would use Footprints to trace different sections of code
  93. dynamically.  MTFP.EXE (see MTFP.C) illustrates using different
  94. trace bits to trace and identify different threads that are
  95. executing simultaneously.  FPDEMO.C shows Footprints in a PM
  96. environment, while taking a user through the steps involved with
  97. setting and monitoring traces.
  98.  
  99. Instructions
  100. ------------
  101. All you have to do is designate a directory as your FOOTPATH.  This 
  102. is where all Footprints trace files and trace bit options files
  103. reside.  In your CONFIG.SYS, add the line
  104.       SET FOOTPATH=c:\traces
  105. where you put the directory path in place of c:\traces above.
  106. You must then reboot.  Now, try running FP.EXE, and going through
  107. FPDEMO.EXE.  Look at the code (FPDEMO.C).  If you think you have
  108. a grasp of it, check our MTFP.EXE and MTFP.C.  Run MTFP, and turn on
  109. and off different trace bits, and look at the monitor window.  When
  110. you are done, create a history file.  Or, create a history file 
  111. while MTFP.EXE is running.
  112.  
  113. ========================
  114. === Happy debugging! ===
  115. ========================
  116.            
  117. Ordering
  118. --------
  119. If you would like to  order Footprints, give us a call at (713) 
  120. 871-1448 during regular business hours, or fax an order to us
  121. at (713) 871-1449.  Be sure to have MC/Visa/Discover credit
  122. card number and expiration date ready.  The price is $59 +
  123. $5.95 for shipping anywhere in the United States.  Add $1
  124. for shipping to Canada, and $2 for shipping overseas.
  125.  
  126. You may also Email us at 76636,662 on Compuserve, or
  127. usib5srq@ibmmail.com via Internet.  We would love to answer
  128. any questions you may have.
  129.  
  130. By the Way
  131. ----------
  132. By the way, Footprints is a trademark of Hardy Software
  133. Systems, Inc.  
  134.  
  135. License Agreement
  136. -----------------
  137. This program product is the property of Hardy Software
  138. Systems, Inc., and is licensed for your use as a demonstration.
  139. You may distribute this demo all you want in its zipped format.  
  140. Just don't try to disassemble it or recreate the DLL.
  141. You may not distribute FP.EXE to users who have the Footprints
  142. DLL, which is distributed by licensed users of Footprints.
  143. If you have FP.EXE and the Footprint DLL, you owe us
  144. fifty nine bucks.
  145.  
  146. If you disagree with this license agreement, or are unable
  147. to abide by it, destroy all copies of Footprints code in your
  148. possession.
  149.  
  150.