Fresh Fish 5/FreshFish_July-August1994.bin/bbs/util/xoper-2.4.lha/Xoper-2.4/Xoper.doc

Text File | 1993-10-05 | 24.7 KB | 662 lines

                Xoper V2.3

            Copyright (c) Werner Gunther 1991

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.
---------------------------------------------------------------------------
Changes in V1.3b:
New commands: [C] information on CLI-Tasks.
Added        : 'Time 0' stops any update, System-Requesters are now handeled
          correctly (affects 'Kill' and 'Closewindow').
---------------------------------------------------------------------------
Changes in V2.0:
The 'user interface' (what user interface ?) has been rewritten from
scratch, and a small iconify routine has been added. To customize the whole
thing a little bit, there are a few new commands:
 MinimumChars, HistoryLines, ShowHistory, KillHistory, OutputLines,
IconifyOff, BackDropIcon, UseScreen, UseWindow.
Other new commands include:
TimerIO, RemResident, Repeat, TrapGuru, Setfont, DiskChange, Alias,
SaveOutput.
Addresses are now shown as 32-Bit values for 68020 compatibility. The 'More'
command is obsolete and has been removed. The 'interrupt list' has two new
fields. 'Time' w/o parameters shows current setting. 'display commands'
separated by blanks will display the lists one by one, instead of
displaying them all at once.
---------------------------------------------------------------------------
Changes in V2.1:
Mostly bug fixes:
 KS1.3 dependancy removed. Using UseScreen in the startup file could crash
the program if started with the -b flag. The S (stack) command wasn't
robust enought. Some strangness in the 'KILL' routine have been removed.
The iconizing routine couldn't distinguish between multiple drags and
doubleclicks.
Added: SetFKeys, Time accepts values < 1, 'Windows' shows the owner task (if
available). The task display shows the name of the loaded command
(enclosed in '[]') instead of the name, if the task is a CLI, 'CLICmd'
toggles this feature on/off. Commandline completion using <tab>.

A new program 'KillXoper' has been added to the distribution to remove
Xoper from memory in case it loops or freezes (I hope it won't be needed).
---------------------------------------------------------------------------
Changes in V2.2:
The 'KillXoper' routine has been put into Xoper's main program. Loaded CLI
commands are always displayed, not only in the task list.
---------------------------------------------------------------------------
Changes in V2.3:
General Fixes for WB2.0x, FPU and 680xx processors. A complete redesign
of the 'task usage' section, including a new display showing the total
amount of cpu-time by task.
Added new fields to the task, fonts, screen and cli display; scrollbars,
logging of open files and filelocks, a 'frags' like display.
The 'save' function appends its output to a file, toggeling commands may
be followed by 'on' or 'off' for clearer startup-scripts.
(the 68881 code was done by Lothar English)
---------------------------------------------------------------------------
Changes in V2.4:
Xoper now handles non-proportinal fonts bigger than 8x8 pixels correctly.
The old style can be forced with the new option 'usetopaz', Xoper will use
topaz/8 instead. Xoper now takes care of the screens barheight and window
border widths. Commandline completation now works at every position of the
inputline and cycles instantly. If running under Kick2.0+ Xoper clones the
default public screen and makes it's own screen public. Search for startup
script first in 'currentdir' then in 'env:' and last in 's:'. Older cmds as
'cancel','alert','remnode' and 'remintserver' now displayed in the help page.
The input-handler checking for Amiga-Amiga-x is now permanently installed.

Lots of bugs removed and major code cleanup.
---------------------------------------------------------------------------

Starting Xoper from CLI:

Xoper [kill] [-b] [T] [F] [S] [L] [D] [R] [E] [M] [P] [I] [C] [U]

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.

Xoper kill

will kill an already running Xoper task from outside, in case Xoper hangs or
guru's.

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 Window:
-------------
 The window (or screen if you request one) is devided into two sections: a
very small input line on the bottom and a large output area on the top. If
the output exceeds the size of the window you may scroll or 'page' through
the text using the num-pad keys:

A1000  A2000/A500
  7    Home        Top of display
  1    End        Bottom
  9    Pg Up        one page up
  3    Pg Dn        one page down
  8    Up Arrow    one line up
  2    Down Arrow    one line down
  4    Left Arrow    one page left
  6    Right Arrow    one page right

 The input section has some line editing facilities and a history buffer
contollable with the following keys (similar to NewCon and ConMan):

Cursor left        cursor one character left
Shift  left        cursor to the start of the next word
Cursor right        one character right
Shift  right        previous word
Cursor Up        previous line in history buffer
Shift  Up        top of buffer
Cursor Down        next line in history buffer
Shift  Down        bottom of buffer
DEL            DEL
BS            backspace
Ctrl   X        delete line
Ctrl   Y        delete EOL
Ins   (numpad '0')      toggles insert mode (default is 'on')
Del   (numpad '.')      same as DEL

ESC            moves the input area from the bottom into the
            output section. Entering a command here (i.e
            overwiting an output line), will cause Xoper to add
            the address of that node to your command line.
            Example: Show the hunks of a 'File.System' process:
            type 'T' to get a list of all tasks, press <esc>,
            move the cursor to the line displaying the
            File.System process and type 'Hunks <enter>'. Press
            <enter> once more to return to the usual Xoper
            display.
Help            displays a help panel.
TAB            Command line completion.
            Example: press <c>, hit <tab> several times.

The Xoper window has, beside the usual closewindow and depth-arrange
gadgets, a custom gadget on its title bar, used to iconify Xoper. The icon
may be moved anywhere on the screen just by dragging it, double clicking
the icon will restart the program. The window itself is a simple_refresh
window, so it may look a little bit sluggish when it needs a refresh.

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

Commands are entered in the command line at the bottom of the window,
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, after the prompt or from CLI
as parameters. If more than one list has to be displayed, you may enter
several commands in one line. Separating them with blanks displays the lists
one by one instead of showing them all at once.

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 (or the
name of the loaded command, if a CLI process. The loaded command name
is enclosed in '[]'), stdin and stdout (enclosed in ()), devicename
(enclosed in {}), if the process is a handler and unit number if the process
is a device.

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).

