home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / WATCH2.ZIP / WATCH.IPF < prev    next >
Text File  |  1990-08-16  |  13KB  |  411 lines
  1. :userdoc.
  2. :title.Help for Watch/2 Debugging Aid
  3. :body.
  4. .*
  5. .*
  6. :h1 res=001.Watch/2 Extended Help
  7. :p.
  8. The :hp2.Watch/2 Debugging Aid:ehp2. is designed to assist the
  9. Presentation Manager Applications developer by providing a 
  10. a means for displaying debugging information within the PM environment.
  11. This utility is meant to be used as the developers sole debugging
  12. aid. Rather is is designed to be used in conjunction with other
  13. commercially available debugging aids.
  14. :p.
  15. For information on setting up a client application to use the :hp2.Watch/2
  16. Debugging Aid:ehp2., Select the "
  17. :link reftype=hd res=041.Installing in Clients:elink." option from the
  18. :hp2.F1=Help:ehp2. pull-down menu.
  19. .*
  20. .*
  21. :h1 res=005.Help for Options
  22. :p.
  23. Choose the :hp2.Options:ehp2. pull-down menu to show and allow selection of the
  24. available options for the Watch/2 Debugging Aid.  Those Options Include...
  25. :parml.
  26. :pt.:link reftype=hd res=006.Clear:elink. Message Area
  27. :pd.Select this option to Clear the main message logging area of all
  28. currently displayed messages.
  29. :pt.:link reftype=hd res=007.Open:elink. 
  30. /:link reftype=hd res=007.Close:elink. Log File
  31. :pd.Select this option to either :hp2.Open:ehp2. a log file and begin
  32. logging messages to that file or to :hp2.Close:ehp2. the log file and 
  33. to terminate logging messages to the file.  This options depends on the 
  34. state of the menu item.
  35. :pt.:link reftype=hd res=015.Truncate:elink. File
  36. :pd.Select this menu item if you wish to clear all messages which have
  37. been logged to an open message logging file.
  38. .*
  39. .*
  40. :h2 res=006.Help for Clear Message Area
  41. :p.
  42. Select the :hp2.Clear Message Area:ehp2. to clear all messages displayed in the
  43. primary debugging window.  Once cleared, the window should display a 
  44. single message which reads "Beginning of Log...". The 
  45. :hp2.Clear Message Area:ehp2. can also be selected by pressing the
  46. :link reftype=hd res=024.Del:elink. key.
  47. :p.
  48. :hp2.Note...:ehp2. Clearing the message area does not clear
  49. any messages logged to a message logging file.  Clearing
  50. of a file is accomplished through
  51. the use of the
  52. :link reftype=hd res=015.Truncate File:elink.
  53. facility.
  54. .*
  55. .*
  56. :h2 res=007.Log Messages to File
  57. :p.
  58. This menu item has two states, :hp2.Open Log File...:ehp2. and :hp2.Close
  59. Log File:ehp2.. When the menu item reads "Open Log File...", no logging
  60. is presently being piped to a file.  Choosing this selection sets up a 
  61. dialog box requesting the user to enter a file specification which can be
  62. used to open a file and begin directing all log messages to both the main
  63. logging window as well as to a file.
  64. :p.
  65. When the menu item reads "Close Log File", a message logging file is 
  66. currently open and accepting log messages.  Choosing this selection closes
  67. the file and from that point all messages are only logged to the main 
  68. logging window.
  69. :p.
  70. Regardless of the state of this menu item, it can be selected by pressing
  71. the :link reftype=hd res=024.Ctrl+L:elink. keys simultaneously.
  72. .*
  73. .*
  74. :h3 res=10.Log File Name
  75. :p.
  76. Enter the full drive, path, and file specification of the file to which
  77. message logging is to be written.
  78. :p.
  79. :hp2.Note...:ehp2. If the High Performance File System is loaded, this
  80. file specification can be up to 254 bytes in length, adhering to the
  81. standard HPFS file specification definition.
  82. .*
  83. .*
  84. :h3 res=11.Log File Ok/Cancel Buttons
  85. :p.
  86. Choose the :hp2.OK:ehp2. button to accept the file name displayed in the Log File
  87. Specification, or choose the :hp2.Cancel:ehp2. button to return without opening the 
  88. message logging file.
  89. .*
  90. .*
  91. :h2 res=015.Truncate File
  92. :p.
  93. This :hp2.Truncate File:ehp2. option is only selectable
  94. when a message logging file is open.  When
  95. selectable, this option clears all messages previously logged to the 
  96. file and resets the file to an empty state and ready to receive all new
  97. messages. The :hp2.Truncate File:ehp2. option can also be selected
  98. by pressing the
  99. :link reftype=hd res=024.Ctrl+T:elink. keys simultaneously.
  100. :p.
  101. :hp2.Note...:ehp2. Truncating the message logging file does
  102. not clear any messages logged to the main Watch/2 debugging window.
  103. to clear messages from the main window, use the
  104. :link reftype=hd res=006.Clear Message Area:elink.
  105. facility
  106. .*
  107. .*
  108. :h1 res=17.Exit Watch/2 Debugging Aid
  109. :p.
  110. Choosing the :hp2.Exit:ehp2. main menu item initiates a pull-down menu
  111. requesting the user to choose either
  112. :link reftype=hd res=018.Exit:elink. or
  113. :link reftype=hd res=019.Resume:elink.
  114. :p.
  115. This acts as final confirmation that the user really wishes to
  116. :hp2.Exit:ehp2. the Watch/2 Debugging Aid, and if not, gives the user
  117. the opportunity to continue normal operations of the utility.
  118. .*
  119. .*
  120. :h2 res=018.Exit the Watch/2 Debugging Aid
  121. :p.
  122. Choose this option to close any open message logging file and accomplish
  123. a controlled shutdown. The :hp2.Exit:ehp2. can also be initiated
  124. by pressing the
  125. :link reftype=hd res=024.F3:elink. key.
  126. :p.
  127. :hp2.Note...:ehp2. If any client applications are attached at the time
  128. this option is selected, the Watch/2 Debugging Aid will not allow
  129. shutdown until all client applications have first been shut down.
  130. .*
  131. .*
  132. :h2 res=019.Resume the Watch/2 Debugging Aid
  133. :p.
  134. Should :hp2.Exit:ehp2. be choosen by mistake from the main panel menu,
  135. chooing the :hp2.Resume:ehp2. option merely places the user back to the
  136. main panel as if Exit had never been selected.
  137. .*
  138. .*
  139. :h1 res=020.Help for F1=Help
  140. :p.
  141. Selecting the main :hp2.F1=Help:ehp2. menu item displays the the
  142. :hp2.Help:ehp2 pull-down menu for selection of the various help options.
  143. :p.
  144. Pressing the :link reftype=hd res=024.F1:elink. key from any
  145. point in the menu structures presents :hp2.help:ehp2.
  146. for the specific menu or submenu item.  Pressing the
  147. :link reftype=hd res=024.F1:elink. key from 
  148. within any dialog presents the :hp2.help:ehp2. for the specific field
  149. or push-button which is currently highlighted.
  150. .*
  151. .*
  152. :h2 res=021.Help for Help
  153. :p.
  154. Select :hp2.Help for Help:ehp2. on the :hp2.Help:ehp2. pull-down menu
  155. for information on how to use the :hp2.Help:ehp2. facilities associated
  156. with the Watch/2 Debugging Aid. 
  157. .*
  158. .*
  159. :h2 res=022.Extended Help
  160. :p.
  161. Select :hp2.Extended Help:ehp2. on the :hp2.Help:ehp2. pull-down menu
  162. to see the extended help panel for the Watch/2 Debugging Aid.
  163. .*
  164. .*
  165. :h2 res=023.Keys Help
  166. :p.
  167. Select :hp2.Keys Help:ehp2. on the :hp2.Help:ehp2. pull-down menu to
  168. see a list of the available accelerator keys associated with the 
  169. Watch/2 Debugging Aid.
  170. .*
  171. .*
  172. :h2 res=024.Accelerator Keys
  173. :p.
  174. The following is a list of the available accelerator keys associated with
  175. the Watch/2 Debugging Aid software...
  176. :parml.
  177. :pt.F1
  178. :pd.Get Help
  179. :pt.F2
  180. :pd.View the Extended Help for the Watch/2 Debugging Aid from
  181. within any help window.
  182. :pt.F3
  183. :pd.Initiates the 
  184. :link reftype=hd res=018.Exit:elink.
  185. task to shut down the Watch/2 Debugging Aid.
  186. :pt.Del
  187. :pd.Initiates the task to accomplish the
  188. :link reftype=hd res=006.Clear Message Area:elink.
  189. associated with the main message logging window.
  190. :pt.Ctrl+L
  191. :pd.Selects either the :link reftype=hd res=007.Open:elink.
  192. or :link reftype=hd res=007.Close:elink. operation associated with
  193. a message logging file depending on the state of the menu item.
  194. :pt.Ctrl+T
  195. :pd.:link reftype=hd res=015.Truncate:elink.
  196. all messages from the currently open logging file.
  197. :eparml.
  198. .*
  199. .*
  200. :h2 res=025.Help Index
  201. :p.
  202. Select :hp2.Help Index:ehp2. on the :hp2.Help:ehp2. pull-down menu to
  203. see the :hp2.Index:ehp2. of all help available for the Watch/2 Debugging
  204. Aid Utility.
  205. .*
  206. .*
  207. :h2 res=026.Help for About Watch/2 Debugging Aid
  208. :p.
  209. Select :hp2.About:ehp2. from the :hp2.Help:ehp2. pull-down menu to
  210. view the :hp2.Version.Release:ehp2., :hp2.Author:ehp2., and 
  211. :hp2.Copyright:ehp2. Information for the Watch/2 Debugging Aid.
  212. .*
  213. .*
  214. :h2 res=034.About Watch
  215. :p.
  216. The idea behind the :hp2.Watch/2 Debugging Aid:ehp2. was
  217. originally presented in the January 1990 issue of MicroSoft
  218. Journal along with a program entitled TRACER, authored
  219. by Daniel Hildebrand. 
  220. :p.
  221. While :hp2.Watch/2:ehp2. is generally built around the same concepts
  222. and ideas, it has been entirely re-engineered and enhanced to include
  223. features such as a full implementation of the IPF help
  224. capabilities.
  225. :p.
  226. This software is offered as a shared tool only.  You are free to copy and
  227. use for software development and debugging purposes, providing...
  228. :p.
  229. 1. NO FEE IS CHARGED FOR USE, COPYING, OR DISTRIBUTION; and
  230. :p.
  231. 2. IS NOT MODIFIED IN ANY WAY FROM THE ORIGINAL.
  232. :p.
  233. There exists NO warranties, either expressed or implied, as to
  234. the merchantability, fitness for purpose, or functionality of this
  235. software.
  236. .*
  237. .*
  238. :h2 res=040.Installation in Client Applications
  239. :p.
  240. Select :hp2.Installing in Clients:ehp2. from the :hp2.Help:ehp2. pull-down
  241. menu to view instructions for installing the appropriate software hooks 
  242. and includes into the client application which will allow the application 
  243. to have use of the Watch/2 Debugging Aid.
  244. .*
  245. .*
  246. :h2 res=041.Installation in Client Applications
  247. :p.
  248. In order to install the appropriate hooks to the Watch/2 Debugging Aid into
  249. a client application, the following steps should be taken...
  250. :p.
  251. :hp8.Step 1:ehp8. - Include the :hp2.watch.h:ehp2.
  252. header file in the beginning
  253. of you c program source file to obtain the appropriate definitions for 
  254. messages, variables, and necessary code. See
  255. :link reftype=hd res=042.Example:elink. #1.
  256. :p.
  257. :hp8.Step 2:ehp8. - Add the :hp2.WATCHVARIABLES:ehp2. macro above the 
  258. main() function.  This defines the necessary external variables necessary
  259. for attaching and communicating with the :hp2.Watch/2 Debugging Aid:ehp2.
  260. See :link reftype=hd res=043.Example:elink. #2.
  261. :p.
  262. :hp2.Note...:ehp2. The :hp2.WATCHVARIABLES:ehp2. macro may need to be added into
  263. secondary source files if secondary modules use the Watch/2 facilities.
  264. :p.
  265. :hp8.Step 3:ehp8. - Add the :hp2.WATCHHELLO:ehp2. macro within the
  266. :hp2.WM_CREATE:ehp2. message handling statement for the main message window
  267. processing procedure.  This broadcasts a message to all applications to
  268. see if Tracer is already running and if so an attachment can me made
  269. immediately. See
  270. :link reftype=hd res=044.Example:elink. #3.
  271. :p.
  272. :hp8.Step 4:ehp8. - Add tje :hp2.WATCHATTACH:ehp2. macro as a separate
  273. message entry in the first level :hp2.case:ehp2. statement within the
  274. main window processing procedure. This establishes the initial
  275. communications facility for utilizing the Watch/2 Debugging Aid. See
  276. :link reftype=hd res=045.Example:elink. #4.  
  277. :p.
  278. :hp8.Step 5:ehp8. - Use the :hp2.WATCHPOST(string):ehp2. macro freely
  279. throughout the client application.  This macro provides the facility to
  280. send the user defined text as a message to the :hp2.Watch/2 Debugging
  281. Aid:ehp2.. See
  282. :link reftype=hd res=046.Example:elink. #5.
  283. .*
  284. .*
  285. :h3 res=042.Example #1 - Include Header Files
  286. :xmp.
  287. // SET UP DEFINES FOR SELECTIVE INCLUSION FROM OS2.H
  288. #define INCL_PM
  289. #define INCL_WIN
  290. #define INCL_DOS
  291.  
  292. // APPLICATIONS INCLUDES OF APPROPRIATE HEADER FILES
  293. #include <os2.h>
  294. #include <stdio.h>
  295. #include <string.h>
  296. #include <stdlib.h>
  297. #include <process.h>
  298. :hp2.#include <watch.h>:ehp2.
  299. #include "appl.h"
  300. &bullet.
  301. &bullet.
  302. &bullet.
  303. :exmp.
  304. .*
  305. .*
  306. :h3 res=043.Example #2 - WATCHVARIABLES Macro
  307. :xmp.
  308. // DEFINE GLOBAL VARIABLES...
  309. HMQ    hmq;
  310. HWND   hwndClient;
  311. HWND   hwndFrame;
  312.  
  313. :hp2.WATCHVARIABLES:ehp2.
  314.  
  315. VOID cdecl main()
  316. {
  317. &bullet.
  318. &bullet.
  319. &bullet.
  320. }
  321. :exmp.
  322. .*
  323. .*
  324. :h3 res=044.Example #3 - WATCHHELLO Macro
  325. :xmp.
  326. // MAIN WINDOW PROCESSING PROCEDURE...
  327. MRESULT EXPENTRY MainWindowProc(HWND hwnd, USHORT msg,
  328.                                 MPARAM mp1, MPARAM mp2)
  329. {
  330.   // DEFINE LOCALIZED VARIABLES...
  331.   HPS   hps;
  332.   RECTL rc;
  333.  
  334.   // HANDLE MESSAGES TO MAIN WINDOW...
  335.   switch(msg)
  336.   {
  337.     case WM_CREATE:
  338.          &bullet.
  339.          :hp2.WATCHHELLO:ehp2.
  340.          &bullet.
  341.          break;
  342.     case WM_COMMAND:
  343.          &bullet.
  344.          &bullet.
  345.          &bullet.
  346.     default:
  347.       return WinDefWindowProc(hwnd, msg, mp1, mp2);
  348.   }
  349.   return FALSE;
  350. }
  351. :exmp.
  352. .*
  353. .*
  354. :h3 res=045.Example #4 - WATCHATTACH Macro
  355. :xmp.
  356. // MAIN WINDOW PROCESSING PROCEDURE...
  357. MRESULT EXPENTRY MainWindowProc(HWND hwnd, USHORT msg,
  358.                                 MPARAM mp1, MPARAM mp2)
  359. {
  360.   // DEFINE LOCALIZED VARIABLES...
  361.   HPS   hps;
  362.   RECTL rc;
  363.  
  364.   // HANDLE MESSAGES TO MAIN WINDOW...
  365.   switch(msg)
  366.   {
  367.     case WM_CREATE:
  368.          &bullet.
  369.          WATCHHELLO
  370.          &bullet.
  371.          break;
  372.     case WM_COMMAND:
  373.          &bullet.
  374.          &bullet.
  375.          &bullet.
  376.     :hp2.WATCHATTACH:ehp2.
  377.     default:
  378.       return WinDefWindowProc(hwnd, msg, mp1, mp2);
  379.   }
  380.   return FALSE;
  381. }
  382. :exmp.
  383. .*
  384. .*
  385. :h3 res=046.Example #5 - WATCHPOST(string) Macro
  386. :xmp.
  387. VOID UserFunction(HWND hwnd)
  388. {
  389.   // INITIALIZATION PROCESSING...
  390.   &bullet.
  391.   &bullet.
  392.   &bullet.
  393.  
  394.   // SET UP DIALOG AND PASS CONTROL TO THE DIALOG PROCEDURE...
  395.   :hp2.WATCHPOST("Displaying the User Dialog Box!");:ehp2.
  396.   WinDlgBox(HWND_DESKTOP,
  397.             hwnd,
  398.             UserDlgProc,
  399.             NULL,
  400.             ID_DIALOG,
  401.             NULL);
  402.   :hp2.WATCHPOST("Returned from Dialog Box Processing!");:ehp2.
  403.   &bullet.
  404.   &bullet.
  405.   &bullet.
  406. }
  407. :exmp.
  408. .*
  409. .*
  410. :euserdoc.
  411.