home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / rwx10.zip / RWX.DOC < prev   
Text File  |  1998-01-22  |  20KB  |  540 lines
  1. ____________________________________________________________________
  2. ____________________________________________________________________
  3.  
  4.  
  5. ====  Rwx v1.0 - a SOM Class Explorer  ====
  6.  
  7. (C) Copyright R L Walsh 1994, 1997 - All Rights Reserved
  8.  
  9. ____________________________________________________________________
  10. ____________________________________________________________________
  11.  
  12.     TABLE OF CONTENTS
  13. ____________________________________________________________________
  14.  
  15.  
  16.     o   Introduction
  17.     o   Using Rwx
  18.     o   Menus
  19.     o   Class List Window
  20.     o   Class Info Window
  21.     o   Install/Remove
  22.     o   License Agreement
  23.  
  24. ____________________________________________________________________
  25. ____________________________________________________________________
  26.  
  27.     INTRODUCTION
  28. ____________________________________________________________________
  29.  
  30.  
  31. Rwx v1.0 is a tool for examining System Object Model (SOM) classes
  32. loaded by the OS/2 Workplace Shell.  It is implemented as a WPS
  33. class that can be used with all versions of OS/2 Warp v3 and v4.
  34.  
  35. Rwx can list all SOM classes in the WPS process and provide
  36. detailed information about each, including a complete listing of
  37. its methods.  Use Rwx to better understand how a class works and
  38. its relationship to other classes, and to identify undocumented
  39. methods and classes.  You can even use Rwx to create skeleton IDL
  40. files for undocumented classes, enabling you to subclass them.
  41.  
  42. Rwx v1.0 is released as freeware.  You may copy and redistribute
  43. it, provided there is no charge to the end user except the costs
  44. of media and distribution.  It may not be included in "commercial"
  45. packages without permission.
  46.  
  47. Email your comments, questions, and suggestions to the author,
  48. Rich Walsh, at <rlwalsh@packet.net>.
  49.  
  50. ____________________________________________________________________
  51. ____________________________________________________________________
  52.  
  53.     USING RWX
  54. ____________________________________________________________________
  55.  
  56.  
  57. Modify, then run the REXX script in the "Install/Remove" section
  58. below to register class "Rwx" and create an Rwx object on your
  59. Desktop.  Open it to display its Class Explorer view.
  60.  
  61.  
  62. Class Explorer Window
  63. ---------------------
  64.  
  65. There are two main parts, the Class List and Class Info windows,
  66. plus navigation buttons, an icon area used for drag and drop,
  67. and a menu.
  68.  
  69. Class List: a drop-down listing of all SOM classes currently
  70.             loaded in the WPS process, plus WPS classes that are
  71.             registered but not loaded.  Options let you choose
  72.             the sort order and the classes included in the list.
  73.  
  74. Class Info: a scrollable text window that displays details for a
  75.             selected class.  It identifies a class's module and
  76.             load cause; its ancestry and the number of methods
  77.             introduced by each ancestor;  and, WPS-specific
  78.             details such as default view, style bits, etc.  By
  79.             default, Rwx lists every method a class introduces
  80.             or overrides.  You can choose to turn off the list,
  81.             or to expand it to include every inherited method.
  82.  
  83. Buttons:    selection and navigation buttons for use with the
  84.             mouse or keyboard.  The left arrow selects (or
  85.             reselects) a class from the list.  The up and down
  86.             arrows select the previous or next class on the list.
  87.  
  88. Icon area:  displays Rwx's icon at startup, and the default class
  89.             icon when a WPS class is selected.  Drop a WPS object
  90.             here to display info about its class.
  91.  
  92. Menu:       contains commands to refresh the Class List, lookup
  93.             a class or method name, etc, plus items for setting
  94.             defaults.
  95.  
  96.  
  97. API Help
  98. --------
  99. If you have the WPS and/or SOM online references from the OS/2
  100. Developer's Toolkit, you can use API Help to look up classes
  101. and methods.
  102.  
  103. Place the cursor on the word to look up, then press Ctrl-A
  104. or select 'Help/API help' from the menu.  To look up a phrase
  105. or part of a word, highlight the text first.
  106.  
  107. By default Rwx uses this command line to invoke online help:
  108.     VIEW WPS1.INF+WPS2.INF+WPS3.INF+SOMREF.INF [topic]
  109.  
  110. You can change the .INF files it uses by setting an RWXREF
  111. environment variable.  For example:
  112.     SET RWXREF=WPS1.INF+WPS2.INF+SOMREF.INF+SOMGUIDE.INF
  113.  
  114.  
  115. Drag and Drop
  116. -------------
  117. Drop a WPS object on the icon area (to the left of the Class
  118. List) to display details about its class.  Rwx will identify
  119. the object's class, then try to find its name in the Class List.
  120. This will fail if you've excluded WPS classes from the list.
  121. Set 'Options/Filter' to 'Show all', refresh the list, then try
  122. again.
  123.  
  124.  
  125. Copying Information
  126. -------------------
  127. You can use DragText or the clipboard to copy details from the
  128. Class Info window.  To copy the Class List, select 'Classes/
  129. Copy list' from the menu.  This will copy the Class List in
  130. its current format to the Class Info window.  You can then copy
  131. selected text from there.
  132.  
  133.  
  134. Fonts and Colors
  135. ----------------
  136. Rwx saves the colors and font used by the Class Info window.
  137. When you reopen Rwx, these colors and fonts will be applied
  138. to both the Class List and the Class Info windows.
  139.  
  140. ____________________________________________________________________
  141. ____________________________________________________________________
  142.  
  143.     MENUS
  144. ____________________________________________________________________
  145.  
  146.  
  147. Classes
  148. =======
  149.  
  150. Refresh list:
  151. [Ctrl-R]    updates the list of loaded and registered classes.
  152.             Use this after changing Rwx's class listing options,
  153.             or to see if SOM has loaded or unloaded any classes
  154.             since the last refresh.
  155.  
  156. Copy list:  copies the current Class List to the Class Info window;
  157. [Ctrl-C]    the list is not updated.  This lets you copy part or
  158.             all of the it using DragText or the clipboard.
  159.  
  160. Load now:   if the "Load on Request" option is set, you must
  161. [Ctrl-L]    select this item to view details for classes that
  162.             are not loaded currently.
  163.  
  164.  
  165. Options
  166. =======
  167.  
  168. The Sort, Filter, and Load options take effect when you select
  169. 'Classes/Refresh'.  The Methods options take effect when you
  170. select or reselect a class from the list.  The Word wrap option
  171. takes effect immediately.
  172.  
  173.  
  174. Sort
  175. ----
  176. by Parent:  creates an indented hierarchical listing (default)
  177.  
  178. Alphabetically:
  179.             creates a left-justified listing of classes sorted
  180.             by name
  181.  
  182. None:       classes are listed in the order SOM stores them
  183.             in its class table;  this can help identify the
  184.             order in which classes were loaded.
  185.  
  186. Filter
  187. ------
  188. Show all:   every class currently loaded, plus WPS classes that
  189.             are registered but not loaded will be listed (default)
  190.  
  191. WPS only:   only classes descended from WPObject are included
  192.  
  193. Exclude WPS:
  194.             classes descended from WPObject will not be listed.
  195.  
  196. Load
  197. ----
  198. This controls whether and when Rwx loads classes not currently
  199. in memory.
  200.  
  201. at Startup: all registered WPS classes will be loaded whenever
  202.             you open Rwx or refresh the class list;  classes
  203.             that SOM unloads will be reloaded when selected
  204.  
  205. to View Details:
  206.             a class will be loaded, if necessary, when you select
  207.             it from the class listing (default)
  208.  
  209. on Request: Rwx will advise if a class is not loaded currently;
  210.             you must then select 'Classes/Load now' from the menu.
  211.  
  212. Methods
  213. -------
  214. Detailed:   every new and inherited method available to the class
  215.             is listed;  classes which have overridden a given
  216.             method are identified
  217.  
  218. Concise:    every method that is introduced or overridden by the
  219.             class is listed (default)
  220.  
  221. None:       no method listing is generated.
  222.  
  223.  
  224. Word wrap:  
  225. ---------   toggles word wrap in the Class Info window;  this
  226. [Ctrl-W]    is the only option that takes effect immediately.
  227.  
  228.  
  229. Help
  230. ====
  231.  
  232. API help:   Select this item to display online help for the
  233. [Ctrl-A]    classes and methods shown in the Class Info window.
  234.             Rwx will lookup whatever text is selected;  if nothing
  235.             is selected, Rwx will select the word at the cursor,
  236.             then look it up.  You must have the online SOM and WPS
  237.             references from the OS/2 Developers Toolkit.
  238.  
  239. Product Info:
  240.             author, version, and copyright information
  241.  
  242. ____________________________________________________________________
  243. ____________________________________________________________________
  244.  
  245.     CLASS LIST WINDOW
  246. ____________________________________________________________________
  247.  
  248.  
  249. By default, the Class List displays an indented, hierarchical
  250. listing of every SOM class currently loaded in the Workplace
  251. Shell process, plus additional WPS classes that are registered
  252. but not loaded (see note below).  Menu options let you sort the
  253. list alphabetically or by load order, and exclude either WPS or
  254. non-WPS classes.
  255.  
  256. Navigate the list by selecting a class directly or by using
  257. the buttons next to it.  The up and down arrows step through
  258. the list;  the left arrow displays (or redisplays) details for
  259. the selected class.
  260.  
  261. Because SOM dynamically loads and unloads classes, the contents
  262. of the Class List may change over time.  Use the 'Classes/Refresh'
  263. menu option to update the list.
  264.  
  265. Use the 'Options/Load' menu to control whether and when Rwx should
  266. have SOM load a class that isn't currently in memory.  The default
  267. action ('to View Details') is to load a class when you select it
  268. from the list.  The "Menus" section describes the other options.
  269.  
  270. Note:  The class list does not include WPObject's metaclass
  271. (M_WPObject) or any of its descendants.  Details about these
  272. classes are displayed when you select the associated instance
  273. class.
  274.  
  275. ____________________________________________________________________
  276. ____________________________________________________________________
  277.  
  278.     CLASS INFO WINDOW
  279. ____________________________________________________________________
  280.  
  281.  
  282. Standard Information
  283. ====================
  284.  
  285. Items which may not appear for every class are surrounded by
  286. parentheses.
  287.  
  288. Class:      The name of this object class, as known to SOM.  The
  289.             address of the class object appears to the right.
  290.  
  291. Metaclass:  The class that constructs objects for the subject
  292.             class.  It is always descended from SOMClass.  The
  293.             address of the metaclass object appears to the right.
  294.  
  295. Parent:     The class(es) from which the subject class was
  296.             derived.  If the subject class has multiple parents,
  297.             each will be listed.  The address of the parent
  298.             class object appears to the right.
  299.  
  300. (Replaces:)  (only shown if a replacement is in effect)
  301.             Whenever SOM is asked to create an object of the class
  302.             shown here, it will create an object of the subject
  303.             class instead.  This class is normally the subject's
  304.             parent;  it may be different if multiple subclasses
  305.             are replacing the same parent.
  306.  
  307. Module:     The fully qualified path of the DLL containing this
  308.             class.  If the DLL name SOM supplies isn't valid,
  309.             the means Rwx used to identify the module is also
  310.             shown in parentheses:
  311.              - (method addr):  Rwx used the address of a method
  312.                the class introduced or overrode.
  313.              - (related class):  Rwx assumed that the class is
  314.                in the same file as the class that caused it to
  315.                be loaded (this may be incorrect).
  316.             If all else fails,"unknown" is displayed.
  317.  
  318. Load cause: An attempt to identify why this class was loaded;
  319.             consider this an "educated guess".  You may see "WPS
  320.             registration", the name of another class, or "unknown".
  321.             If a class is shown, it may be followed by:
  322.              - (SOMInitModule):  a request to load the class
  323.                shown here probably caused SOM to invoke the DLL's
  324.                SOMInitModule which then loaded the subject class.
  325.              - (descendant):  the class shown here is a descendant
  326.                of the subject class;  to construct a class, SOM
  327.                has to load all ancestor classes.
  328.  
  329. ____________________________________________________________________
  330.  
  331.  
  332. WPS-Specific Information
  333. ========================
  334.  
  335. This section appears for classes descended from WPObject.  The
  336. WPS creates additional classes not descended from WPObject, but
  337. they are not considered "WPS classes" here.
  338.  
  339. Registered / Unregistered WPS class:
  340.             WPS registration facilitates loading classes when
  341.             objects are created or awakened, but it is not
  342.             required.  There are several other mechanisms that
  343.             can cause a class to be loaded.
  344.  
  345. Title:      The default name given to objects of this class.
  346.  
  347. Storage class:
  348.             The ancestor class that handles the storage of an
  349.             object's persistent data.  WPFileSystem objects use
  350.             files and folders;  WPAbstract objects use os2.ini.
  351.             WPTransient objects don't store their data and must
  352.             be recreated each time the system starts.
  353.  
  354. Default view:
  355.             If a specific view has not been set for an object of
  356.             this class, this view will be opened by default.
  357.  
  358. Class Style:
  359.             The default style bits given to objects of this class.
  360.  
  361. (PM_Workplace:IplLoad:)  (WPFileSystem and descendents only)
  362.             The "PM_Workplace:IplLoad" entry in os2.ini identifies
  363.             classes that the WPS should load at startup and keep
  364.             in memory, rather than loading and unloading them
  365.             on demand.  They are usually descendants of WPDataFile
  366.             associated with particular types of files.
  367.  
  368. (File Associations:)  (WPFileSystem and descendents only)
  369.             The WPS uses this info to assign filesystem objects
  370.             to a class when they have no .CLASSINFO extended
  371.             attribute. They are assumed to be instances of the
  372.             subject class If either their names or .TYPE
  373.             extended attributes match the value(s) shown here.
  374.  
  375. ____________________________________________________________________
  376.  
  377.  
  378. Instance Method & Data Summary
  379. Class Method & Data Summary
  380. ==============================
  381.  
  382. These provide a complete listing of:
  383.  -  a class's ancestors
  384.  -  the count of methods introduced by each class
  385.  -  the size of instance data introduced by each class
  386.  
  387. The total line shows the count of methods available to instances of
  388. the subject class, and the size of the storage required for each
  389. instance of this class.  (FYI...  The total data size is always
  390. 4 bytes larger than the sum of the classes' data size.)
  391.  
  392. ____________________________________________________________________
  393.  
  394.  
  395. Method Listings
  396. ===============
  397.  
  398. This section's contents are controlled by the 'Options/Methods'
  399. menu.
  400.  
  401.  -  None:       this section will not appear;
  402.  -  Concise:    all methods introduced or overridden by this class
  403.                 and its metaclass are listed;
  404.  -  Detailed:   every method available to a class and its metaclass
  405.                 is listed;  each class that has overridden an
  406.                 inherited method is identified.
  407.  
  408. Listings for the class and metaclass follow the same format.
  409. Methods are grouped by the class that introduced them, starting
  410. with the subject class and working back to SOMObject.  The concise
  411. listing includes only ancestors whose methods have been overridden
  412. by the subject class.  The detailed listing includes all ancestors.
  413.  
  414. For each method, Rwx displays:  its index in the class's method
  415. table, its name, and its current entry point on your system.
  416. On the detailed listing, classes that have overridden this method
  417. appear to the right of the entry point.  If the subject class
  418. overrode this method, an asterisk also appears next to the index.
  419.  
  420. ____________________________________________________________________
  421. ____________________________________________________________________
  422.  
  423.     INSTALL/REMOVE
  424. ____________________________________________________________________
  425.  
  426.  
  427. Install
  428. =======
  429.  
  430. To install Rwx, copy this REXX script to a text editor.  Change
  431. the value of RWXPATH, save it as RWXIN.CMD, then run it.  It will
  432. register the class and create an object named Rwx on your Desktop.
  433.  
  434.  
  435. --------------------------------------------------------------------
  436. /* RWXIN.CMD - install Rwx */
  437.  
  438. call RxFuncAdd 'SysLoadFuncs', 'RexxUtil', 'SysLoadFuncs'
  439. call SysLoadFuncs
  440.  
  441. RWXPATH = 'c:\path\RWX.DLL'
  442.  
  443. if SysRegisterObjectClass( 'Rwx', RWXPATH)
  444. then do
  445.     if SysCreateObject( 'Rwx', 'Rwx', '<WP_DESKTOP>', 'OBJECTID=<Rwx>', 'R')
  446.     then
  447.         say 'Rwx has been registered and an Rwx object created'
  448.     else
  449.         say 'Unable to create Rwx object - Rwx class is registered'
  450. end
  451. else do
  452.     say 'Unable to register class Rwx!  Make sure the path is correct.'
  453.     say 'It is currently set to: ' RWXPATH
  454.     rc = SysDeregisterObjectClass( 'Rwx')
  455. end
  456. --------------------------------------------------------------------
  457.  
  458.  
  459. Remove
  460. ======
  461.  
  462. To remove Rwx, copy this REXX script to a text editor, save it as
  463. RWXOUT.CMD, then run it.  It will delete the object RWXIN created,
  464. then it will deregister Rwx.
  465.  
  466.  
  467. --------------------------------------------------------------------
  468. /* RWXOUT.CMD - remove Rwx */
  469.  
  470. call RxFuncAdd 'SysLoadFuncs', 'RexxUtil', 'SysLoadFuncs'
  471. call SysLoadFuncs
  472.  
  473. if SysDestroyObject( '<Rwx>')
  474. then
  475.     say 'Rwx object deleted'
  476. else
  477.     say 'Unable to delete Rwx object'
  478.  
  479. if SysDeregisterObjectClass( 'Rwx')
  480. then
  481.     say 'Rwx class deregistered'
  482. else
  483.     say 'Unable to deregister Rwx class'
  484. --------------------------------------------------------------------
  485.  
  486. ____________________________________________________________________
  487. ____________________________________________________________________
  488.  
  489.     LICENSE AGREEMENT
  490. ____________________________________________________________________
  491.  
  492.  
  493. Rwx is the copyrighted property of Richard L. Walsh. It is licensed,
  494. not given, to you at no cost for your personal use.
  495.  
  496. You may copy and freely redistribute Rwx to others, provided:
  497.  
  498.     -the recipient agrees to the terms of this license,
  499.     -you transfer Rwx as a whole and intact,
  500.     -there is no cost to the recipient other than the costs
  501.      of providing media and transmission, and
  502.     -it is not redistributed in conjunction with any software
  503.      that may not also be freely redistributed by the recipient.
  504.  
  505. You may not modify Rwx in any way nor may you reverse assemble,
  506. reverse compile, or otherwise translate or reverse engineer its
  507. executable code or data. 
  508.  
  509. Rwx is not warranted to be free of defects nor to be suitable for
  510. any particular purpose the licensee may put it to. The licensee
  511. agrees to use Rwx at his or her own risk, and agrees to accept
  512. all liabilities arising from its use, including all claims by
  513. third parties, without recourse to the author or copyright holder.
  514.  
  515. THERE ARE NO WARRANTIES, EXPRESS OR IMPLIED, OF ANY SORT.
  516. BY YOUR USE OF THE PROGRAM YOU AGREE TO THE TERMS OF THIS LICENSE.
  517.  
  518. ____________________________________________________________________
  519. ____________________________________________________________________
  520.  
  521. Rich Walsh  <rlwalsh@packet.net>
  522. Ft Myers, Florida
  523.  
  524. Jan 22, 1997
  525.  
  526. ____________________________________________________________________
  527.  
  528.  
  529.     === Have you tried DragText yet? ===
  530.  
  531. DragText lets you handle text as an object by adding
  532. drag and drop text to commonly used windows systemwide.
  533. Visit http://www.usacomputers.net/personal/rlwalsh/
  534. for more information.  DragText v2.5 is also available
  535. from many popular FTP sites as drgtxt25.zip.
  536.  
  537. ____________________________________________________________________
  538. ____________________________________________________________________
  539.  
  540.