U = cpu usage
Task node (HEX), state, when it was started, the total amount of CPU time
it used, processnumber, taskname.

C = Cli Commands
Task node (HEX), Type (interactive/batch), Mode (Background/Foreground),
CLI number, CLI name, program it executes.

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),[T]ype ([S]erver/[H]andler), [S]tate
([E]nabled/[D]isabled), 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 EXEC 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 0.1 seconds, maximum is 255.9, default
is 5 seconds. Time 0 stops automatic update and waits for a keypress. Values
 < 0.5 are not recommended.
Example: Time 1.5

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 1 New Cli

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

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.

TraceOpen
TraceLock
Monitors dos calls to Open() and Lock(). Press break to stop.

Zerotimer [processnumber] <taskname>
Reset the used time counter on the cpu usage display. This is useful if
benchmarking a cli command.

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.

Frags
Conts free memory hunks by size. Displays the size in hex and decimal,
number of hunks, largest available hunk.

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.

TimerIO
Display pending timer requests. It shows the address of the
IORequest-structure, the unit (MICROHZ or VBLANK), the time to complete (up
to 255 secs) and the task submitting the request.

RemResident <resident module name>
Kicks the resident module out of the ResModules-List. It does not free the
module itself, but only makes sure it won't be reactivated during the next
reset. Removing a ROM-based module does not have any effect.

Repeat <Command string>
Repeats the command string at the current refresh rate (see 'Time').
However, commands not producing any output won't be repeated, but only
executed once. Press <enter> to stop.
Example: Time 1
     Repeat TimerIO

TrapGuru
Activates a trap handler similar to GOMF. It only works with a 68000
processor, as it relys on a specified stack frame (at least I think so,
couldn't check it out). If an exception occurs (i.e. GURU) Xoper will
stop (or popup, if running in background) and display some information
about what happened (the taskname causing the error, its program counter,
the alert number etc.) and you'll be asked if you want to (K)ill the task
or (I)gnore the exception. Choosing (i)gnore will do nothing at all if the
erroneous program was a process (as it will stop itself displaying a
'Task held...' requester), but force a task to execute a 'Wait(0L)' (i.e.
wait forever) as tasks do directly display an alert box.

Alias <AliasName> <CommandName>
Defines a new name to be used along with the original command name. The new
name should not contain any blanks. To delete an existing alias use the
<AliasName> without a commandname.
Example: Alias ih InputHandler

SetFKey <key number> <string>
Assign a string to a funktion key. 'Key number' is a value between 1-20,
10-20 denotes shifted keys. Use '^' to simulate a <return> and '_' for
space (the parser strips leading/trailing blanks).
Example: SetFKey 1 Hunks^
     enter t <return>, press <escape>, move the cursor to a process,
     press F1

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.

DiskChange
Show all installed diskchange interrupts. It displays the node, data and
code fields of the interrupt, the device it is attached to (df0:-df3:) and
the task which added the interrupt (if available). The main purpose for
this command is to check for a virus, as the diskchange interrupt is a
wonderful place to install them.

Windows
List address and title of all windows.

Screens
List address size, depth and title of screens.

PubScreens (Kick 2.0+)
Show all currently existing public screens

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

Windowfonts
List Windows and associated fonts.

SetFont [size] <fontname> <window>
Change the default font of a window. To avoid confusion, you should use a
font with the same font size as the original font, as many programs rely on
the point size.
Example: Windows
     Press <esc>, move the cursor to the Xoper window line and type
     Setfont diamond.font
     (now you know what I mean by 'relying on a font size' :-))

 ->new: Xoper handles EVERY non-proportional font correctly. Xoper doesn't
    requires topaz eight any more!

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

