Explorer 1.6j
=============
Allows you to browse around memory as E objects (which are like C structs).
(Minor update to 1.5j, a small bug-fix for v37/8 compatibility.)
Basic Function
--------------
You enter an address and then select the object which is (supposed to be?)
at that address. You can then see the value that each element of the
object takes, and follow pointers etc. by double-clicking on the element (a
single click changes the address to the element's address, which is an
offset from the address you specified for the object).
A double-click may therefore change the object being browsed, so there is a
way of returning to the original object via the "Back Up" button. As you
double-click and select new objects your choices are recorded. The current
depth of this path is shown as the 'Depth:' text. The action of the
"Back Up" button is duplicated by the "Back Up" menu item on the
"Selections" menu. There is also an option to clear the current path on
this menu.
The list of objects may be created in several ways (these are found on the
"Project" menu):
1) "Load." Scan the selected module or all the modules in the selected
directory and its sub-directories. The found objects will
replace any current list of objects.
2) "Merge." Same as 1) but any objects found are added to the current
list of objects rather than replacing them.
3) "Load Cache." Same as 1) but the current E module cache is scanned.
This is most useful when Explorer is used to help debug
your programs.
The address and object can also be specified via ARexx, making Explorer an
extremely useful debugging tool as well as a system browser! (A module is
supplied to show how easy it is to integrate the appropriate ARexx call
into your program.)
Object Layout
-------------
The elements of the selected object are listed in order. If you choose to
see the value of element it will be displayed in hex in parenthesis after
the element, and if you choose to see the element address (an offset from
the object address) it will be displayed after an '@'. (Use the
"Selections" menu to decide which, if any, you want to see.)
Where to Start
--------------
Explorer starts off with the address of an internal hail and copyright
string. The items on the "Presets" menu give some other, interesting
starting points:
1) "Dos." Views the address stored in the 'dosbase' global variable as
a 'doslibrary' object. The dos.library is one of the
fundamental Amiga system libraries, and 'dosbase' is its
corresponding library base object.
2) "Exec." Same as 1) but for the 'execbase' variable and object for the
exec.library (the most fundamental Amiga system library).
3) "Graphics." Same as 1) but for the 'gfxbase' variable and object for
the graphics.library.
4) "Intuition." Same as 1) but for the 'intuitionbase' variable and
object for the intuition.library.
5) "This Process." Views the 'process' object for the running Explorer
program!
For a typical Explorer session, you would probably start at one of these
points and then double-click on elements and use the "Back Up" button to
browse around. You never really need to set the address explicitly on the
GUI (at worst you'd do it by ARexx), but the option is there if you really
want to...
Simple Types
------------
The "CHAR", "INT" and "LONG" buttons view the contents of the address as if
it were a pointer to the corresponding type, and fills in the 'Hex:',
'Decimal:' and 'String:' texts with the value(s) being pointed at.
"BSTR" is similar to "CHAR" but it first converts the address from a BCPL
pointer and then skips over the length byte. "BADDR" just converts the
address to a BCPL pointer.
"--" and "++" treat the address as if it were pointing to an array of the
type last requested (i.e., an object or simple type). "--" moves the
address back to the previous element in the array, and "++" moves it on to
the next. The size of the last requested type is shown as the 'Size:'
text.
Display Beeps!
--------------
The screen will flash (or you'll get a beep or whatever your Workbench is
set up to do) if you do one of the following:
1) Select something when the address is NIL (zero). A NIL address is not
valid (although Explorer will behave as if it were).
2) Select an element which is a NIL pointer or a LONG that is NIL.
3) Select an element with object or PTR TO object type, where the object
is not in the current list of objects.
4) Backup past a depth of zero.
Command Line Options
--------------------
The command line template is 'OBJECT,ADDR,ALL/S,CACHE/S,NONE/S'.
1) 'OBJECT' Specify an initial object to be displayed (to be useful, the
appropriate module must also be loaded using 'ALL' or
'CACHE').
2) 'ADDR' Specify an initial address to be displayed (NIL is ignored!).
3) 'ALL' Load all objects from the modules in Emodules: and its
sub-directories.
4) 'CACHE' Load all objects from the modules in the current E module
cache.
5) 'NONE' Start with no objects (overrides 'ALL' and 'CACHE').
By default, no objects will be loaded and the starting address will be that
of an internal hail and copyright string (which will be displayed as the
'String:' text).
ARexx
-----
The "Reply" menu item on the "ARexx" menu manually replies to an ARexx
message that may have been received. You can also let Explorer
automatically reply to these messages by checking the "Auto Reply" option,
but the manual method is best since you can be sure that the pointers
remain valid while you browse (since the calling program is halted). Once
you've replied to a message the calling program is free to scribble all
over the memory at the address it just gave you...
A module 'sendexplorer' is supplied to simplify the debugging facilities of
Explorer. It defines a single function, 'sendExplorer', which you call
with the address and object name you are interested in. The third,
optional parameter is a message port for replies. If you don't supply this
then a temporary port is created for the duration of the function call.
(The purpose of this parameter is to allow you to re-use the same port
during your program if you call 'sendExplorer' a lot.) An example call is:
sendExplorer(packet, 'dospacket')
To browse using your own objects you'd separate them out into modules and
load these modules in your program. Compiling your program would add these
to the E module cache, which can then be used to set-up Explorer (using the
"Load Cache" menu item). Alternatively, you could "Load" or "Merge" the
appropriate module directly.
Example Program
---------------
To show how useful Explorer can be, there is a modified version of the
'empty' handler supplied. This uses the above call to 'sendExplorer' to
communicate the value of the packet currently being processed. Since the
handler is not a full process (it's just a task) there would normally be no
simple way of debugging it or examining the packets as they arrive (none of
the DOS functions, such as printing text, are available to simple tasks).
However, the handler can send messages to ARexx and thus to Explorer.
To try it out:
1) Make sure ARexx is up (by running RexxMast, if necessary).
2) Start up Explorer using,
run explorer all
3) Now copy the 'empty-handler' to L:,
copy empty-handler L:
4) Mount it using,
mount empty: from empty.mountlist
5) Use the handler,
type empty:10
6) Look at Explorer. It will be displaying the first packet. Browse
around it, remembering that most elements will be BCPL strings.
7) Select "Reply" from the ARexx menu (or press RAmiga-R) to reply to this
message.
8) Another packet arrives and the message is sent to Explorer.
9) Repeat 6)-8) until the 'type' command finishes and you get the Shell
prompt back.
|
aminet net>