Amiga Format 8/af008.adf/Xoper/Xoper.doc

Text File | 1988-06-28 | 12.1 KB | 365 lines

                                 Xoper V1.3

                    Copyright (c) Werner Gunther 1989

Xoper is a freeware program to display and to control system activity.
Permition is granted to freely distribute this program.

--------------------------------------------------------------------------
Changes in V1.2:
New commands: Snoop, Capture, ClrCool, ClrWarm, ClrCold.
Added       : CPU usage by task.

Cancel command has been rewritten, some minor bugs removed.
--------------------------------------------------------------------------
Changes in V1.3:
New commands: [S]=Stack usage, Sort, Hide, Hidden, Header, Window,
              InputHandler.
Added       : Support of startup-scripts, I/O Interrupts/second, 'Kill' an
              alias for 'Cancel'.
Some BIG bugs have been removed: The port-display used to GURU if more than
32 Ports did exist. The Cli Xoper has been started did act like having a
priority of 128. Unlock didn't unlock sometimes, the interrupt/priority
field did contain rubbish, Currentdir didn't examine all Processes.
There were some more, minor bugs, all (hopefully) removed.
--------------------------------------------------------------------------

Starting Xoper from CLI:

Xoper [T] [F] [S] [L] [D] [R] [E] [M] [P] [I]

These parameters are described below. For all those who like long
Startup-Sequences, overcrowded memory and hot-keys enter

Xoper -b

This will install Xoper in background waiting for LeftAmiga-RightAmiga-X
to pop up. In both cases you don't have to RUN or RUNBACK Xoper, it will
always create its own process.

At startup Xoper loads and executes a file named S:Xoper.Startup if such a
file is available. This startup-script is used to set default values, the
window size or the initial default list to be displayed. The Xoper-window
will only be opened after the startup-script has been processed. Look at the
end of the document for a sample startup file.

Xoper Commands:
---------------

 Commands can be entered after the prompt '->', these are divided into two
groups:

Display commands: These are always single character entries and may be
specified in any order, upper or lower case, with or w/o embedded blanks,
after the prompt or from CLI as parameters:

T = Tasks (Default if Xoper is called without parameters)
Task node (HEX), Display type, status, priority (decimal), CPU usage
(percent), processnumber for Dos-Processes (decimal), taskname.

F = Task Flags
Task node (HEX), Allocated Signals (HEX), Signals the Task is waiting for
(HEX), Signals received (HEX), Address of the next instruction to be
executed (HEX).

L = Libraries
Base address (HEX), open count (decimal), version (decimal), revision
(decimal), flags (binary), libraryname.

D = Devices
Base address (HEX), open count (decimal), version (decimal), revision
(decimal), flags (binary), devicename.

E = Resident (sorry)
Base address (HEX), priority (decimal), flags (binary), version
(decimal), type, name.

R = Resources
Base address (HEX), open count (decimal), version (decimal), revision
(decimal), flags (binary), resource name.

M = Memory
Lower and upper bounds (HEX), bytes free (decimal), attributes, priority
(decimal), hunk name.

P = Ports
Node address (HEX), portname, flags, signal bit (decimal), queue length
[number of messages] (decimal), taskname.

I = Interrupts
Node address (HEX), pointer to interrupt data (HEX), pointer to interrupt
code (HEX), priority (decimal),type [interrupt queue the interrupt belongs
to], interrupt name.

S = Stack
Lower limit of the stack, stack size, currently used stacksize, taskname.
If you want to minimize your stack using this utility, please note that
Dos-functions use 1500 Bytes at the bottom of the Stack frame for their own
purposes and note that the stacksize is only checked one time per second by
this command.

H = Help ( or ?)
Show a list of commands.

; = NOP
Skip this line (used for remarks in a script file)

Q = Quit
Same as QUIT (see below).

Example: Entering TPM would display Tasks, Ports and Memory. The display
would be updated after a few seconds (5 by default, may be changed
anytime, see below.)

