<document title="MsgMon">
<define name="version" value="">
<define name="date" value="" length=20 align="right">




<literal mode="Text">
=============================================================================
MsgMon - Monitor Wimp Messages with Reporter                     Version $$version$$

(C) Stephen Fryatt 2010-2020                             $$date$$
=============================================================================
</literal>







<chapter title="Licence" file="Licence">

<cite>MsgMon</cite> is licensed under the EUPL, Version&nbsp;1.2 only (the "Licence"); you may not use this work except in compliance with the Licence.

You may obtain a copy of the Licence at <link ref="#url http://joinup.ec.europa.eu/software/page/eupl">http://joinup.ec.europa.eu/software/page/eupl</link>

Unless required by applicable law or agreed to in writing, software distributed under the Licence is distributed on an &quot;<strong>as is</strong>&quot; basis, <strong>without warranties or conditions of any kind</strong>, either express or implied.

See the Licence for the specific language governing permissions and limitations under the Licence.

The source for <cite>MsgMon</cite> can be found alongside this binary download, at <link ref="#url http://www.stevefryatt.org.uk/software">http://www.stevefryatt.org.uk/software</link>

The necessary libraries and build tools can be found at <link ref="#url http://www.stevefryatt.org.uk/software/build">http://www.stevefryatt.org.uk/software/build</link>

</chapter>




<chapter title="Introduction" file="Introduction">

<cite>MsgMon</cite> is a module to work with <cite>Reporter</cite>, from Chris Morison and Martin Avison, in order to display details of messages passed between applications using the Wimp's User Message protocol. When run, it installs a set of filters to watch for messages; these are decoded and, if they are in the list of message codes that <cite>MsgMon</cite> is interested in, displayed in the <cite>Reporter</cite> window.

Copies of the latest version of <cite>Reporter</cite> can be found on Martin Avison's website, at <link ref="#url http://www.avisoft.force9.co.uk/">http://www.avisoft.force9.co.uk/</link>

</chapter>




<chapter title="Installation and Use" file="Use">

<cite>MsgMon</cite> requires RISC OS 3.1 or later, and a copy of <cite>Reporter</cite> from <link ref="#url http://www.avisoft.force9.co.uk/">http://www.avisoft.force9.co.uk/</link>

The module does not require installation, and it can simply be started from the Filer by double-clicking on it. As long as <cite>Reporter</cite> is also running, details of all Wimp messages passing between the applications running on the system will start to be shown in the <window>Reporter</window> window.

As an example, a simple two message exchange would be shown in <cite>Reporter</cite> by <cite>MsgMon</cite> as follows:

<codeblock>
Message_DataOpen (&amp;000005) [Message Recorded]
From 'Filer' to 'StrongED'
My ref: &amp;0007E35B; Your ref: &amp;00000000
20  : 20909099 : ...  : 546345113
24  : FFFFFFFF : .... : -1
28  : 0000063C : <... : 1596
32  : 0000021E : .... : 542
36  : 00000000 : .... : 0
40  : 00000FFF : .... : 4095
44  : 53464441 : ADFS : 1397113921
48  : 79493A3A : ::Iy : 2034842170
52  : 78696E6F : onix : 2020175471
56  : 522E242E : .$.R : 1378755630
60  : 726F7065 : epor : 1919905893
64  : 73694C74 : tLis : 1936280692
68  : 00000074 : t... : 116
72  : 000006BE : .... : 1726
76  : 000003D4 : .... : 980

Message_DataLoadAck (&amp;000004) [Message]
From 'StrongED' to 'Filer'
My ref: &amp;0007E35C; Your ref: &amp;0007E35B
20  : 20909099 : ...  : 546345113
24  : FFFFFFFF : .... : -1
28  : 0000063C : <... : 1596
32  : 0000021E : .... : 542
36  : 00000000 : .... : 0
40  : 00000FFF : .... : 4095
44  : 53464441 : ADFS : 1397113921
48  : 79493A3A : ::Iy : 2034842170
52  : 78696E6F : onix : 2020175471
56  : 522E242E : .$.R : 1378755630
60  : 726F7065 : epor : 1919905893
64  : 73694C74 : tLis : 1936280692
68  : 00000074 : t... : 116
72  : 000006BE : .... : 1726
76  : 000003D4 : .... : 980
</codeblock>

Each message consists of three header lines in black, followed by a dump of the message contents (where applicable) in blue. The first line of each header is highlighted with a cream background to make individual messages stand out.

