!Reporter

v2.74 (01 Aug 2021)

The !Reporter application provides commands to display information in the Reporter window which can be very useful when developing and debugging Wimp programs in BASIC, C or Assembler, plus Modules, Obey files, and even the !Boot sequence!

There were a few new facilities in v2.72, which are indicated by , because the main change is to improve the Search facility, plus many miscellaneous fixes and changes.

A summary of the main facilities of Reporter is ...

General
- All OS Commands executed can be displayed, including any error messages, and optional Time and Source.
- Any Error or WimpError messages and codes can be displayed.
- Anything written to file system Report will be displayed.
- Anything output after VDU 4 from a task can be displayed.
- Reporting can be turned On or Off, from the program or externally.
- The display can be saved to a file (manually or automatically), with an automatic numeric suffix.
- Improved Search facility to find a string in the text area, with simple wildcard and search history.
- Reported lines can also be written to SysLog.
- Help information is in StrongHelp format for ease of use.
- The whole RISC OS !Boot sequence can be Reported, and Reporter commands can be used.
  Now more robust and fail-safe.
- Runs on RISC OS v3, v4, v5 and v6, and all currently known hardware in 26 & 32 bit mode up to ARMv8.
- Facility to set Reporter inactive at startup.
- Initial startup customisation set using ConfiX.
Reporting Commands
- Report command to display text and variables from the command line, obey files or programs (see below)
- ReportTasks command to display a list of the running tasks.
- ReportDump command to display storage in hex and character.
- ReportHeap command to display and validate OS Heaps. If heap is corrupt, it will display the block which is invalid, and raise an error.
- ReportWhere command to display information about the latest abort.
- ReportMods command to display full details of all Relocatable Modules.
- ReportVer command to display the version of individual modules.
- ReportErrBlk command and SWI to enable easy reporting of error block contents after a SWI.
Control Commands
- ReportClear command clears text display area and automatically Unpauses.
- ReportSave command saves current text area to a file.
- ReportOpt is a general options command for Commands, Time, Source, Errors, Hide, Pause etc.
- Old commands which were replaced by *ReportOpt command in v2.70 have been removed.
Commands for use in BASIC
- Report command to display text, values of variables, evaluated expressions, and storage.
  Facility for displaying current PROC/FN name using \?
- ReportMem command to display a summary of memory usage, including Slotsize, addresses and string free space.
  Facility for verifying and listing 121 internal BASIC lists.
- ReportErr command to display BASIC Errors (with line number and any Library name], and optionally Throwback invoked to display the line in error.
- ReportMon command to monitor changes to BASIC variables.
- ReportTrace command to display BASIC TRACE output (with BASIC v1.24+ indents and reports ENDPROC/ENDFN.)
- ReportPoll command to display of WimpPoll reason codes.
- ReportStack command to display the BASIC Stack contents (like a traceback facility).
Other Languages
- There are some functions so using Reporter is easier from BASIC Assembler.
- Assembled code can display text, and values of registers, using SWIs, or FNs from BASIC.
- Ada95 code can display text, and values of OS variables.
- SWI Report_Registers and BASIC FNReport support printf-style output.
- BASIC FNReport supports condition codes, avoids code expansion, and has no usage limit.
- BASIC FNReportOn and FNReportOff to enable easier control.
- PROCReportPatch to enable easy patching of existing code.

Report Command

The most useful and most used command is *Report, which has the facilities outlined below...

*Report [ <text> | <<OsVariable>> | <BASICVariable> | (<BASICExpression>) ]

This command takes any text passed to it and displays it in the Reporter window, which automatically scrolls.
If an OS variable is found it will display <variable>=value.
If a BASIC variable name is found, it will display name=value.
If a BASIC expression is found in brackets (), it will display (expr)=value.
If a numeric BASIC variable or expression is preceeded by a ~ sign the output is in Hexadecimal.
Text or background can be coloured in any of 15 colours.
Time and date can be easily displayed, including a microsecond timer.
Output from another command can be displayed.

Many of these facilities are also available in SWI "Report_TextS" or "Report_Text0", or BASIC FNReport for assembler.