Other commands that do not display lists:
These commands may be entered upper or lower case. Parameters enclosed
in '<>' must be, enclosed in '[]' may be specified. Names are usually
entered as ascii-strings, it can however happen that two or more nodes of
the same name exist. On tasks you may specify the DOS-Processnumber to
sort them out. If everything fails, you can enter the Node-Address with a
leading '$'. This Address will be checked first before the command is being
executed. If the check fails, you'll get an error message or a warning or
a prompt, depending on what went wrong. Names are always the last parameter
to enter. This may seem strange, but it is the simplest way to get rid of
embedded blanks.

Time <seconds>
Set time between updates. Minimum is 1 second, maximum is 255, default is 5
seconds.
Example: Time 1

Taskpri <priority> [processnumber] <taskname>
Change the priority of a task. Values may range from -127 to 127, better
use values between -5 and 5.
Example: Taskpri 5 New Cli

Mypri <priority>
Shortcut for "Taskpri Xoper <priority>"
Example: Mypri 6

Pri <priority> <nodename>
Change the priority of any other node. This command does not work for Tasks.
If the specified node has been found, the entire list the node belongs to
will be resorted.
Example: Pri 1 Chip Memory        (try to allocate memory in CHIP first)

Break [processnumber] <taskname>
Set break signals. Useful for tasks running in background or from Workbench.
Example: Break 3 New CLI

Hunks [processnumber] <processname>
Show location, BCPL-Pointers and length of memory blocks the process uses.
Example: Hunks RAM

Snoop [processnumber] <taskname>
Track memory allocation/deallocation of a task. Press break (CTRL-C) to
stop. List includes: action (alloc/free), memory requirements (CHIP/ FAST/
PUBLIC etc), memory size, memory location (start, end) and the address from
where AllocMem() was called.

Files
List lock, access, size and name of open files.

Locks
List any lock.
BUG: Trying to lock the Volume "RAM Disk" crashes the machine sometimes. If
a Volume "RAM Disk" is found it will be replaced by the devicename "RAM:"
(this has been fixed on WB 1.3). Make sure you don't have a disk labeled
"RAM Disk" or you'll never see its locks:-)

Currentdir
List current directory settings of all processes.

Devices
List name,heads,sectors,tracks,startup-buffers and handler-process of every
DOS-device.

Inputhandler
Display node, priority and name (if any) of the input-handlers currently in
use.

Capture
Show vectors controlling the reset, i.e. CoolCapture, ColdCapture and
WarmCapture pointers, KickMem allocations. Useful when searching
for Viruses, but remember that the RAD: device in 1.3 uses the KickMem
pointer to recover from a reset.

ClrCool
ClrCold
ClrWarm
Clear one of those pointers.

Lockdrive <drivename:>
Prevent DOS, Workbench and Disk-Validator from cluttering on the drive.
This command isn't very useful, but I needed it myself. Please note that
the drivename is case sensitive and has to end with a ':'.

Freedrive <drivename:>
Re-enable a drive.

Windows
List address and title of all windows.

Screens
List address and title of screens.

Fonts
List address,height,width,type,fist character and last character of all
loaded fonts.

Windowfonts
List Windows and associated fonts.

Freeze [processnumber] <taskname>
Halt a Task. The task should be READY or WAITING. Frozen tasks are queued in
a new list called FROZEN. When you leave Xoper, halted Task will be
released.
Example: Freeze Killer Graphics Task

Warm [processnum] <taskname>
Restart a halted Task. Task must be FROZEN.
Example: Warm Killer Graphics Task

Hide <taskname>
The task-list tend to be longer than the window size. You may inhibit the
output of some tasks you are not interested in using his command.
Example: Hide trackdisk.device

Hidden
Turn those hidden Tasks back on. It actually is a toggle.

Header
Toggle the (rather long) header on the task display on/off.

Sort
The tasks listing is sorted (on V1.3 and above) to avoid 'jumping' of the
display. Sort toggles this feature on/off. (Stupid command, but was easy
to implement).