The first line of the header consists of the message name (as defined by Acorn and their successors or by the third parties responsible) with the 32-bit hexadecimal message number following it in parentheses. If the message does not appear in the list of numbers that <cite>MsgMon</cite> knows about, a textual name will not be given. At the end of the line is the type of message, in square brackets: this will either be &quot;Message&quot;, &quot;Message Recorded&quot; or &quot;Message Acknowledge&quot;, which correspond to the Wimp_Poll reason codes 17, 18 and 19 respectively.

The second header line shows the applications sending and receiving the message, converted from task handles into task names. Broadcast messages will be reported multiple times: once for each application that they are sent to before being claimed. In some cases, when the system itself sends the message, the 'From' field will appear as an empty string.

The third header line gives the My Ref and Your Ref fields from the message, again as hexadecimal 32-bit numbers.

If the message block was longer than the basic 20 bytes, subsequent lines of the report show the block contents as a series of 32-bit integers.  Each appears on its own line, containing from left to right the offset into the message block, the value of the word in hexadecimal, the value of the word as four ASCII bytes shown LSB to MSB, and the value of the word in signed decimal. In the case of the ASCII bytes, characters outside of the range 32 to 126 (space to '~') are shown as full-stops.

To stop <cite>MsgMon</cite> sending messages to <cite>Reporter</cite>, the module should be killed using <command>*RMKill MsgMon</command> at the command line: this could be placed in an Obey file to save typing it regularly.


<subhead title="Narrowing down the messages">

By default, <cite>MsgMon</cite> will report all the messages that occur on the system; this very quickly becomes unwieldy. Using the <command>*MsgMonAddMsg</command> command it is possible to narrow down the messages that get reported: once at least one message has been added to <cite>MsgMon</cite>'s list, only listed messages will be included.

The easiest way to use the command is to create Obey files containing lists of messages belonging to specific groups. For example, the following saved as an Obey file would cause messages belonging to the Data Transfer Protocol and the Block Transfer Protocol to be shown:

<codeblock>
MsgMonAddMsg 1
MsgMonAddMsg 2
MsgMonAddMsg 3
MsgMonAddMsg 4
MsgMonAddMsg 5
MsgMonAddMsg 6
MsgMonAddMsg 7
MsgMonaddMsg &amp;D
MsgMonAddMsg &amp;F
MsgMonAddMsg &amp;10
MsgMonAddMsg &amp;11
MsgMonAddMsg &amp;12
MsgMonAddMsg &amp;13
</codeblock>

Alternatively, messages can be specified by name, using the names in message file (see <link ref="Config">Configuring the Module</link>) with <code>Message_</code> at the start. The list above could also be written as follows, with the same effect (the names are matched case-insensitively):

<codeblock>
MsgMonAddMsg Message_DataSave
MsgMonAddMsg Message_DataSaveAck
MsgMonAddMsg Message_DataLoad
MsgMonAddMsg Message_DataLoadAck
MsgMonAddMsg Message_DataOpen
MsgMonAddMsg Message_RAMFetch
MsgMonAddMsg Message_RAMTransmit
MsgMonAddMsg Message_DataSaved
MsgMonAddMsg Message_PreQuit
MsgMonAddMsg Message_PaletteChange
MsgMonAddMsg Message_SaveDesktop
MsgMonAddMsg Message_DeviceClaim
MsgMonAddMsg Message_DeviceInUse
MsgMonAddMsg Message_Shutdown
MsgMonAddMsg Message_ClaimEntity
MsgMonAddMsg Message_DataRequest
MsgMonAddMsg Message_Dragging
MsgMonAddMsg Message_DragClaim
MsgMonAddMsg Message_ReleaseEntity
</codeblock>

Similarly, a file could be created to report on messages in the Colour Picker Protocol:

<codeblock>
MsgMonAddMsg Message_ColourChoice
MsgMonAddMsg Message_ColourChanged
MsgMonAddMsg Message_CloseRequest
MsgMonAddMsg Message_OpenParent
</codeblock>

Calls to <command>*MsgMonAddMsg</command> are additive, so running these two Obey files in sequence would result in messages belonging to all three protocols being displayed. To remove messages from the list, the <command>*MsgMonRemoveMsg</command> command can be used in a similar way; in addition, <command>*MsgMonRemoveMsg -all</command> would clear the entire list and return <cite>MsgMon</cite> to reporting all messages that are sent. This could be used in the Obey files to make each file select just its own messages by including it before the new messages are added:

<codeblock>
MsgMonRemoveMsg -all
MsgMonAddMsg Message_ColourChoice
MsgMonAddMsg Message_ColourChanged
MsgMonAddMsg Message_CloseRequest
MsgMonAddMsg Message_OpenParent
</codeblock>

