home *** CD-ROM | disk | FTP | other *** search
/ Creative Computers / CreativeComputers.iso / shareware / utilities / icontrace_2.00 / it.doc < prev    next >
Text File  |  1994-11-17  |  15KB  |  578 lines
  1.  
  2.  
  3.                        IconTrace v2.00 User's Manual                 1
  4.  
  5.  
  6.                               IconTrace v2.00
  7.  
  8.                         Copyright ⌐ 1993 Peter Stuer
  9.                             All rights reserved
  10.  
  11.                       Release date November 15, 1993
  12.  
  13.                                  FREEWARE
  14.  
  15.                                 User Manual
  16.  
  17.  
  18.      COPYRIGHT NOTICE 
  19.  
  20.      IconTrace software and documentation are Copyright ⌐ 1993 by
  21.      Peter Stuer.  All rights reserved.  
  22.  
  23.  
  24.      DISCLAIMER 
  25.  
  26.      IconTrace has proven to be stable in everyday use.  The author
  27.      is not responsible for any loss of data, damages to software or
  28.      hardware that may result directly or indirectly from the use of
  29.      this program.  The author reserves the right to make changes to
  30.      the software or documentation without notice.  
  31.  
  32.  
  33.      PREFACE 
  34.  
  35.      This program is freeware, this means that you can copy it freely
  36.      as long as you don't ask any more money for it than a nominal
  37.      fee for copying.  If you want to distribute this program you
  38.      should keep this document with it.  This program cannot be used
  39.      for commercial purposes without written permission from the
  40.      author.  
  41.  
  42.      None of the files of the IconTrace package may be modified or
  43.      left out without permission of the author. Crunching or achiving
  44.      is allowed only if none of the IconTrace files get modified by
  45.      it.  
  46.  
  47.      Special permission is hereby granted to include IconTrace in
  48.      Public-Domain collections such as Fred Fish's Amiga Library.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.      
  65.  
  66.  
  67.                        IconTrace v2.00 User's Manual                 2
  68.  
  69.  
  70.      Chapter 1 Introduction      
  71.  
  72.      1.1 What is IconTrace ?    
  73.  
  74.          IconTrace is a program that allows you to monitor what the
  75.      icon library is doing when you start a program using the
  76.      Workbench.  It's main use lies in discovering undocumented
  77.      ToolTypes and debugging your existing ToolTypes by watching if
  78.      the program finds them correctly. You are also shown what icons
  79.      your programs look for.  
  80.  
  81.  
  82.      1.2 Features of IconTrace     
  83.  
  84.          Currently the following functions can be monitored: 
  85.  
  86.              FindToolType            GetIcon 
  87.              GetDiskObject           MatchToolValue 
  88.              GetDiskObjectNew        PutDiskObject 
  89.              GetDefDiskObject        PutDefDiskObject 
  90.                                      PutIcon 
  91.  
  92.      You can specify which functions IconTrace should monitor.  
  93.  
  94.      IconTrace saves the trace information it gathers as session
  95.      history. It provides a scrollbar which enables you to scroll
  96.      through the session history.  
  97.  
  98.      IconTrace is also a commodity. You can specify a hotkey to show
  99.      or hide the output window.  
  100.  
  101.      IconTrace can open on any public screen.  
  102.  
  103.  
  104.      1.3 System requirements      
  105.  
  106.          IconTrace should run on any Amiga system with at least 512K
  107.      RAM and one disk-drive. IconTrace requires KickStart v2.04 or
  108.      higher to run. Special care has been taken in the program design
  109.      to make the program work with 68020, 68030 and 68040 processors
  110.      without sacrificing 68000 compatibility.  
  111.  
  112.      IconTrace also requires the ReqTools.library v38 or higher.
  113.      ReqTools is copyright ⌐ 1992, 1993 by Nico Franτois.  
  114.  
  115.      IconTrace is KickStart 3.0 compatible and aware. It will show
  116.      you some of the new features available with this version of the
  117.      operating system.  
  118.  
  119.      Should you have any trouble running IconTrace on your machine,
  120.      please write to me with the full specifications of your machine,
  121.      that is KickStart version, model, expansion boards etc...  
  122.  
  123.  
  124.      1.4 About the author and the program  
  125.  
  126.  
  127.  
  128.      
  129.  
  130.  
  131.                        IconTrace v2.00 User's Manual                 3
  132.  
  133.  
  134.          IconTrace has been created using the Macro68 Assembler and
  135.      CygnusEd Professional 3 on an Amiga A3000 25/100 with 10MB
  136.      memory.  The IconTrace documentation was formatted with PRoff.  
  137.  
  138.      If you have suggestions or remarks about this program, or if you
  139.      find any bugs, please let me know.  
  140.  
  141.      When sending in bug reports, please state exactly under what
  142.      circumstances the bug occurred, what equipment was used and what
  143.      happened. If possible also try to give me enough information to
  144.      reproduce the bug. It is very difficult to find bugs when you
  145.      don't know exactly what happened.  
  146.  
  147.      Write to the following address: 
  148.  
  149.              Fido     :  2:292/603.7 (Peter Stuer)
  150.              AmigaNet : 39:120/102.7 (Peter Stuer)
  151.              NLA Net  : 14:200/101.7 (Peter Stuer)
  152.  
  153.              UUCP     : Peter.Stuer@p7.f603.n292.z2.FidoNet.Org
  154.  
  155.              SnailMail: Peter Stuer
  156.                         Beatrijslaan 2 bus 13
  157.                         B-2050 Antwerpen L.O.
  158.                         Belgium - Europe
  159.  
  160.      I will also try to put the latest available version of IconTrace
  161.      on the following BBS (this may change without further notice): 
  162.  
  163.              Great Balls Of Fire BBS 
  164.              ReqTools Support BBS 
  165.              Herman Stevens 
  166.              Lubbeek 
  167.              ADS Distribution HUB 
  168.              ABC Host Belgium 
  169.              AFN Host Belgium 
  170.              Tel. +32-(0)16-64.09.12 
  171.              ZyXEL U1496+ 16800 BPS (N.8.1) v32bis v42bis 
  172.              24-24 h.  
  173.              Fido Node  2:292/603 
  174.              NLA Node  14:200/101.0 
  175.              AmyNet    39:120/102.0 
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.      
  193.  
  194.  
  195.                        IconTrace v2.00 User's Manual                 4
  196.  
  197.  
  198.      Chapter 2 Using IconTrace     
  199.  
  200.          You can be start IconTrace from the CLI/Shell or the
  201.      Workbench.  IconTrace will always check to make sure it is not
  202.      already running. If so, the copy of IT that is already running
  203.      will be notified and its window will open or come to the front.
  204.      The second copy will exit quietly.  
  205.  
  206.  
  207.      2.1 Starting IconTrace from the Shell   
  208.  
  209.          To start IconTrace from the Shell simply type: 
  210.  
  211.              1> IconTrace 
  212.  
  213.      followed by a return. If you want to continue using the Shell
  214.      while IconTrace is running, you need to prepend the Run command
  215.      before IconTrace as follows: 
  216.  
  217.              1> run IconTrace 
  218.  
  219.      If IconTrace is succesful in initializing itself, you see the
  220.      IconTrace window and will start monitoring the icon.library. If
  221.      no window is displayed, consult Appendix A (Troubleshooting) for
  222.      more assistance.  
  223.  
  224.  
  225.      2.2 Shell Startup Options     
  226.  
  227.          IconTrace can be started with various options. If you run
  228.      IconTrace with a questionmark (?) as argument you'll get the
  229.      argument template.  
  230.  
  231.  
  232.      HISTORY 
  233.  
  234.        This option tells IconTrace how many lines of history it
  235.        should keep. Use 0 to disable the history feature. The default
  236.        number of history lines is 256.  
  237.  
  238.      OUTPUT 
  239.  
  240.        With this option you can direct the trace information to some
  241.        other AmigaDOS device of file in addition or in place of the
  242.        information being displayed in the window.  
  243.  
  244.        If you have a debugging terminal attached to the serial port
  245.        you could use 'IconTrace OUTPUT=AUX:' to have all trace
  246.        information appear at the terminal.  
  247.  
  248.        A special symbol is DEBUG. 'OUTPUT=DEBUG' will output all
  249.        trace information to the serial port at 9600 baud.  
  250.  
  251.      WIDTH 
  252.  
  253.        This option specifies the width of the IconTrace output window
  254.  
  255.  
  256.      
  257.  
  258.  
  259.                        IconTrace v2.00 User's Manual                 5
  260.  
  261.  
  262.        in pixels. By default, IconTrace will open a window that is as
  263.        wide as the visible width of the public screen it is appearing
  264.        on.  
  265.  
  266.      HEIGHT 
  267.  
  268.        This option specifies the height of the IconTrace output
  269.        window in screen lines. By default, IconTrace will open a
  270.        window that is as high as the visible height of the public
  271.        screen it is appearing on, without overlapping the title bar.  
  272.  
  273.      SCREEN 
  274.  
  275.        If you do not use this option, IconTrace will open on the
  276.        default public screen which is most of the times the Workbench
  277.        screen.  IconTrace will try to open on the public screen whose
  278.        name is specified after this argument.  
  279.  
  280.      TRACEMASK 
  281.  
  282.        By specifying a trace mask you can determine which
  283.        icon.library functions IconTrace will actually trace. The
  284.        trace mask consists of a string of characters. The function
  285.        corresponding to the character will be traced. Use the
  286.        following characters: 
  287.  
  288.              A: GetIcon              F: PutDiskObject 
  289.              B: GetDiskObject        G: PutDefDiskObject 
  290.              C: GetDefDiskObject     H: FindToolType 
  291.              D: GetDefDiskObjectNew  I: MatchToolValue 
  292.              E: PutIcon 
  293.  
  294.        For example, TRACEMASK=HI will only trace the icon.library
  295.        FindToolType() and MatchToolValue(). By default, IconTrace
  296.        monitors all icon.library functions it knows about.  
  297.  
  298.      CX_PRIORITY 
  299.  
  300.        This option allows you to specify priority relative to the
  301.        other Commodities programs. Default priority is 0.  
  302.  
  303.      CX_POPKEY 
  304.  
  305.        This option allows you to change the default hot key for
  306.        IconTrace.  The default hot key is 'ralt i' (right Alt key
  307.        pressed with 'i').  
  308.  
  309.      CX_POPUP 
  310.  
  311.        If you do not want IconTrace to open its window, you can
  312.        specify the CX_POPUP switch like this: DT CX_POPUP=NO. By
  313.        default, the IconTrace window will open.  
  314.  
  315.      CX_ACTIVE 
  316.  
  317.        By specifying CX_ACTIVE=NO, IconTrace start without its
  318.  
  319.  
  320.      
  321.  
  322.  
  323.                        IconTrace v2.00 User's Manual                 6
  324.  
  325.  
  326.        tracing code enabled. By default, tracing starts immediately.  
  327.  
  328.  
  329.      2.3 Starting IconTrace from the Workbench   
  330.  
  331.          To start IconTrace from the Workbench, simply double-click
  332.      on the IconTrace icon to start the program or use the 'Execute
  333.      Command' item from the 'Workbench' menu.  
  334.  
  335.  
  336.      2.4 Workbench Startup Options     
  337.  
  338.          You can specify the same options as explained in the
  339.      paragraph "Shell Startup Options" by adding tooltypes to the
  340.      IconTrace icon.  
  341.  
  342.  
  343.                                    NOTE
  344.  
  345.           If you use the CX_POPUP and/or the CX_ACTIVE tooltype
  346.           you must specify them with '=YES' appended to them.
  347.           For example, 'CX_POPUP=YES'. Not using them defaults
  348.           to CX_POPUP=YES and CX_ACTIVE=YES.  
  349.  
  350.  
  351.      To change the task priority of IconTrace you can add the TOOLPRI
  352.      tooltype to the IconTrace icon. For example, adding TOOLPRI=5 will
  353.      start running IconTrace with task priority 5.
  354.  
  355.  
  356.      2.5 Stopping IconTrace     
  357.  
  358.          You can stop IconTrace at any time by sending it a break signal. If
  359.      you started IconTrace from the Shell, you can do this by pressing
  360.      Ctrl-C.
  361.  
  362.      Since IconTrace is a commodity you can use the Exchange utility to
  363.      control it.
  364.  
  365.        'Show Interface' will open the IconTrace output window
  366.  
  367.        'Hide Interface' will close the IconTrace output window
  368.  
  369.        The 'Active/Inactive' cycle gadget will toggle IconTrace's
  370.        activation status. When IconTrace is active it will update it's
  371.        internal history even when the output window is closed; when it is
  372.        inactive, no tracing will occur.
  373.  
  374.        The "Active" menuitem of the "Project" menu will also allow you to
  375.        toggle the activation status of IconTrace.
  376.  
  377.        'Remove' will tell IconTrace to quit.
  378.  
  379.      The 'Quit' menu item will exit IconTrace.
  380.  
  381.  
  382.  
  383.  
  384.      
  385.  
  386.  
  387.                        IconTrace v2.00 User's Manual                 7
  388.  
  389.  
  390.                                    NOTE
  391.  
  392.           IconTrace will try to quit immediately. If any of the
  393.           patches are still in use, it will wait until no
  394.           program uses the IconTrace patches anymore.  
  395.  
  396.  
  397.  
  398.      2.6 About the trace output   
  399.  
  400.          The information shown depends on which function is being traced
  401.      but all messages have 3 components in common:
  402.  
  403.              Process Name    The name of the process calling the
  404.                              icon.library function.
  405.  
  406.              Trace Info      Verbose information about the function
  407.                              being executed.
  408.  
  409.              Result          Whether the call was succesfull or not
  410.                              (if applicable)
  411.  
  412.      :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  413.      ::::::::::::::::::::::: IconTrace HISTORY ::::::::::::::::::::::::
  414.      :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  415.  
  416.      ::: Version 2.00 ::: November 15, 1993 ::::::::::::::::::::::::::
  417.  
  418.      - Complete rewrite.
  419.  
  420.      - NEW: Removed the annoying delay when quitting IconTrace. Thanks
  421.        to Rafael D'Halleweyn for the suggestion.
  422.  
  423.      - NEW: Added up/down gadgets to scroll up/down line by line.
  424.  
  425.      - NEW: Added Clear menu item to clear the history buffer while
  426.        IconTrace is running.
  427.  
  428.      - NEW: Added an Active menu item to make activating and
  429.        deactivating IconTrace on the fly easier.
  430.  
  431.      - NEW: Added trace code for undocumented functions GetIcon() and
  432.        PutIcon(). Apparently, the Workbench uses these calls to get
  433.        its icons when opening Workbench windows.
  434.  
  435.        NOTE: If you want to know why it takes so extremely long for the
  436.        Workbench to show a disk/drawer contents in using View By Name
  437.        mode, start IconTrace and be amazed!
  438.  
  439.      - IMPROVED: Optimized some of the core routines.
  440.  
  441.      ::: Version 1.02 ::: June 26, 1993 ::::::::::::::::::::::::::::::
  442.  
  443.      - BUG: The patch of the GetDiskObjectNew used the wrong trace
  444.        code.
  445.  
  446.  
  447.  
  448.      
  449.  
  450.  
  451.                        IconTrace v2.00 User's Manual                 8
  452.  
  453.  
  454.      - NEW: Made error reporting and failure handling more verbose.
  455.  
  456.      - NEW: Improved and optimized code.
  457.  
  458.      ::: Version 1.01 ::: June 24, 1993 ::::::::::::::::::::::::::::::
  459.  
  460.      - BUG: FindToolType trace code gave wrong results, sorry...
  461.  
  462.      ::: Version 1.00 ::: June 23, 1993 ::::::::::::::::::::::::::::::
  463.  
  464.      - First release
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.      
  513.  
  514.  
  515.      
  516.  
  517.  
  518.                              Table Of Contents
  519.  
  520.                               IconTrace v2.00
  521.  
  522.      Chapter 1 Introduction     ................................    2
  523.         1.1 What is IconTrace ?   ..............................    2
  524.         1.2 Features of IconTrace    ...........................    2
  525.         1.3 System requirements     ............................    2
  526.         1.4 About the author and the program ...................    2
  527.      Chapter 2 Using IconTrace    ..............................    4
  528.         2.1 Starting IconTrace from the Shell  .................    4
  529.         2.2 Shell Startup Options    ...........................    4
  530.         2.3 Starting IconTrace from the Workbench  .............    6
  531.         2.4 Workbench Startup Options    .......................    6
  532.         2.5 Stopping IconTrace     .............................    6
  533.         2.6 About the trace output   ...........................    7
  534.  
  535.      Copyright ⌐ 1993 IconTrace v2.00 written by Peter Stuer
  536.  
  537.                   _
  538.                _ //
  539.      Thanks to \X/ Amiga for being the best computer ever !
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.      
  577.  
  578.