Info <librarynode | devicenode>
Show additional information stored in the lib_IdString field.
Example: Info arp.library

Openlib <libraryname>
Open a library. This is useful if you don't want a specified library being
'flushed' out.
Example: Openlibrary arp.library

Clear [longword]
Fill unused memory chunks with pattern, default is 0. Handy for debuggers.
Example: Clear $66726565

Flush
Clean up memory, flush unused libraries, devices and fonts.

Lastalert
Show last Guru Meditation code or rubbish.

Usage
Toggle CPUSE field on the task display between usage relative to all
possible dispatches and usage relative to actually dispatched tasks.
Ahem...not very clear I think. Well, let me try again...
If you add all CPUSE fields together you get 100 % (more or less 1%). After
entering "Usage" adding the fields together will give you the same value as
shown in the 'CPU Activity field'. (I HATE having to write docs)

Taskports
Disable / enable a listing of taskports if ports are displayed.

More
Stop displaying "<MORE>" and "<RETURN>" if output exceeds window.

Window <leftedge> [toptedge [width [height]]]
Works only on script files. Defines the window to be opened.
Example: Window 0 0 550 190

Quit or just Q
Exit Xoper. If Xoper was started with '-b' or if 'Hold' was specified it
will stay in background waiting for LeftAmiga-RightAmiga-X.

Hold
Exit Xoper but install a key-handler and stay in background. Window
settings and display commands are saved.

Exit
Clean up and quit.

!!!! WARNING: The next few commands are dangerous and 'dirty' !!!!!
!!!!!!!!!!!! don't use them if not strictly necessary !!!!!!!!!!!!!

Kill [processnumber] <taskname>
Kill a task or a process. If the task has been called from CLI, the Task
itself and the CLI will be killed. Hunks, Windows, Screens  and the
teminal-window will be freed. Simple tasks are just RemTask()'ed. If it is
not a CLI Task you'll be asked if it is a Workbench task, if the answer is
'Yes' unloading will be done by the Workbench. If not, you will be prompted
if Xoper should unload the code. Enter 'No' if you don't know how the task
has been started.

Closewindow <title>
Closes a Window. Please, use it only if the corresponding Task has been
'Cancel'ed. Use the Window-Structure address if the window has no name.

Closescreen <title>
same as above, but for screens.

Unlock <lock (BPTR)>
Unlock a file.

Closelib <libraryname>
This is exactly the same as CloseLibrary().

CD [processnumber] <processname>
Change the current directory of a process. You are prompted if the old
directory lock should be unlocked.

Signal <mask> [processnumber] <taskname>
Set any task-signal. Mask is a hexadecimal value with or w/o leading '$'.
See task's SIGWAIT field for sensible values. Tasks normaly do not wait for
signals only, but for messages, that's why this command may not have the
desired effect, but it is quite useful for tasks hanging around and waiting
for events that may never happen. Warning: Using Signal without any
knowledge about what you are going to signal may cause a system-crash!
Example: Signal 10000000 PopCLI III

----------------------------------------------------------------------------
;Sample Startup Script (to be placed in s:Xoper.Startup)
;
; Window definition on a overscanned + PAL Workbench screen
Window 122 0 550 230
;
;don't display some Tasks
;
Hide CON
Hide trackdisk.device
;
;but turn them on on Startup
;
Hidden
;
;Change the default list to Ports
;
P
;don't display any prompt if the window is full
More
----------------------------------------------------------------------------
I want to thank these people for helping me to debug and enhance the current
Version of Xoper:
Jeff White, Patrik Skottsborg, Michael Beer, Christian Balzer, Lars Soltau,
Heiko Rath and Bob Page.
Thanks.
----------------------------------------------------------------------------
Please send flames, bug reports and especially a list of features you would
like to have included in the next version to

 Werner Gunther
 Wingertspfad 12
 D 6900 Heidelberg
 (Germany)

or to my EMAIL address for a fast response:

 [e-mail]