

                       Help for Reporter                           v2.11
                       =================

  Purpose
  =======

  This little module provides some commands which can be very useful when
  debugging Wimp programs, as it enables information to be easily displayed 
  in a separate debugging window.

  The main facilities are ...

    Basic programs can display text, and values of variables and evaluated 
     expressions, just with commands - NO additional Basic PROCs or FNs.

    The scrollable Reporter window will have new lines added at the bottom, 
     and previous lines scrolled upwards. The maximim size is customisable.
     
    The Reporter window can be scrolled with Page Up/Down, Home, End, 
     and the cursor keys.

    The text and background can be coloured in many of the Wimp colours.

    Reporting can be turned On or Off, from the program or externally.

    The display can be saved to a file.

    Basic memory usage summary can be displayed.

    Basic Errors can be displayed, and Throwback invoked to display the
     line in error.
    
    Obey files can display text, and values of OS Variables.

    Assembled code can display text, and values of registers.

    Ada95 code can display text, and values of OS variables.

  Reporter v1 was written by Chris Morison.
  Reporter v2 was written by Martin Avison, based (with permission) on v1.
  
  The latest version will be available from both web sites - see Contact
  Information below.


  Starting Reporter
  =================

  To start Reporter, just double-click on the !Reporter application in the
  usual way. Nothing obvious will happen! When a command first writes
  something to the Reporter window, it will then open so you can see what has
  been written. 

  The scrollable window will have new lines added at the bottom, and previous
  lines scrolled upwards. The display can be moved by the scroll bars, and
  when the window gains the input focus by clicking Select in it, then Home, 
  End, Page Up, Page Down, Cursor Up, Down, Left and Right also have the 
  expected effects.

  Note that the window can only be updated when Reporter is allowed to 
  process ... it cannot update if a program is in a hard loop, or RISC OS 
  is single tasking (displaying an Error box, for example).


  Commands provided by Reporter:
  ==============================

  Most commands do not have to be in a Wimp Task to work, so can be used from
  a Basic program, an Obey file, a TaskWindow, or even a * command prompt!

  The total length of text displayed by any one command should not exceed 250
  characters - just split it into multiple commands. If 250 is exceeded, ?=>
  will be displayed at that point and the line will end there, AND another
  line will be overwritten with the remainder of the line.

  *Report [ <text> | <<OsVariable>> | <BasicVariable> | (<BasicExpression>) ]
  ---------------------------------------------------------------------------
  This will be the most used command. It takes any text passed to it and
  displays it in the Reporter window, opening it if necessary. 

  If nothing follows the *Report command, just a blank line is displayed.

  If an OS variable is found enclosed in <>, then it will display
  <name>="value". If it is not a current variable, it will be displayed
  unchanged.

  If \t is found, it will be replaced by the time in hh:mm:ss.cc format to
  help in any time critical applications.
  
  If \ is found at the start of the line, followed by a special colour
  character, the line will be displayed in the standard Wimp colours to
  help the readability of the display. The colours available are:
         Text    Background    Colour
          \w        \W         White
          \f        \F         Faded Grey 
          \b        \B         Blue
          \y        \Y         Yellow
          \g        \G         Green
          \r        \R         Red
          \c        \C         Cream
          \d        \D         Dark Green
          \o        \O         Orange
          \l        \L         Light Blue
  Note that EITHER the Text colour can be set OR the Background colour, but
  NOT both! The text is automatically set white for dark background colours. 
  Some values are more useful than others!
  
  If there is text which should be displayed without any change, then just
  enclose the whole text in quotes. The text will then be displayed
  unchanged, but without the quote marks.

  The most powerful facilities are for use for debugging Basic programs, but
  these only work from within a Basic program, otherwise they are treated as
  text to be displayed ...

  If a Basic variable name is found, it will display name=value of the
  variable at that time. This will handle any type of variable - Integers,
  Strings, Floats (even in BASIC64), and elements of Arrays. Note that a
  variable name must be preceeded by a blank or a comma.  An Integer may also
  be preceeded by a ~ sign, which will display the value in Hexadecimal.
  
  If a String variable is found to contain control characters (&00-&1F or 
  &7F) the byte will be displayed in Hexadecimal within Square Brackets 
  eg [13] to avoid controlling the display and confusing the user! 

  Indirected variables (those starting in !$|?) may be used, but please be
  more careful with these. It does not seem possible to trap some errors, so
  it is possible to get 'Unknown or missing variable', or even 'Abort on Data
  Transfer' if they are wrongly used on a *Report command, just as you would
  in the Basic program itself. 

  If a Basic expression is found contained in brackets (), then it will be
  tokenised, then passed to Basic for evaluation. If it is numeric, it will
  then be evaluated by STR$, unless it is preceeded by a ~ sign when it will
  be evaluated by STR$~, giving the output in Hexadecimal.  Note the
  expression including () cannot be more than 120 characters, otherwise a
  message 'too long' is displayed. It can contain any valid single Basic 
  expression including any operators, functions, and user defined functions. 

  It is quite possible that Basic errors are raised when the *Report command
  is processed when running from Basic. In this case the error will be passed
  back to the Basic program correctly, with the Error Line ERL indicating the
  line on which the incorrect *Report command is, and ERR and REPORT$ giving
  the actual error.

  *ReportClear [<text>] 
  ---------------------
  Clears the Reporter window, and will display a Dark Green message 
  '** ReportClear **' followed by any text.

  It can also be used by from the Reporter menu.

  *ReportClose
  ------------
  Closes the Reporter window. 
  The contents are not changed - they just cannot be seen.

  *ReportQuit
  -----------
  Quits the !Reporter application. 
  It can also be used from the Reporter menu.
  Any further Reporter commands will result in 'File not found' errors.  

  *ReportOff [<text>]
  -------------------
  Turns all reporting off, and will display a Red message 
  '** ReportOff **' followed by any text. 
  Note that it has no effect if already off!

  This enables easy control over which reports are produced without
  adding/removing many other commands. 

  It can also be used from the Reporter menu.

  *ReportOn [<text>] 
  ------------------ 
  Turns all reporting on, and will display a Dark Green message 
  '** ReportOn  **' followed by any text. 
  Note that it has no effect if already on! 

  This enables easy control over which reports are produced without
  adding/removing many other commands. 

  It can also be used from the Reporter menu.

  *ReportMem 
  ---------- 
  Displays a summary of the memory usage within a Basic program, giving the
  Free space, and the space used by the Program, Variables, and the Stack.
  This can be useful for monitoring the effect of variable allocations and
  stack usage (for loops, procedures etc) on the Free space, and to ensure
  there is no memory leakage. 
  
  If there is less than 512 bytes free then the Variables cannot expand, 
  resulting in various 'No Room' errors.

  If there is less than 1024 bytes free then the Stack cannot expand, 
  resulting in 'Too many nested structures' errors.

  The message is normally Green, but if Free is less than 4096 bytes it will 
  have an Orange background, or less than 1024 bytes it will have a Red 
  background. 

  The figures are mostly from the functions PAGE, TOP, END and HIMEM, but the
  split between Variables and Stack cannot easily be obtained elsewhere.
  The values should add up to HIMEM-PAGE.

  This command will ONLY work from within a Basic program, otherwise
  it will just display a Red message 'Not in Basic' 

  *ReportError  [Throwback]
  -------------------------
  Displays a Red backround message containing the error and Basic error 
  line to the Reporter window. It is intended to be placed in a Basic error 
  handling routine.

  If Throwback was specified (or just the T), it will then try to perform a
  'Throwback' of the error... 

  IF   module DDEUtils is available 
       It is in the v4.00 system ROM, and probably previous ones as well.
       This dependency could probably be removed, if required. 

  AND  there is a Throwback handler running 
       eg Zap v1.40 and later, and probably previous versions 

  AND  the program was started with a command that included the filename
       Note this excludes some ways of running programs from within Zap,
       because they are run from memory locations. 
  	  Save, Run, Quit      ^E     seems the best way

  THEN a Throwback window will open with the filename, and the error line and
       message. Clicking on this line will load the program into Zap, if not
       already loaded, then display the program in error at the line in error.
     
  Throwback notes:

  1.  Under some circumstances if Throwback is tried the screen may blank and
  completely redraw, for example an error in a program which has used PRINT
  outside a Task. 

  2.  If the error is in a LIBRARY, then Throwback cannot tell, and it will
  indicate the ERL as in the main program - wrongly! Libraries should
  probably be tested as part of the main program.

  3.  StrongEd v4.60 seems to have Throwback, BUT it seems to go to the
  PHYSICAL line number requested, not the BASIC line number. This may be my
  lack of understanding - I confess to being a Zap user, so my knowledge of
  StrongEd is based on 5 minutes experiment! If anyone can get this to work,
  please let me know.

  This all may seem rather restrictive, but nevertheless can be very useful!

  Note *ReportError will ONLY work from within a Basic program, otherwise it 
  will just display a Red message 'Not in Basic' 

  *ReportSave  [<filename>] 
  ------------------------- 
  Saves the contents of the Reporter text to a text file <filename>. 
  If the filename is omitted, RAM:ReportList will be used.
  Any errors from the save are written to the Reporter window.

  Note that only lines than can be displayed are saved, and will not include
  any lines that have been discarded because the text workarea is full. 
  See Customisation below if you want to increase the text workarea size.

  It can also be used from the Reporter menu, but a name of RAM:ReportList
  will always be used.

  This is rather crude, but it could be improved if there is a demand.

  The saved files can enable comparisons between different debugging
  sessions to be made.


  Assembler Code Debugging
  ========================

  There are some rudimentary facilities for helping to debug assembler code
  using the facilities of Reporter. 
  
  There is a Basic FNReport(0,"") which will generate instructions to Branch
  to Reporter, which when executed will display Registers 0 to 13, the Flags,
  and the Mode, hopefully without disturbing your program.  If the code is
  being assembled Offset (ie OPT bit 4 is on) the Branch will be relocatable,
  12 bytes long. If not Offset, a simple branch will be generated, only 4
  bytes long, but in this case the assembled code must NOT be moved before
  execution.

  If the first parameter is not zero, then only the Registers with
  the corresponding bit on will be displayed. For example, %10011 will
  display registers r0,r1, and r4 only. Note that this facility inserts 4
  more bytes into your code for the flag values.

  Note that when the following are displayed ...
    r14 is the return address from the Branch and Link to Reporter.
    pc  is the actual address of the Branch and Link to Reporter.  

  If the second parameter is not null, then the text will be displayed
  instead of the 'Register List' default so that you can easily tell where
  you are.  Note that this facility inserts the length of the message into
  your code, and it also needs the 4 byte flag.

  The additional code inserted could of course take some references out of
  range. This is not easily avoidable - at least it will work when they are
  removed!

  Please see and run the TestAsm program for an example.

  There are also some SWIs which can be used:

    Report_Clear        executes *ReportClear
    Report_Close        executes *ReportClose
    Report_On           executes *ReportOn
    Report_Off          executes *ReportOff

  and some SWIs which are designed for use in FNReport:

    Report_RegList      used by FNReportRegs to get branch address
    Report_RegListX     used by FNReportRegs to get extended branch address

  Notes:
  
  1.  When testing using this facility, please assemble your program AFTER
  Reporter is loaded. If Reporter subsequently has to be re-loaded, any
  attempt to run your program is likely to be fatal until it is re-assembled. 

  2.  Currently it will NOT work from a program that is in SVC mode if the
  code has been assembled Offset. This is being investigated to find a
  reasonable solution!


  Debugging Hints and Tips
  ========================

  To temporarily disable Reporting, use *ReportOn and *ReportOff commands 
  in the program, and/or from the Reporter menu.
  
  To remove Reporter commands temporarily from a Basic program, use an editor 
  to change   *Report
     to       REM *Report
  Reverse this to re-activate Reporter.

  To remove Reporter commands permanently from a Basic program, use an editor 
  to change the comands to REM comments as above. Then the REM statements
  can be easily removed by
     either using Basic CRUNCH %100 then saving it somewhere else
     or using one of the many Basic compressors (eg !BC) 
  
  To allow Reporter commands to be used under control of the program, use
     IF debug THEN *Report ....

  If a Memory leak is suspected, use *ReportMem to see if and why the
  free space keeps decreasing.


  Ada95 Debugging
  ===============
  
  The Ada95 directory contains some information from Stefan Bellon which
  should enable at least text to be displayed from Ada95 programs.

  If any problems or queries about this, please ask Stefan, as it means
  nothing to me!


  Customisation
  =============

  The scrollable window will display by default up to about 6k of text,
  ie about the last 600 lines of 10 characters ... or 24 lines of 250
  characters! When the text workarea is full the oldest messages are 
  discarded.

  The only customisation available is to change the size of the text 
  workarea by adding a number to the end of the RmRun command in the !Run 
  file. This will specify the number of Kbytes of text storage area to be
  used. The only knowm limit is available memory!


  Conversion from Reporter v1
  ===========================

  If you have used Reporter v1.23 or earlier in programs, then:

        Replace any of ...            With ...

        *Reporter       xxx           *Report      xxx
        *Reporter_Clear xxx           *ReportClear xxx
        *Reporter_Close               *ReportClose

        PROCreporter(xxx)             *Report      xxx
        PROCreporter_clear(xxx)       *ReportClear xxx
        PROCreporter_val(xxx)         *Report      xxx

  then remove any of the above PROCs from the program, and all should work!

  Note that the direction of scroll of the window has been changed from
  downwards to upwards!


  Conditions of Use
  =================

  Please note that all the software and documentation supplied with Reporter 
  is FreeWare. This means that we retain the copyright on all the files
  contained within the !Reporter directory. You may freely copy and
  distribute it, provided that it is complete with all the original files,
  and that you do not sell it. 

  If you use Reporter, please send an eMail to one of the addresses below.
  We will then let you know of any new versions.

  PD libraries and other collections may not distribute Reporter without our
  written permission:  this is only so we can ensure that the latest version
  is available.

  Although Reporter is believed to be free of any bugs, we cannot accept any
  responsibility for any loss or corruption of data which might result from
  using Reporter.  Normal testing and data backup should be performed!


  Problems and Suggestions
  ========================

  If any bugs or problems are found, or if you have any suggestions for
  improvements, please send either of us full details including version
  information, preferably on eMail, so that we can recreate the problem and
  try to correct it.


  History
  =======

  04/03/1997 v1.23 Release version by Chris Morison

  Martin Avison then copied (with permission) Chris Morison's v1.23, 
  and eventually there emerged ...

  19/02/2000 v2.00 First public release version by Martin Avison
  05/04/2000 v2.01 Fixed ReportClear very long wait problem
  08/04/2000 v2.02 Optimised large Text Areas #1 ?
                   Added Hex Ctrl char output in Strings (and v2.00a)
                   Added Text Colour support
  02/05/2000 v2.03 Optimised large Text Areas #2
  06/05/2000 v2.04 Added Background Colour support
  06/05/2000 v2.05 Added ReportQuit command
  07/05/2000 v2.06 Optimised large Text Areas #3
  08/05/2000 v2.07 Extended background colour to left margin
  09/05/2000 v2.08 Added ReportSave facility
  12/05/2000 v2.09 Fixed resize window bug
                   Added KeyPress handling for page movement
                   Added ReportMem command
  22/05/2000 v2.10 Public release by Martin
  24/05/2000 v2.11 Fixed Processkey bug    


  Contact Information
  ===================

  Chris Morison:

           SnailMail:  Chris Morison
                       4 Arley Close
                       Macclesfield
                       Cheshire
                       SK11 8QP

           eMail:      organizer@ukgateway.net
        
           Web Page:   http://www.organizer.ukgateway.net


  Martin Avison:

           SnailMail:  Martin Avison,
                       Avisoft,
                       16  Well Close,
                       Leigh,
                       TONBRIDGE,
                       Kent      TN11  8RQ

           eMail:      support@avisoft.force9.net

           Web Page:   http//www.avisoft.force9.co.uk


      *******************************************************
      **  If this help has flashed past too fast to read,  **
      **  then please load any Text Editor and try again!  **
      *******************************************************