More details of the commands offered by <cite>MsgMon</cite> can be found in the section on <link ref="Config">Configuring the Module</link>.

</chapter>




<chapter title="Configuring the Module" file="Config">

<cite>MsgMon</cite> provides a number of *commands which can be used to control and interrogate its operation.

<comdef target="*MsgMonAddMsg" params="[-message] &lt;message code&gt;">

The command <command>*MsgMonAddMsg</command> is used to add a message to the list to be reported (with an empty list, all messages will be returned).

The &lt;message code&gt; parameter is a numeric Wimp message code in decimal (or hex, if preceded by &quot;&amp;&quot;), or a message name starting with <code>Message_</code>: for example, <code>1<code> or <code>Message_DataSave</code> would be equivalent.
</comdef>

<comdef target="*MsgMonRemoveMsg" params="[-message] &lt;message code&gt; | -all">

The command <command>*MsgMonRemoveMsg</command> removes a message or messages from the interception list.

If the &lt;message code&gt; parameter is used, then an individual message will be removed from the list: the code is a numeric Wimp message code in decimal (or hex, if preceded by &quot;&amp;&quot;), or a message name starting with <code>Message_</code>.

If -all is used, then all the messages in the list will be removed and <cite>MsgMon</cite> will start reporting on all messages again.
</comdef>

<comdef target="*MsgMonListMsgs" params="">

<command>*MsgMonListMsgs</command> will display a list of messages being reported by <cite>MsgMon</cite>; entries can be added or removed by <command>*MsgMonAddMsg</command> and <command>*MsgMonRemoveMsg</command> respectively.

An empty list indicates that all messages will be reported.
</comdef>

<comdef target="*MsgMonLoadMsgs" params="[-file] &lt;message file&gt;">

Load a new file of mappings between message numbers and names, used by <cite>MsgMon</cite> to look up messagee names passed to the <command>*MsgMonAddMsg</command> and <command>*MsgMonRemoveMsg</command> commands, and include names in the Reporter window. This will only be necessary if your system is using non-standard messages provided by third-party applications.

The file pointed to by &lt;message file&gt; is a simple RISC OS format text file, consisting of a one line per message. Each line consists of the message number in hex (with a leading &quot;&amp;&quot;) followed by a tab character (ASCII 9) and then the part of the message name following &quot;Message_"&quot;.

As an example, a file defining message &amp;1 as Message_DataSave and message &amp;400C0 as Message_MenuWarning would appear as follows (note that tabs have been replaced by spaces):

<codeblock>
&amp;1     DataSave
&amp;400C0 MenuWarning
</codeblock>

The standard file used by <cite>MsgMon</cite> can be found in ResourceFS at <file>Resources:$.ThirdParty.MsgMon.MsgList</file> when the module is loaded. This can be copied and used as a basis for updates if required; if you add any useful definitions, please consider submitting your amendments for inclusion in a future release.
</comdef>

</chapter>




<chapter title="Version History" file="History">

<subhead title="1.00 (20 May 2010)">

First public release.


<subhead title="1.01 (22 May 2010)">

Update to first public release.

<list>
<li>String copies terminate on NULL or LF to correctly handle the full range of task names returned by the Task Manager.
</list>


<subhead title="1.02 (12 July 2013)">

Update to first public release.

<list>
<li>Port from ExtBasAsm to ObjAsm/Asasm and restructure for cross-assembly.
<li>Fix broken workspace structure and remove unused memory allocations.
<li>Replace all non-X SWIs and fix error handling.
<li>Check for ARMv7 compatibility.
</list>


<subhead title="1.03 (1 September 2014)">

Update to first public release.

<list>
<li>Correctly terminate module title string.
<li>Correct 32-bit detection in exit code.
</list>


<subhead title="1.04 (30 August 2020)">

Update to first public release.

<list>
<li>Licence updated to EUPL&nbsp;v1.2.
<li><command>*MsgMonAddMsg</command> and <command>*MsgMonRemoveMsg</command> can take message names as well as numbers.
<li>Wrap message body lines in double-quotation marks to resolve problems with <cite>Reporter</cite> interpreting <code>\</code> characters.
<li>Replace <code>&quot;</code> with <code>.</code> in ASCII display, to avoid catching <cite>Reporter</cite> out. 
</list>

</chapter>




<literal mode="Text">

Updates and Contacting Me
-------------------------

  If you have any comments about MsgMon, or would like to report any bugs
  that you find, you can email me at the address below.

  Any updates to the module will be made available on my website, at
  http://www.stevefryatt.org.uk/software/msgmon/

  Stephen Fryatt
  email: steve@stevefryatt.org.uk
</literal>