SmartPatch
Xoper has to patch some system functions. If Xoper is forced to quit it checks
that no other program patched the same functions. In this case we have to wait
until the other proram(s) end for safe restoring the patched library vectors.
But if you use 'SaferPatches' by Martin Adrian you can quit though the vectors
are patched again because SaferPatches keeps track of the right order functions
has been changed. This works only if library vectors are changed via the exec
SetFunction(). DO NOT alter library vector by your self !!!.
If you do not have SaferPatches or similar switch this option on.

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 is actually 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).

CLICmd
Toggles between showing the loaded command and the taskname of CLI processes
in the tasks listing.

taskinfo
toggles additional process information (unitnumber, stdio, devicename) on
and off.

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

CxHandler
Turn the commodity broker on or off. This command decides if the hotkey
activation comes from the inputhandler (Kick 1.3 style) or from the commodity
broker (Kick 2.0+ style). If we could install Xoper as commodity the commodity
is active and the inputhandler is disabled. The actual hotkey description is
always displayed in the window title. This description can be changed for the
commodity with the 'popkey' command (see below). The inputhandler hotkey is
hard coded.
This command has no effect Kickstarts below 2.0 !

PopKey
Change the hotkey description for our commodity. With the hotkey you can popup
Xoper if it is in sleep mode or simply pop it's window (including screen) to
front. See for instance 'Toolmanger.doc' for a complete key description (sorry!)
By default the hotkey is 'Lcommand - Rcommand - X' ( means press left amiga,
right amiga and x at the same time).

Openlib <libraryname>
Open a library. This is useful if you don't want a specified library being
'flushed' out.
Example: Openlib 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.

Alert
Show last Guru Xoper caught.

Lastalert
Show last Guru Meditation code or rubbish. (information obtained by exec)

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.

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

IconPos <leftedge> [toptedge [width [height]]]
Defines the initial position of xoper's icon. Used in the startup script.

HistoryLines <number of lines>
Set the maximum number of input lines the history buffer should hold.
Default is 10 lines.

MinimumChars <number of characters>
Set the minimum number of characters an inputline should have to be added to
the history buffer.
Default is 2 characters.

ShowHistory
Show the history buffer. (quite useless, I know)

KillHistory
Delete all lines from the history buffer. (still useless)

OutputLines <number of lines>
Set the maximum number of lines the output buffer may hold. If the buffer
overflows, a line from the top of the buffer will be deleted for each new
line.
The default value is 500, using a maximum of 500 * 104 = 52000 bytes.

SaveOutput <filename>
Write the contents of the output buffer to a file. If the file already
exists, the output will be appended.

Iconify
Turns the iconify on or off. A small window or an appicon will appear if
iconify is on.

BackDropIcon
Puts the Xoper icon behind all other windows, instead of creating it on top
of them.

PropGad
Turns the scrollbar on or off (as you like)

UseScreen
Opens Xoper on a screen. The new screen will take its data (width, colors,
viewmodes etc.) from the Workbench screen and open a borderless backdrop
window on it.

UseWindow
Opens Xoper on a window.

UseTopaz
By default Xoper uses the system default font in it's window. UseTopaz toggles
between this default font or topaz eight. There is a trick to flip between
the system default font and EVERY other (mono-spaced prefered) font. This can
be done with the 'SetFont' command (see above). Now you can flip between your
selected font and the system default font. This selection stays valid until the
window will be closed. UseTopaz acts as an toggle. You can specify 'on' or
'off' to force a desired state.


Quit or just Q
see Hold below

Hold
Exit Xoper but stay in background. When Xoper pops up window settings and
the selected display are restored.

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> (cancel is a synonym or vice versa ...)
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. A good example for tasks that should NEVER be unloaded are
programs started by ARP'S ASyncRun (or ARun).

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.

RemNode <node address>
remove a node from a list.

RemPort <port address>
remove a port from exec's port list.

RemIntServer <interrupt address>
Remove a interrupt server.

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 normally 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
----------------------------------------------------------------------------
Email:
[e-mail]