Example of Reporter Usage

A simple BASIC program ...

010 : REM Simple Reporter Demonstration 020 : ON ERROR END 030 : *Report \G Start Simple BASIC Test at time \t ... 040 : *Report \b Hello World from Reporter 050 : *ReportDebug 060 : String$="a string" :Integer%=67890 :HexInt%=&1234 070 : *Report String$ Integer% ~HexInt% 080 : Float = 9876/77 090 : DIM FloatArray(5) :FloatArray(1) = 1.234 100 : *Report Float FloatArray(1) 110 : *Report ((ATN Integer%)*100) 120 : *Set Test$OsVar Test OS Variable 130 : *Report <Test$OsVar> 140 : PROCproc1 150 : END 160 : 170 : DEF PROCproc1 180 : FOR I% = 369 TO -369 STEP -369 190 : PROCproc2(I%) 200 : NEXT 210 : ENDPROC 220 : 230 : DEF PROCproc2(divisor%) 240 : *Report divisor% 250 : perc% = FNpercent(123,divisor%) 260 : *Report perc% 270 : ENDPROC 280 : 290 : DEF FNpercent(A%,B%) 300 : = A% / B% * 100

... and the Reporter display, showing simple Obey file and BASIC program running

Extender Modules

There are two modules that extend the abilities of Reporter:

MsgMon

allows the details of any Wimp messages passing between applications on the system to be viewed on the screen in real time, with control over which messages are recorded. It was written by, and is available from, Steve Fryatt.

ServMon

allows the details of any Service calls made by applications on the system to be viewed on the screen in real time, with control over which services are recorded. It was written by me, based on MsgMon by Steve Fryatt, and will be available soon.

Recent Change History

14/03/2006 v2.64 Release version
05/02/2010 v2.64 Update to the latest available.
21/04/2011 v2.66 Release version with many changes.
24/04/2011 v2.66a Minor change to remove RMA Heap list when started during Boot.
11/02/2012 v2.66d Minor change to enable *ReportHeap to cater for the OS_Heap changes in RISC OS v5.18.
14/08/2012 v2.67 Release version with many changes.
22/08/2012 v2.67a Minor changes, mainly to remove need for including Choices file in zip. Users with v2.67 already do not need to update again, unless you have problems using AsmLib.
01/12/2015 v2.70 Release version with many changes.
04/12/2015 v2.71 Release version with minor improvements to the Search facility.
15/08/2020 v2.72 Release version with Search improvements and many other minor fixes.
01/08/2021 v2.74 Release version with some minor fixes.

How to obtain Reporter

To download please click on the files below:

Application	Version	Date	Download	Description
!Reporter	v2.74	(01 Aug 2021)	194 kByte	This is a full archive of the latest version, with minor Help update on 11th August. Note that you will also need StrongHelp to read the !Help file, and ConfiX to configure Reporter.

Supplementary Applications

There are three optional applications also available to download separately:

Application	Version	Date	Download	Description
!ReportTA	v1.02	(12 May 2004)	14 kByte	Analyses Trace data from BASIC programs collected by the !Reporter command *ReportTrace, counting the number of times Procedures, Functions, or even Lines are used. This enables the easy identification of program code that is: inefficient, so it can be optimised; very heavily used, so it can be optimised; never used, either for further testing, or removal. Needs ArmSort to run.
!ReportRMA	v1.00	(19 Jan 2006)	11 kByte	Analyses Relocatable Memory Area (RMA) Storage activity collected by the !Reporter command *ReportRmaOn, counting the number of storage Claims, Frees and Extends, and checking if there are any Frees or Extends without a Claim, or any Claims without a Free. Needs ArmSort to run.
!BasicTweak	v0.10	( 1 Dec 2015)	13 kByte	Enables *Report commands to be removed from BASIC programs, and also Crunched.

Please click home to return to the Avisoft home page.

E&OE. © Copyright Martin Avison, 2000-2021 Last updated: Tue 16th November 2021
Please send any queries or comments to
This site is hosted by Force9 on Plusnet