Figure 4-0

Display 4-0

SwatDisplay 4-0

Table 4-0
Table 4-1 Memory Modes

Mode	Size	1st column		2nd column		3rd column

b	byte	hex byte		signed dec		ASCII character

w	word	hex word		unsigned dec		signed decimal

d	dword	segment:offset		signed dec		symbol

i	???	hex bytes		assembler instr.
4Swat Reference

Revision:  l

This chapter is intended to provide documentation for the majority of useful 
Swat commands. The general structure of the descriptions in this chapter 
will be as follows:

Usage:	Shows the command and its various arguments and subcommands (if any).

Examples:	Examples of the command as it could be used.

Synopsis:	Summary of the command and its functions and results.

Notes:	Details about the subcommands, arguments, and other command features.

See Also:	Other related commands.

	4.1	Notation

The descriptions of the Swat commands will follow the following notational 
conventions:

u	command (alternative1|alternative2|...|alternativeN)
() The parentheses enclose a set of alternatives separated by a vertical 
line. For example, the expression quit (cont|leave) means that either 
quit cont or quit leave can be used.

u	command [optional_argument]
[] The brackets enclose optional arguments to the command. For 
example, the command alias [<word[<command>]>] could have zero, 
one, or two arguments because the <command> and <word> arguments 
are optional. Another example would be the command objwalk 
[<addr>], which may take zero arguments if it is meant to use the 
default address, and one argument if the user gives it a particular 
address to look at.

u	command <type_of_argument>
< > The angled brackets enclose the type of an argument rather than the 
actual string to be typed. For example, <addr> indicates an address 
expression and <argument> indicates some sort of argument, but 
(addr|type) means either the string addr or the string type.

u	*   +
An asterisk following any of the previous constructs indicates zero or 
more repetitions of the construct may be typed. An addition sign 
indicates one or more repetitions of the construct may be used. For 
example, unalias word* can be the unalias command by itself, or it can 
be followed by a list of words to be unaliased.

	4.2	Swat Reference

n	_print



Usage:	_print <expression>

Examples:	

"_print ax-10"
print ax less 10 decimal.

Synopsis:	Print the value of an expression.

Notes:	The difference between this command and the "print" command is a subtle 
one: if one of the arguments contains square-brackets, the Tcl interpreter will 
attempt to evaluate the text between the brackets as a command before 
_print is given the argument. If the text between the brackets is intended to 
be an array index, the interpreter will generate an error before the Swat 
expression evaluator has a chance to decide whether the text is a nested Tcl 
command or an array index.

 For this reason, this function is intended primarily for use by Tcl procedures, 
not by users.

See Also:	print, addr-parse.

n	abort



Usage:	abort [<frame-number>]
abort [<function>]

Examples:	

"abort"	 abort executing the current frame.

 "abort 3" 	abort executing up through the third frame.

 "abort ObjMessage" 
abort executing up through first ObjMessage.

Synopsis:	 Abort code execution up through a given frame or routine. By "abort", we me 
"do not execute". This can be quite dangerous, as semaphores may not be 
ungrabbed, blocks not unlocked, flags not cleared, etc., leaving the state of 
objects, and if executing system code, possibly the system itself in a bad state. 
This command should only be used when the only alternative is to to detach 
(i.e. in a fatal error) as a way to possibly prolong the usefulness of the 
debugging session.

Notes:	

u	If no argument is given, code through the current frame is aborted. 

u	<frame num> are the numbers that appear at the left of the backtrace.

See Also:	finish, backtrace, zip.

n	abortframe



Usage:	abortframe <frame-token>

Examples:	

"abortframe $cur"
Abort all code execution through the frame whose token is in 
$cur.

Synopsis:	Aborts code execution up through a particular stack frame. As no code is 
executed, the registers may be in a garbaged state.

Notes:	

u	The argument is a frame token, as returned by the "frame" command.

u	No FULLSTOP event is dispatched when the machine actually aborts 
executing in the given frame. The caller must dispatch it itself, using the 
"event" command. For information about FULLSTOP events, see the 
event Tcl command.

u	The command returns zero if the machine aborted executing in the given 
frame; non-zero if it was interrupted before that could happen. 

n	addr-parse



Usage:	addr-parse <addr> [<addr-only>]

Examples:	

"addr-parse *ds:si" 
Parse the address "*ds:si" into its handle, offset and data-type 
components. In this case, the data-type will be "nil".

 "addr-parse ILLEGAL_HANDLE 0" 
Figures the value for the enumerated constant 
"ILLEGAL_HANDLE". The handle for this non-address will be 
"value".

Synopsis:	This command parses the address expression into its components, returning 
a list {<handle> <offset> <type> } as its value.

Notes:	

u	This will generate an error if there's an error parsing the <addr> 

u	<handle> is the token for the handle in which the address resides, or "nil" 
if the address is absolute. This token can be given to the "handle" 
command for further processing. 

u	<offset> is a decimal number and is the offset of the address within the 
block indicated by the <handle> token. If <handle> is "nil", this can be a 
32-bit linear address. 

u	<type> is a type token for the data at the given address, if any could be 
determined. For example the address "ds:bx" has no type, as it's just a 
memory reference, but "ds:bx.VDE_extraData" will have whatever type 
the structure field "VDE_extraData" possesses. This token can be passed 
to the "type" or "value" commands for further processing.

u	If the expression doesn't refer to data that can be fetched from the patient 
(e.g. "foo*3") <handle> will be returned as the string "value" instead of a 
normal handle token. <offset> is then a value-list for the resulting value, 
and <type> is the type description by means of which the value list can 
be interpreted. 

u	The optional <addr-only> argument is zero or non-zero to indicate the 
willingness or unwillingness, respectively, of the caller to receive a value 
list in return. If <addr-only> is absent or non-zero, any expression that 
can only be expressed as a value will generate an error. The single 
exception to this is if the expression involves pointer arithmetic. For 
example "pself+1" normally would be returned as a value list for a far 
pointer, as the result cannot be fetched from the PC. When <addr-only> 
is absent or non-zero, "addr-parse" pretends the expression was 
"*(pself+1)", allowing simple specification of an address by the user for 
those commands that just address memory.

u	The <offset> element of the returned list is very useful when you want to 
allow the user to give you anything, be it a register or a number or an 
enumerated constant or whatever. You can pass the argument you were 
given to [index [addr-parse $arg] 1] and end up with an appropriate 
decimal number. Be sure to pass <addr-only> as 0, however, or else you'll 
generate an error. 

See Also:	value, handle, type.

n	addr-preprocess



Usage:	addr-preprocess <addr> <seg-var> <off-var>

Examples:	

"addr-preprocess $args s o" 
Parse the address expression in $args, storing the segment 
portion in $s and the offset portion in $o in the current scope.

Synopsis:	Preprocesses an address expression into a form that is easier to manipulate 
and faster to reparse.

Notes:	

u	<seg-var> is the name of a variable in the caller's scope in which the 
segment of the address is stored. It should be treated as opaque, as it may 
or may not be numeric. 

u	<off-var> is the name of a variable in the caller's scope in which the offset 
of the address is stored. This will always be numeric. 

u	Returns the 3-list returned by addr-parse, in case you have a use for the 
type token stored in the list. 

See Also:	addr-parse.

n	addr-with-obj-flag



Usage:	addr-with-obj-flag

Examples:	

"var addr [addr-with-obj-flag $addr]" 
If $addr is "-i", returns the address of the current implied grab.

Synopsis:	This is a utility routine that can be used by any command that deals with 
objects where the user may reasonably want to operate on the leaf object of 
one of the hierarchies, or the windowed object under the mouse. It can be 
given one of a set of flags that indicate where to find the address of the object 
on which to operate.

Notes:	

u	Special values accepted for <address>:

           Value 	Returns address expression for-

            -a 	the current patient's application object

            -i 	the current "implied grab": the windowed object over which the 
mouse is currently located

            -f 	the leaf of the keyboard-focus hierarchy

            -t 	the leaf of the target hierarchy

            -m 	the leaf of the model hierarchy

            -c 	the content for the view over which the mouse is currently 
located

            -kg 	the leaf of the keyboard-grab hierarchy

            -mg 	the leaf of the mouse-grab hierarchy

u	If <address> is empty, this will return the contents of the local variable 
"oself" within the current frame, if it has one, or *ds:si 

u	If <address> isn't one of the above, this just returns <address>. 

See Also:	impliedgrab, content, focusobj, targetobj, modelobj, keyboardobj, mouseobj.

n	alias



Usage:	alias [<name> [<body>]]

Examples:	

"alias p print" 
Execute "print" when the user types the command "p". Any 
arguments to "p" get passed to "print" in the order they were 
given.

 "alias while {for {} $1 {} $2}" 
Executes an appropriate "for" loop when the "while" command 
is executed with its two arguments: a test expression and a 
body of commands to execute. 

"alias" 	Prints all the defined aliases.

"alias while" 
Prints what the "while" command is aliased to.

Synopsis:	 This is a short-cut to allow you to make commands you commonly type easier 
to use, and to define simple new commands quickly.

Notes:	

u	If you give no arguments the current aliases are all displayed.

u	If you give a single argument, the name of an existing alias, the command 
that will be executed when you use the alias is printed.

u	The <body> string is usually in curly braces, as it usually involves 
whitespace and can contain newlines for the longer aliases.

u	You can use the pseudo-variables $1, $2, etc. in the <body> to represent 
the 1st, 2nd, etc. argument given when the alias is invoked. They are 
pseudo-variables as the "var" command will not operate on them, nor are 
they available to any procedure invoked by the alias.

u	You can also interpolate a range of the arguments using $<start>-<end>. 
If you do not give an <end>, then the arguments from <start> to the last 
one will be interpolated.

u	$* will interpolate all the arguments.

u	$# will interpolate the actual number of arguments.

u	If you do not use any of these pseudo-variables, all the arguments given 
to the alias will be appended to the <body>.

u	Interpolation of the values for these pseudo-variables occurs regardless 
of braces in the <body>.

u	It is an error to specify an argument number when there are fewer than 
that many arguments given to the alias.

See Also:	unalias.

n	alignFields



Usage:	var alignFields [(0|1)]

Examples:	

"var alignFields 1" 
Sets the "print" command to align the values for all the fields of 
a given structure.

Synopsis:	Determines whether structure-field values follow immediately after the field 
name or if all values are indented to the same level. The "print" command 
and other display commands use this variable when formatting their output.

Notes:	

u	Having all values indented to the same level makes it easier for some 
people to locate a particular field in a structure. It is not without cost, 
however, in that Swat must determine the length of the longest field 
name before it can print anything. 

u	The default value for this variable is zero.

See Also:	print.

n	antifreeze



Usage:	antifreeze <patient>
antifreeze :<n>
antifreeze <patient>:<n>
antifreeze <id>

Examples:	

"antifreeze term"
Promotes the application thread for "term" to be the 
"most-runnable"

"antifreeze :1"
Does likewise for thread #1 of the current patient

"antifreeze 16c0h" 
Does likewise the thread whose handle is 16c0h

"antifreeze"	Promotes the current thread to be the "most-runnable."

See Also:	freeze 

n	antithaw



Usage:	antithaw <patient>
antithaw :<n>
antithaw <patient>:<n>
antithaw <id>

Examples:	

"antithaw term"
Allows the application thread for "term" to run normally.

"antithaw :1"
Allows thread #1 of the current patient to run normally.

"antithaw 16c0h" 
Allow the thread whose handle is 16c0h to run normally.

See Also:	thaw

n	appobj



Usage:	appobj [<patient>]

Examples:	

"pobj [appobj draw]" 
prints the GenApplication object for draw.

"pobj [appobj]"
prints the GenApplication object for the current application 
(equivalent to "pobj -a").

Synopsis:	Returns the address of the GenApplication object for the given patient, or the 
current one if you give no patient.

See Also:	impliedgrab.

n	apropos



Usage:	apropos [<string>]

Examples:	

"apropos vis" 
Find all commands related to vis

 "apropos text" 
Find all commands related to text 

Synopsis:	Search the list of commands and command help for all entries containing 
<string>. Lists each command and its synopsis. 

Notes:	<string> may actually be a pattern, as described in the help for the "string" 
command (under "string match"). It automatically has a leading and 
following * tacked onto it to cause it to match anywhere within a help string.

See Also:	help.

n	aset



Usage:	aset <array-name> <index> <value>

Examples:	

"aset foo $i $n"
Sets the $i'th element (counting from zero) of the value stored 
in the variable foo to $n.

Synopsis:	Allows you to treat a list stored in a variable as an array, setting arbitrary 
elements of that array to arbitrary values.

Notes:	

u	<array-name> is the name of the variable, not the value of the variable 
to be altered.

u	This command returns nothing.

u	The index must be within the bounds of the current value for the 
variable. If it is out of bounds, aset will generate an error.

See Also:	index.

n	assoc



Usage:	assoc <list> <key>

Examples:	

"assoc $classes GenPrimaryClass"
Examines the sublists of $classes and returns the first one 
whose first element is the string GenPrimaryClass.

Synopsis:	 Searches an associative list to find an element with a particular key. The list 
is itself made up of lists, each of whose first element is a key.

Notes:	

u	 A typical associative list is made of key/value pairs, like this:
 {{<key> <value>} {<key> <value>} ...}

u	 If an element is found whose <key> matches the passed <key>, the entire 
element is returned as the result. If no <key> matches, nil is returned.

See Also:	car, cdr, range, list, delassoc.

n	assign



Usage:	assign <addr> <value>

Examples:	

"assign ip ip+2" 	
Add 2 to the value of IP in the current frame.

 "assign {word ds:si} 63h" 
Store 63h in the word at ds:si

Synopsis:	Performs an assignment to a patient variable or register (but not to an 
element of the value history). The first argument is the variable or register 
to be assigned and the second argument is the value to assign to it (which 
may be a regular address expression). If the first expression doesn't indicate 
a type, "word" is assumed. Only byte, word or dword types are supported.

Notes:	

u	When assigning to an sptr, the value assigned will be the segment of the 
block indicated by the <value>, unless <value> is an absolute address (or 
just a number), in which case the low 16 bits of the offset will be used 
instead.

u	Similar behavior occurs when assigning to an fptr, except if the <value> 
is an absolute address, in which case the linear address in the offset 
portion of the <value> will be decomposed into a segment and an offset.

See Also:	imem, value

n	att



Usage:	att [<args>]

Examples:	

"att"	attach Swat to GEOS.

Synopsis:	Attach Swat to GEOS.

Notes:	The args argument can be one of the following:

-s	reboot GEOS with error checking, attach, and stop

-sn	reboot GEOS without error checking, attach, and stop

-f	restart GEOS with error checking and attach after a pause

-r	restart GEOS with error checking and attach

-rn	restart GEOS without error checking and attach

See Also:	detach, quit.

n	attach



Usage:	attach [<boot>]

Examples:	

"attach"	attach to the target PC

Synopsis:	Attach swat to the target PC.

Notes:	

u	The boot argument is "-b" to bootstrap and "+b" to not. Normally, Swat 
will try to read symbolic information about all running geodes; 
bootstrapping specifies that Swat should only read symbolic information 
for these geodes when it must. 

u	If you give no <boot> argument, swat will use the most-recent one.

u	By default, swat will locate the symbols for all geodes and threads active 
on the PC when it attaches.

u	If any geode has changed since you detached from the PC, its symbols are 
re-read.

See Also:	att, detach, quit.

n	autoload



Usage:	autoload <function> <flags> <file> [<class> <docstring>]

Examples:	

"autoload cycles 1 timing"
load the file "timing.tcl" when the cycles command is first 
executed. The user must type the command completely.

"autoload print 2 print"
load the file "print.tcl" when the print command is first 
executed. The user may abbreviate the command and the Tcl 
interpreter will not evaluate its arguments.

Synopsis:	This command allows the first invocation of a command to automatically 
force the transparent reading of a file of Tcl commands.

Notes:	

u	autoload takes 3 or 5 arguments: the command, an integer with bit flags 
telling how the interpreter should invoke the command, the file that 
should be read to define the command (this may be absolute or on 
load-path) and an optional help class and string for the command.

u	The help class and string need only be given if the file to be loaded isn't 
part of the system library (doesn't have its help strings extracted when 
Swat is built).

u	The <flags> argument has the following bit-flags:

0	User must type the command's name exactly. The command 
will be defined by "defsubr" or "defdsubr" when <file> is loaded.

1	The interpreter will not evaluate arguments passed to the 
command. All arguments will be merged into a single string 
and passed to the command as one argument. The command 
will use the special "noeval" argument when it is defined.

See Also:	defsubr, defdsubr, defcommand, proc.

n	backtrace



Usage:	backtrace [-r<reg>* ][<frames to list>]

Examples:	

"backtrace"	print all the frames in the patient

"backtrace -rax"
print all the frames and the contents of AX in each one.

"where 5"	print the last five frames

"w 5"	print the last five frames

Synopsis:	Print all the active stack frames for the patient.

Notes:	

u	The <frames to list> argument is the number of frames to print. If not 
specified, then all are printed.

u	If a numeric argument is not passed to backtrace then it attempts to 
display method calls in the form:

        MSG_NAME(cx, dx, bp) => className (^l####h:####h)

	      Here <cx>, <dx>, and <bp> are the values passed in these registers. 
<className> is the name of the class which handled the message. 
^l####h:####h is the address of the object (block, chunk handle) 
handling the message.

u	If a numeric argument is passed to backtrace then the attempt to decode 
the message is not done and the single line above expands into:

       			 far ProcCallModuleRoutine(), geodesResource.asm:476
			 near ObjCallMethodTable(), objectClass.asm:1224

	      This is generally less useful, but sometimes it's what you need. 

See Also:	up, down, func, where.

n	bindings



Usage:	bindings

Synopsis:	Shows all current key bindings

n	bind-key



Usage:	bind-key <ascii_value> <function>

Examples:	

"bind-key \321 scroll_srcwin_down"
Binds scroll-down key to the scroll_srcwin_down Tcl routine.

Synopsis:	Binds an ASCII value to a function.

See Also:	alias, unbind-key.

n	break

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	break-taken



Usage:	break-taken [<flag>]

Examples:	

"break-taken"	
Returns 1 if the machine stopped because of a breakpoint.

"break-taken 0"
Specify that no breakpoint was actually taken to stop the 
machine.

Synopsis:	Obscure. This is used to determine if the machine stopped because a 
breakpoint was hit and taken.

Notes:	Setting the break-taken flag is a rather obscure operation. It is useful 
primarily in complex commands that single-step the machine until a 
particular address is reached, or a breakpoint is taken when a breakpoint 
must be used to skip over a procedure call, or condense multiple iterations of 
an instruction with a REP prefix into 1. For an example of this use, refer to 
the "cycles" command. 

See Also:	brk, irq.

n	brk

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	brkload



Usage:	brkload [<handle>] 

Examples:	

"brkload Interface" 
Stop the machine when the Interface resource is loaded or 
swapped in.

 "brkload bx"	Stop the machine when the resource whose handle ID is in BX 
is loaded or swapped in.

 "brkload" 	Stop watching for the previously-specified resource to be 
loaded.

Synopsis:	Stop the machine when a particular resource is loaded into memory.

Notes:	

u	Only one brkload may be active at a time; registering a second one 
automatically unregisters the first. 

u	If you give no <handle> argument, the previously-set brkload will be 
unregistered.

See Also:	handle.

n	byteAsChar



Usage:	var byteAsChar [(0|1)]

Examples:	

"var byteAsChar 1" 
Print byte variables as characters.

Synopsis:	Determines how unsigned character variables are printed: if set non-zero, 
they are displayed as characters, else they are treated as unsigned integers.

Notes:	

u	If $byteAsChar is 0, $intFormat is used. 

u	The default value for this variable is 0.

n	bytes



Usage:	bytes [<address>] [<length>]

Examples:	

"bytes"	lists 16 bytes at DS:SI

"bytes ds:di 32"
lists 32 bytes at DS:SI

Synopsis:	Examine memory as a dump of bytes and characters.

Notes:	

u	The <address> argument is the address to examine. If not specified, the 
address after the last examined memory location is used. If no address 
has been examined then DS:SI is used for the address.

u	The <length> argument is the number of bytes to examine. It defaults to 
16.

u	Pressing <Return> after this command continues the list.

u	Characters which are not typical ASCII values are displayed as a period.

See Also:	words, dwords, imem, assign.

n	cache



This is a Tcl primitive. See page 306.

n	call



Usage:	call <function> [<function args>]

Examples:	"call MyFunc"
"call MyDraw ax 1 bx 1 cx 10h dx 10h"
"call FindArea box.bottom 5 box.right 5 push box"'

Synopsis:	Call a function in the current thread.

Notes:	

u	The <function> argument is the function to call. If it is a NEAR function, 
the thread must already be executing in the function's segment.

u	The function arguments are in pairs <variable/register> <value>. These 
pairs are passed to the "assign" command. As a special case, if the 
variable is "push", the value (a word) is pushed onto the stack and is 
popped when the call finishes (if it completes successfully).

u	All current registers are preserved and restored when the call is 
complete. Variables are not.

u	Once the call has completed, you are left in a sub-interpreter to examine 
the state of the machine. Type "break" to get back to the top level.

u	If the machine stops for any other reason than the call's completion, the 
saved register state is discarded and you are left wherever the machine 
stopped. You will not be able to get a stack trace above the called function, 
but if the call eventually completes, and no registers have actually been 
modified, things will get back on track.

u	You may not call a function from a thread that has retreated into the 
kernel. This function also will not allow you to call ThreadExit(). Use 
the "exit" function to do that.

See Also:	assign, call-patient, patch.

n	call-patient



Usage:	call-patient <function> ((<reg>|push) <value>)*

Examples:	

"call-patient MemLock bx $h" 
Locks down the block whose handle ID is in $h.

Synopsis:	This is a utility routine, not intended for use from the command line, that will 
call a routine in the PC after setting registers to or pushing certain values. 

Notes:	

u	Returns non-zero if the call completed successfully. 

u	If the call is successful, the registers reflect the state of the machine upon 
return from the called routine. The previous machine state is preserved 
and can be retrieved, by invoking restore-state, or thrown away, by 
invoking discard-state. The caller must invoke one of these to clean up. 

u	Arguments after <function> are as for "call". 

u	If the called routine is in movable memory, this will lock the containing 
block down before issuing the call, as you'd expect. 

u	Calling anything that makes message calls while on the geos:0 thread is 
a hazardous undertaking at best.

See Also:	call.

n	car



Usage:	car <list>

Examples:	

"car $args"	Returns the first element of $args.

Synopsis:	Returns the first element of a list.

Notes:	This is a lisp-ism for those most comfortable with that language. It can be 
more-efficiently implemented by saying [index <list> 0]

See Also:	cdr.

n	case

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	catch

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	cbrk

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	cdr



Usage:	cdr <list>

Examples:	

"cdr $args"	Returns the remaining arguments yet to be processed.

Synopsis:	Returns all but the first element of a list.

Notes:	This is a lisp-ism for those most comfortable with that language. It can be 
more-efficiently implemented by saying [range <list> 1 end]

See Also:	car.

n	classes



Usage:	classes [<patient>]

Examples:	

"classes "	Print list of classes in current patient.

"classes myapp"
Print list of classes in myapp patient.

Synopsis:	Prints list of classes defined by the given patient.

Notes:	Remember that "brk" will take address arguments of the form 
<class>::<message>, so you can use this function and set a breakpoint using 
"brk MyTextClass::MSG_MY_TEXT_MESSAGE". If you need a breakpoint 
that's limited to one object, use objbrk instead.

n	clrcc



Usage:	clrcc <flag> [<value>]

Examples:	

"clrcc c"	clear the carry flag

Synopsis:	Clear a flag in the target computer.

Notes:	The first argument is the first letter of the flag to clear. The following is a list 
of the flags:
t		trap
i		interrupt enable
d		direction
o		overflow
s		sign
z		zero
a		auxiliary carry
p		parity
c		carry

See Also:	setcc, compcc, getcc.

n	columns



Usage:	columns

Examples:	

"columns"
Return the number of columns on the screen.

Synopsis:	Retrieves the width of the screen, if known, to allow various commands (most 
notably "print") to size their output accordingly.

n	compcc



Usage:	compcc <flag>

Examples:	

"compcc c"	complement the carry flag

Synopsis:	Complement a flag in the target computer.

Notes:	The first argument is the first letter of the flag to complement. The following 
is a list of the flags:
t		trap
i		interrupt enable
d		direction
o		overflow
s		sign
z		zero
a		auxiliary carry
p		parity
c		carry
This command is handy to insert in a patch to flip a flag bit.

See Also:	setcc, clrcc.

n	completion



Usage:	completion <list-of-names>

Examples:	

"completion {martial marital}"
Returns "mar," the common prefix.

Synopsis:	Figures the common prefix from a set of strings. Used for the various forms 
of completion supported by top-level-read.

See Also:	top-level-read.

n	concat

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	condenseSmall



Usage:	var condenseSmall [(0|1)]

Examples:	

"var condenseSpecial 0" 
Force even small structures to be printed one field per line.

Synopsis:	Controls whether "print" attempts to condense the output by printing small 
(< 4 bytes) structures (which are usually records in assembly language) as a 
list of <name> = <int>, where <name> is the field name and <int> is a signed 
integer.

Notes:	The default value of this variable is one.

See Also:	print, condenseSpecial.

n	condenseSpecial



Usage:	var condenseSpecial [(0|1)]

Examples:	

"var condenseSpecial 0" 
Turns off the special formatting of various types of structures 
by "print".

Synopsis:	Controls the formatting of certain structures in more-intuitive ways than the 
bare structure fields.

Notes:	

u	The default value of this variable is 1. 

u	The current list of structures treated specially are: Semaphore, 
Rectangle, Output Descriptor, TMatrix, BBFixed, WBFixed, 
WWFixed, DWFixed, WDFixed, DDFixed, FileDate, FileTime, 
FloatNum, SpecWinSizeSpec.

See Also:	print, condenseSmall.

n	cont



Usage:	cont

Examples:	

"cont"	continue execution

"c"	continue execution

Synopsis:	Continue GEOS.

Notes:	

u	If the global variable waitForPatient is non-zero, this command waits for 
the machine to stop again before it returns.

See Also:	go, istep, step, next, detach, quit.

n	content



Usage:	content

Examples:	

"vistree [content]"
 print the visual tree of the content of the view under the 
mouse.

Synopsis:	Print the address of the content under the view with the current implied 
grab. 

Notes:	

u	This command is normally used with vistree to get the visual tree of a 
content by placing the mouse on the content's view window and issuing 
the command in the example. 

u	If the pointer is not over a GenView object, this is the same as the 
"impliedgrab" command.

See Also:	systemobj, gentree, impliedgrab.

n	continue

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	continue-patient



Usage:	continue-patient

Examples:	

"continue-patient"
Allow the target machine to continue executing GEOS.

Synopsis:	Tell the Swat stub to let the target machine continue where it left off.

Notes:	This command does not wait for the machine to stop again before it returns; 
once the machine is running, you're free to do whatever you want, whether 
it's calling "wait" or examining memory periodically.

See Also:	step-patient.

n	cup



Usage:	cup <class>
cup <object>
cup <flags>

Examples:	

"cup ui::GenDocumentControlClass" 
Print class hierarchy of named class

"cup ^l2850h:0034h" 
Print class hierarchy of object

"cup -f" 	Print class hierarchy of focus object

"cup -p" 	Print class hierarchy of process

Synopsis:	Walks up the class hierarchy, starting at a given class, printing each class 
encountered. May be passed an object, in which case the class of the object 
will be used as a starting place.

n	current-level



Usage:	current-level

Examples:	

"var l [current-level]"
Store the current interpreter nesting level in $l.

Synopsis:	Returns the number of invocations of "top-level" (i.e. the main command 
input loop) currently active.

Notes:	

u	This is currently used only to modify the command prompt to indicate the 
current nesting level.

u	The top-most command loop is level one.

See Also:	prompt, top-level.

n	current-registers



Usage:	current-registers

Examples:	

"current-registers"
Returns a list of the current registers for the current thread.

Synopsis:	Returns all the registers for the current thread as a list of decimal numbers.

Notes:	

u	The mapping from element number to register name is contained in the 
global variable "regnums", which is an assoc-list whose elements contain 
the name of the register, then the element number. 

u	For your own consumption, the list is ordered ax, cx, dx, bx, sp, bp, si, di, 
es, cs, ss, ds, ip, flags. You should use the "regnums" variable when 
programming, however, as this may change at some point (e.g. to 
accommodate the additional registers in the 386).

n	cvtrecord



Usage:	cvtrecord <type> <number>

Examples:	

"cvtrecord [symbol find type HeapFlags] 36" 
Return a value list for the number 36 cast to a HeapFlags 
record.

Synopsis:	Creates a value list for a record from a number, for use in printing out the 
number as a particular record using fmtval.

Notes:	

u	<type> is a type token for a record (or a structure made up exclusively of 
bitfields). 

u	<number> must be an actual number suitable for the "expr" command. It 
cannot be a register or variable or some such. Use "getvalue" to obtain an 
integer from such an expression. 

u	Returns a value list suitable for "value store" or for "fmtval".

See Also:	value, fmtval, expr, getValue.

n	cycles



Synopsis:	Count instruction cycles from now until the given address is reached. Prints 
out each instruction as it is executed, along with the cycles it took. If no 
address is given, executes until a breakpoint is hit. Takes the following 
(optional) flags:

 -r 	Print routines called, the total cycles for each routine, and a 
running total, not the cycles for each instruction.

 -i 	Same as -r, but indents to show calling level. Not recommended 
for counting cycles over deeply nested routines.

 -I 	Same as -i, except uses (#) to indicate call level

 -f 	Stop counting when this routine finishes

 -n 	Does not whine about interrupts being off

 -x <routine> 
Step over calls to <routine>

 -x <routine>=<val> 
Step over calls to <routine> and assume that the call takes 
<val> cycles for timing purposes

n	dcache



Usage:	dcache bsize <blockSize>
dcache length <numBlocks>
dcache stats
dcache params
dcache (on|off)

Examples:	

"dcache bsize 16" 
Set the number of bytes fetched at a time to 16.

 "dcache length 1024" 
Allow 1024 blocks of the current block size to be in the cache at 
a time.

 "dcache off" 	Disables the Swat data cache.

Synopsis:	Controls the cache Swat uses to hold data read from the target machine while 
the machine is stopped.

Notes:	

u	Data written while the machine is stopped actually get written to the 
cache, not the PC, and the modified blocks are written when the machine 
is continued. 

u	The default cache block size is 32 bytes, with a default cache length of 64 
blocks. 

u	It is a very rare thing to have to turn the data cache off. You might need 
to do this while examining the changing registers of a memory-mapped 
I/O device. 

u	The <blockSize> must be a power of 2 and no more than 128. 

u	Changing the block size causes all cached blocks to be flushed (any 
modified cache blocks are written to the PC).

u	Changing the cache length will only flush blocks if there are more blocks 
currently in the cache than are allowed by the new length. 

u	The "dcache stats" command prints statistics giving some indication of 
the efficacy of the data cache. It does not return anything. 

u	The "dcache params" command returns a list {<blockSize> 
<numBlocks>} giving the current parameters of the data cache. There 
are some operations where you might want to adjust the size of the cache 
either up or down, but need to reset the parameters when the operation 
completes. This is what you need to do this.

See Also:	cache.

n	dcall



Usage:	dcall [<args>]

Examples:	

"dcall Dispatch"
Display when the routine Dispatch is called

"dcall none"
stop displaying all routines

Synopsis:	Display calls to a routine.

Notes:	

u	The <args> argument normally is the name of the routine to monitor. 
Whenever a call is made to the routine its name is displayed.

u	If `none' or no argument is passed, then all the routines will stop 
displaying.

u	Dcall uses breakpoints to display routine names. By looking at the list of 
breakpoints you can see which routines display their names and you can 
stop them individually by disabling or deleting their breakpoints.

See Also:	showcalls, mwatch.

n	debug



Usage:	debug <proc-name>*

Examples:	

"debug"	Enter the Tcl debugger immediately.

"debug fooproc"
Enter the Tcl debuffer when the interpreter is about to execute 
the command "fooproc".

Synopsis:	This command is used when debugging Tcl commands. It sets a breakpoint 
at the start of any Tcl command. Also serves as a breakpoint in the middle of 
a Tcl procedure, if executed with no argument.

Notes:	

u	The breakpoint for <proc-name> can be removed using the "undebug" 
command. 

u	<proc-name> need not be a Tcl procedure. Setting a breakpoint on a 
built-in command is not for the faint-of-heart, however, as there are some 
commands used by the Tcl debugger itself. Setting a breakpoint on such 
a command will cause instant death.

See Also:	undebug.

n	debugger



Usage:	var debugger [<command-name>]

Synopsis:	Name of the command when things go wrong. The function is passed two 
arguments: a condition and the current result string from the interpreter. 
The condition is "enter" if entering a command whose debug flag is set, "exit" 
if returning from a frame whose debug flag is set, "error" if an error occurred 
and the "debugOnError" variable is non-zero, "quit" if quit (^> is typed and 
the "debugOnReset" variable is non-zero, or "other" for some other cause (e.g. 
"debug" being invoked from within a function).

n	debugOnError



Usage:	var debugOnError [(0|1)]

Examples:	

"var debugOnError 1"
Turn on debugging when there's a Tcl error.

Synopsis:	Enter debug mode when Swat encounters a Tcl error. 

Notes:	

u	The 0|1 simply is a false|true to stop and debug upon encountering an 
error in a Tcl command. 

u	If an error is caught with the catch command, Swat will not enter debug 
mode. 

See Also:	debugger.



n	defcmd



Usage:	defcmd <name> <args> <help-class> <help-string> <body>

Examples:	Look at almost any .tcl file in the system library for an example; a complete 
example set would be too large to give here.

Synopsis:	This creates a new Tcl procedure with on-line help whose name the user may 
abbreviate when invoking.

Notes:	

u	<help-class> is a Tcl list of places in which to store the <help-string>, 
with the levels in the help tree separated by periods. The leaf node for 
each path is added by this command and is <name>, so a command "foo" 
with the <help-class> "prog.tcl" would have its <help-string> stored as 
"prog.tcl.foo."

u	Because the name you choose for a procedure defined in this manner can 
have an impact on the unique abbreviation for another command, you 
should use this sparingly.

See Also:	defcommand, proc, help. 

n	defcommand



Usage:	defcommand <name> <args> <help-class> <help-string> <body>

Examples:	Look at Swat Display 5-3, Swat Display 5-4, or almost any .tcl file in the 
system library for an example; a complete example set would be too large to 
give here.

Synopsis:	This creates a new Tcl procedure with on-line help whose name must be given 
exactly when the user wishes to invoke it.

Notes:	<help-class> is a Tcl list of places in which to store the <help-string>, with 
the levels in the help tree separated by periods. The leaf node for each path 
is added by this command and is <name>, so a command "foo" with the 
<help-class> "prog.tcl" would have its <help-string> stored as "prog.tcl.foo."

See Also:	defcmd, proc, help.

n	defhelp



Usage:	defhelp <topic> <help-class> <help-string>

Examples:	

"defhelp breakpoint top {Commands relating to the setting of breakpoints}"
Sets the help for "breakpoint" in the "top" category to the given 
string.

Synopsis:	This is used to define the help string for an internal node of the help tree (a 
node that is used in the path for some other real topic, such as a command or 
a variable).

Notes:	

u	This cannot override a string that resides in the /pcgeos/tcl/doc file.

u	You only really need this if you have defined your own help-topic category.

u	<help-class> is a Tcl list of places in which to store the <help-string>, 
with the levels in the help tree separated by periods. The leaf node for 
each path is added by this command and is <name>, so a command "foo" 
with the <help-class> "prog.tcl" would have its <help-string> stored as 
"prog.tcl.foo."

See Also:	help.

n	defsubr

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	defvar



Usage:	defvar <name> <value> [<help-class> <help-string>]

Examples:	

"defvar printRegions 0" 
Define "printRegions" as a global variable and give it the value 
zero, if it didn't have a value already.

Synopsis:	This command is used in .tcl files to define a global variable and give it an 
initial value, should the variable not have been defined before.

Notes:	

u	If the variable is one the user may want to change, give it on-line help 
using the <help-class> and <help-string> arguments.

u	<help-class> is a Tcl list of places in which to store the <help-string>, 
with the levels in the help tree separated by periods. The leaf node for 
each path is added by this command and is <name>, so a command "foo" 
with the <help-class> "variable.output" would have its <help-string> 
stored as "variable.output.foo."

See Also:	var, help.

n	delassoc



Usage:	delassoc <list> <key> [<foundvar> [<elvar>]]

Examples:	

"delassoc $val murphy"
Returns $val without the sublist whose first element is the 
string "murphy."

Synopsis:	Deletes an entry from an associative list.

Notes:	

u	 <foundvar>, if given, is the name of a variable in the caller's scope that 
is to be set non-zero if an element in <list> was found whose <key> 
matched the given one. If no such element was found (and therefore 
deleted), the variable is set zero.

u	<elvar>, if given, is the name of a variable in the caller's scope that 
receives the element that was deleted from the list. If no element was 
deleted, the variable remains untouched.

See Also:	assoc.

n	detach



Usage:	detach [<options>]

Examples:	

"detach cont"
continue GEOS and quit swat

Synopsis:	Detach swat from the PC.

Notes:	

u	The <option> argument may be one of the following: continue: continue 
GEOS and detach swat; leave: keep GEOS stopped and detach swat. 
Anything else causes swat to just detach.

See Also:	attach, quit.

n	dirs



Usage:	dirs

Synopsis:	Prints the directory stack for the current thread.

See Also:	pwd, stdpaths

n	discard-state



Usage:	discard-state

Examples:	

"discard-state"
Throw away the values for all the thread's registers as saved by 
the most recent call to save-state.

Synopsis:	Throw away the state saved by the most-recent save-state command.

Notes:	This is usually only used in response to an error that makes it pointless to 
return to the point where the save-state was performed.

See Also:	save-state, restore-state.

n	diskwalk



Usage:	diskwalk <drive>

Examples:	

"diskwalk 	F" 
Prints the disks registered in drive F.

"diskwalk"	Prints all the disks registered with the system.

Synopsis:	Prints out the information on registered disks.

Notes:	The Flags column is a string of single-character flags with the following 
meanings:

w	The disk is writable.

V 	The disk is always valid, i.e. it's not removable.

S 	The disk is stale. This is set if the drive for the disk has been 
deleted.

u 	The disk is unnamed, so the system has made up a name for it.

See Also:	drivewalk, fsdwalk.

n	display



Usage:	display <lines> <command>
display list
display del <num>

Examples:	

"display list"
list all the commands displayed

"display 1 {piv Vis VCNI_viewHeight}"
always display the view height

"display del 2"
delete the second display command

Synopsis:	Manipulate the display at the bottom of Swat's screen.

Notes:	

u	If you give a numeric <lines> argument, the next argument, <command>, 
is a standard Tcl command to execute each time the machine halts. The 
output of the command is directed to a window <lines> lines high, usually 
located at the bottom of the screen.

u	You can list all the active displays by giving "list" instead of a number as 
the first argument.

u	If the first argument is "del", you can give the number of a display to 
delete as the <num> argument. <num> comes either from the value this 
command returned when the display was created, or from the list of 
active displays shown by typing "display list".

See Also:	wtop, wcreate.

n	doc



Usage:	doc [<keyword>]

Examples:	

"doc MSG_VIS_OPEN"
Brings up technical documentation for MSG_VIS_OPEN.

Synopsis:	Finds technical documentation for <keyword>. If it finds multiple entries for 
the keyword in the documentation, hit <Return> or use doc-next and 
doc-previous to see the additional entries. The documentation retrieved is 
in ASCII form-figures will be missing, but the complete text appears.

See Also:	doc-next, doc-previous.

n	doc-next



Usage:	doc-next

Examples:	

"doc MSG_VIS_OPEN"
Brings up technical documentation for MSG_VIS_OPEN.

"doc-next"
Brings up more technical documentation if available.

Synopsis:	Finds additional technical documentation for <keyword>.

See Also:	doc, doc-previous.

n	doc-previous



Usage:	doc-next

Examples:	

"doc MSG_VIS_OPEN"
Brings up technical documentation for MSG_VIS_OPEN.

"doc-next"	Brings up more technical documentation if available.

"doc-previous" 
Brings back previous (in this case, the first) entry.

Synopsis:	Finds additional technical documentation for <keyword>.

See Also:	doc, doc-next.

n	dosMem



Usage:	dosMem

Examples:	

"dosMem"

Synopsis:	Traverse DOS' chain of memory blocks, providing information about each.

n	down



Usage:	down [<frame offset>]

Examples:	

"down"	move the frame one frame down the stack

"down 4"	move the frame four frames down the stack

Synopsis:	Move the frame down the stack.

Notes:	

u	The frame offset argument is the number of frames to move down the 
stack. If no argument is given then the current frame is moved down one 
frame.

u	This command may be repeated by pressing <Return>.

See Also:	backtrace, up.

n	drivewalk



Usage:	drivewalk

Examples:	

"drivewalk"	
Prints the table of drives known to the system.

Synopsis:	Prints out all disk drives known to the system, along with their current 
status.

Notes:	

u	The Flags column is a string of single character flags with the following 
meanings:

        L	The drive is accessible to the local machine only, i.e. it's not 
visible over a network. 

           R 	The drive is read-only.

           F 	Disks may be formatted in the drive.

           A 	The drive is actually an alias for a path on another drive.

           B 	The drive is busy, performing some extended operation, such as 
formatting or copying a disk.

            r 	The drive uses disks that may be removed by the user.

           n	 The drive is accessed over the network. 

u	The Locks column can reflect one of three states: 

          none 	The drive isn't being accessed by any thread. 

          Excl	The drive is locked for exclusive access by a single thread.

          <num> 	The drive is locked for shared access for a particular disk, 
whose handle is the number. This is followed by the volume 
name of the disk, in square brackets.

See Also:	diskwalk, fsdwalk.

n	dumpstack



Usage:	dumpstack [<address>] [<length>]

Examples:	

"dumpstack"	
dump the stack at SS:SP

"ds ds:si 10"  
dump ten words starting at DS:SI

Synopsis:	Dump the stack and perform some simple interpretation upon it.

Notes:	

u	The <address> argument is the address of the list of words to dump. This 
defaults to SS:SP.

u	The <length> argument is the number of words to dump. This defaults to 
50.

u	This dumps the stack and tries to make symbolic sense of the values, in 
terms of handles, segments, and routines.

u	After doing a dumpstack, if you just hit return without entering a new 
command, by default you will see a continuation of the dumpstack.

See Also:	backtrace.

n	dwordIsPtr



Usage:	var dwordIsPtr [(0|1)]

Examples:	

"var dwordIsPtr 1" 
Tells "print" to print all double-word variables as if they were 
far pointers (segment:offset).

Synopsis:	Controls whether dword (a.k.a. long) variables are printed as 32-bit unsigned 
integers or untyped far pointers.

Notes:	

u	For debugging C code, a value of 0 is more appropriate, while 1 is best for 
debugging assembly language. 

u	The default value for this variable is 1.

See Also:	intFormat, print.

n	dwords



Usage:	dwords [<address>] [<length>]

Examples:	

"dwords"	lists 4 double words at DS:SI

"dwords ds:di 8"
lists 8 double words at DS:DI

Synopsis:	Examine memory as a dump of double words (32 bit hex numbers).

Notes:	

u	The <address> argument is the address to examine. If not specified, the 
address after the last examined memory location is used. If no address 
has be examined then DS:SI is used for the address.

u	The <length> argument is the number of dwords to examine. It defaults 
to 4.

u	Pressing <Return> after this command continues the list.

See Also:	bytes, words, imem, assign.

n	ec



Usage:	ec [<args>]

Examples:	

"ec"	list the error checking turned on

"ec +vm"	add vmem file structure checking

"ec all"	turn on all error checking (slow)

"ec save none"
save the current error checking and then use none

"ec restore"	use the saved error checking flags

Synopsis:	Get or set the error checking level active in the kernel.

Notes:	The following arguments may occur in any combination:

 <flag>	turn on <flag>

+<flag>	turn on <flag>

-<flag>	turn off <flag>

all	turn on all error checking flags

ALL	turn on all error checking flags

none	turn off all error checking flags

sum <handle>
turn on checksum checking for the memory block with the 
given handle ("ec sum bx"). The current contents of the block 
will be summed and that sum regenerated and checked for 
changes at strategic points in the system (e.g. when a call 
between modules occurs).

-sum	turn off checksum checking

save	save the current error checking

restore	restore the saved error checking flags

 where <flag> may be one of the following:

analVM	perform over-aggressive checking of vmem files

graphics	graphics checking

heapFree	heap free block checking

lmemFree	lmem free area checking

lmemInternal
internal lmem error checking

lmemObject
lmem object checking

normal	normal error checking

region	region checking segment extensive

segment	register checking

lmemMove	force lmem blocks to move whenever possible

unlockMove
force unlocked blocks to move whenever possible

vm	vmem file structure checking

vmemDiscard
force vmem blocks to be discarded if possible

u	If there isn't an argument, `ec' reports the current error checking flags.

u	Each time GEOS is run the ec flags are cleared. The saved flags are 
preserved between sessions. The ec flags may be saved and then restored 
after restarting GEOS so that the flag settings are not lost when 
restarting GEOS.

See Also:	why.

n	echo



Usage:	echo [-n] <string>+

Examples:	

"echo -n yes?"
Prints "yes?" without a newline.

"echo hi mom"
Prints "hi mom" followed by a newline.

Synopsis:	Prints its arguments, separated by spaces.

Notes:	If the first argument is "-n", no newline is printed after the arguments.

See Also:	flush-output

n	elist



Usage:	elist [<patient>]

Examples:	

"elist"	list the events for the current thread and patient

"elist ui"	list the events for the last thread of the ui patient

"elist :1"	list the events for the first thread of the current patient

"elist geos:2"
list the events for the second thread of the GEOS patient

Synopsis:	Display all events pending for a patient.

Notes:	The <patient> argument is of the form `patient:thread'. Each part of the 
patient name is optional, and if nothing is specified then the current patient 
is listed.

See Also:	showcalls.

n	ensure-swat-attached



Usage:	ensure-swat-attached

Examples:	

"ensure-swat-attached"
Stop if Swat isn't attached to GEOS.

Synopsis:	If Swat is not attached to GEOS, display an error and stop a command.

Notes:	Use this command at the start of any other command that accesses the target 
PC. Doing so protects the user from the numerous warnings that can result 
from an attempt to read memory when not attached.

n	eqfind



Usage:	eqfind [-p]

Examples:	

"eqfind" list all event queues in the system.

 "eqfind -p" list and print all event queues in the system.

Synopsis:	Display all event queues in the system.

See Also:	elist, eqlist, erfind.

n	eqlist



Usage:	eqlist <queue handle> <name>

Examples:	

"eqlist 8320 geos:2"
show the event list for geos:2

Synopsis:	Display all events in a queue.

Notes:	

u	The queue handle argument is the handle to a queue.

u	The name argument is the name of the queue.

See Also:	elist.

n	erfind



Usage:	erfind [-p]

Examples:	

"erfind" list all recorded event handles in the system.

"erfind -p" list and print all recorded event handles in the system.

Synopsis:	Display all record event handles in the system. These are events that have 
been recorded but not necessarily sent anywhere, so they will not appear in 
the queue of any thread.

See Also:	elist, eqlist, eqfind, pevent.

n	error

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	eval

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	event

This is a Tcl primitive data structure. See "Tool Command Language," 
Chapter 5.

n	exec

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	exit



Usage:	exit <patient>

Examples:	

"exit faxmon"
Causes the faxmon application to exit.

Synopsis:	Sends messages required to make an application quit.

Notes:	This command does nothing when you're stopped at FatalError, as it will 
wait until the machine is idle before attempting to send MSG_META_QUIT; 
continuing from FatalError will cause the system to exit.

See Also:	run. 

n	exit-thread



Usage:	exit-thread [<exit-code>]

Examples:	

"exit-thread" 
Exit the current thread, returning zero to its parent.

"exit-thread 1" 
Exit the current thread, returning one to its parent.

Synopsis:	Exit the current thread.

Notes:	

u	The exit code argument is the status to return to the current thread's 
parent, which defaults to zero. 

u	Do not invoke this function for an event-driven thread; send it a 
MSG_META_DETACH instead. 

See Also:	quit.

n	explain



Usage:	explain

Examples:	"explain"

Synopsis:	Print a more detailed description of why the system crashed, if possible.

Notes:	

u	This must be run from within the frame of the FatalError() function. 
Sometimes GEOS is not quite there. In this case, step an instruction or 
two and then try the "why" command again.

u	This simply looks up the enumerated constant for the error code in the 
AX register in the FatalErrors enumerated type defined by the geode 
that called FatalError(). For example, if a function in the kernel called 
FatalError(), AX would be looked up in geos::FatalErrors, while if a 
function in your application called FatalError(), this function would 
look it up in the FatalErrors type defined by your application. Each 
assembly application defines this enumerated type by virtue of having 
included ec.def.

u	This command also relies on programmers having explained their 
FatalErrors when defining them.

u	For certain fatal errors, additional information is provided by invoking 
the command <patient>::<error code name>, if it exists.

n	explode



Usage:	explode <string> [<sep-set>]

Examples:	

"explode $args" 
Breaks the string stored in the variable "args" into a list of its 
individual letters.

 "explode $file /" 
Breaks the string stored in the variable "file" into a list of its 
components, using "/" as the boundary between components 
when performing the split.

Synopsis:	 Breaks a string into a list of its component letters, allowing them to be 
handled quickly via a foreach loop, or the map or mapconcat commands.

Notes:	This is especially useful for parsing command switches. 

See Also:	foreach, index, range.

n	expr

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	fatalerr_auto_explain



Usage:	var fatalerr_auto_explain [(0|1)]

Examples:	

"var fatalerr_auto_explain 0" 
Turn off automatic generation of the explanation for any 
fatal-error hit.

Synopsis:	Determines if the "why" command will automatically provide you with an 
explanation of any fatal error you encounter. If non-zero, they will be 
provided whenever FatalError is hit.

Notes:	

u	Explanations are loaded from <patient>.fei files stored in the system Tcl 
library directory when an error in <patient> is encountered. 

u	You can also obtain an explanation of an error via the "explain" 
command.

n	fetch-optr



Usage:	fetch-optr <handle> <offset>

Examples:	

"fetch-optr $h $o.GI_comp.CP_firstChild"
 Fetch the optr from the GI_comp.CP_firstChild field of the 
object at ^h$h:$o.

Synopsis:	Extracts an optr from memory, coping with the data in the block that holds 
the optr not having been relocated yet.

Notes:	

u	<offset> is an actual offset, not a chunk handle, while <handle> is a 
handle ID, not a handle token. 

u	Returns a two-list {<handle> <chunk>}, where <handle> is the handle ID 
from the optr, and <chunk> is the chunk handle (low word) from the optr. 

u	We decide whether to relocate the optr ourselves based on the 
LMF_RELOCATED bit in the LMBH_flags field of the block's header. There 
are times, e.g. during the call to MSG_META_RELOCATE for an object, 
when this bit doesn't accurately reflect the state of the class pointer and 
we will return an error when we should not.

n	fhandle



Usage:	fhandle <handle id>

Examples:	"fhandle 3290h"

Synopsis:	Print out a file handle.

Notes:	

u	The <handle id> argument is the handle number. File handles are listed 
in the first column of the `fwalk' command.

See Also:	fwalk.

n	field



Usage:	field <list> <field name>

Examples:	

"field [value fetch ds:si MyBox] topLeft"
return the offset of the topLeft field in MyBox

Synopsis:	Return the value for the field's offset in the structure.

Notes:	

u	The <list> argument is a structure-value list from the "value" command.

u	The <field name> argument is the field in the structure.

See Also:	value, pobject, piv.

n	fieldwin



Usage:	fieldwin

Synopsis:	Print the address of the target machine's current top-most field window.

n	file

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	find



Usage:	find [-ir] <string> [<filename>]

Examples:	

"find FileRead" 
Find next occurrence of string "FileRead" in currently viewed 
file 

"find FI_foo poof.goc"
 find first occurrence of string "FI_foo" in file poof.goc.

 "find -ir myobject" 
case-insensitive reverse search for most recent occurrence of 
string "myobject" in currently viewed file

Synopsis:	Finds a string in a file and brings the line with that string to the middle of 
Swat's source window.

Notes:	

u	If no file argument is specified, find will find the next instance of the 
string in the already viewed file starting from the current file position. 

u	There must already be a source window displayed for find to work. 

u	Possible options to find are:

          -r 	reverse search

          -i 	case insensitive search

n	find-opcode



Usage:	find-opcode <addr> <byte>+

Synopsis:	Locates the mnemonic for an opcode and decodesit. Accepts the address from 
which the opcode bytes were fetched, and one or more opcode bytes as 
arguments. Returns a list of data from the opcode descriptor:

 {name length branch-type args modrm bRead bWritten inst}

length is the length of the instruction.

branch-type is one of: 

1	 none (flow passes to next instruction)

j 	absolute jump

b	 pc-relative jump (branch)

r 	near return

R 	far return

i	 interrupt return

I 	interrupt instruction

Any argument descriptor that doesn't match is to be taken as a literal. E.g. 
AX as a descriptor means AX is that operand.

modrm is the modrm byte for the opcode.

bRead is the number of bytes that may be read by the instruction, if one of its 
operands is in memory.

 bWritten is the number of bytes that may be written by the instruction, if one 
of its operands is in memory.

inst is the decoded form of the instruction. If not enough bytes were given to 
decode the instruction, inst is returned as empty.

n	finish



Usage:	finish [<frame num>]

Examples:	

"finish"	finish executing the current frame

"finish 3"	finish executing up to the third frame

Synopsis:	Finish the execution of a frame.

Notes:	

u	The <frame num> argument is the number of the frame to finish. If none 
is specified then the current frame is finished up. The number to use is 
the number which appears in a backtrace.

u	The machine continues to run until the frame above is reached.

See Also:	backtrace.

n	finishframe



Usage:	finishframe [<frame-token>]

Examples:	

"finishframe $cur"
Run the machine to continue until it has returned from a 
particular stack frame.

Synopsis:	Allows the machine to continue until it has returned from a particular stack 
frame.

Notes:	

u	No FULLSTOP event is dispatched when the machine actually finishes 
executing in the given frame. The caller must dispatch it itself, using the 
"event" command.

u	The command returns zero if the machine finished executing in the given 
frame; non-zero if it was interrupted before that could happen. 

u	The argument is a frame token, as returned by the "frame" command.

See Also:	event, frame, finish.

n	flagwin



Usage:	flagwin [<on>|off]

Synopsis:	Turns on or off a window providing a continuous display of the machine flags 
(e.g. zero, carry).

See Also:	pflags.

n	flowobj



Usage:	flowobj

Examples:	

"pobject [flowobj]"
print out the flow object.

Synopsis:	Prints out address of the uiFlowObj, which is the object which grabs the 
mouse.

Notes:	This command is normally used with pobject to print out the object.

n	flush-output



Usage:	flush-output

Examples:	

"flush-output"
Forces pending output to be displayed.

Synopsis:	Flushes any pending output (e.g. waiting for a newline) to the screen.

See Also:	echo.

n	fmtoptr



Usage:	fmtoptr <handle-id> <chunk>

Examples:	

"fmtoptr 3160h o"	
Prints a description of the object whose address is ^l3160h:0 
(likely a thread/process).

Synopsis:	Takes a global and a local handle and prints a description of the object 
described by that optr.

Notes:	

u	If the global handle is a thread or a process, the thread's name (process 
thread for a process handle) and the chunk handle (as an additional word 
of data for the message) are printed.

u	If the global handle is a queue handle, the queue handle and the chunk 
handle are printed, with a note that the thing's a queue.

u	If Swat can determine the object's class, the optr, full classname, and 
current far pointer are printed. In addition, if the chunk has its low bit 
set, the word "parent" is placed before the output, to denote that the optr 
likely came from a link and is the parent of the object containing the optr.

See Also:	print.

n	fmtval



Usage:	fmtval <value-list> <type-token> <indent> [<tail> [<one-line>]]

Examples:	

"fmtval [value fetch foo] [symbol find type FooStruct] 0"
Prints the value of the variable foo, which is assumed to be of 
type FooStruct.

Synopsis:	This is the primary means of producing nicely-formatted output of data in 
Swat. It is used by both the "print" and "_print" commands and is helpful if 
you want to print the value of a variable without entering anything into the 
value history.

Notes:	

u	<value-list> is the return value from "value fetch". You can, of course, 
construct one of these if you feel so inclined.

u	<type-token> is the token for the type-description used when fetching the 
value. 

u	<indent> is the base indentation for all output. When "fmtval" calls itself 
recursively, it increases this by 4 for each recursive call. 

u	<tail> is an optional parameter that exists solely for use in formatting 
nested arrays. It is a string to print after the entire value has been 
formatted. You will almost always omit it or pass the empty string.

u	<one-line> is another optional parameter used almost exclusively for 
recursive calls. It indicates if the value being formatted is expected to fit 
on a single line, and so "fmtval" should not force a newline to be output 
at the end of the value. The value should be 0 or 1.

See Also:	print, _print, fmtoptr, threadname.

n	focus



Usage:	focus [<object>]

Examples:	

"focus" 	print focus hierarchy from the system object down

 "focus -i" 	print focus hierarchy from implied grab down

 "focus ^l4e10h:20h" 
print focus hierarchy from ^l4e10h:20h down

 "focus [content]" 
print focus hierarchy from content under mouse.

Synopsis:	Prints the focus hierarchy below an object.

Notes:	

u	If no argument is specified, the system object is used. 

u	The special object flags may be used to specify <object>.  For a list of these 
flags, see pobject.

u	Remember that the object you start from may have the focus within its 
part of the hierarchy, but still not have the focus because something in a 
different part of the tree has it. 

u	The variable "printNamesInObjTrees" can be used to print out the actual 
app-defined labels for the objects, instead of the class, where available.

	This variable defaults to false.

See Also:	target, model, mouse, keyboard, pobject.

n	focusobj



Usage:	focusobj

Examples:	

"focusobj"	print model hierarchy from system object down

"pobj [focusobj]"
Do a pobject on the focus object (equivalent to "pobj -f").

Synopsis:	Returns the object with the focus.

See Also:	focus, target, model, targetobj, modelobj.

n	fonts



Usage:	fonts [<args>]

Examples:	

"fonts"	summarize general font usage

"fonts -u"	list fonts currently in use

Synopsis:	Print various font info.

Notes:	

u	The <args> argument may be any of the following:

           -a	list of fonts available

           -d	list of font drivers available

           -u	[<ID>] list of fonts currently in use. Optional font ID to match.

            -s	summary of above information

 If no argument is specified the default is to show the summary.

u	 When using other commands you probably need to pass them the handle 
in FIUE_dataHandle. When you don't have the font's handle ready, the 
best way is to use "fonts -u" to find the font at the right point size and 
then grab the handle from there.

See Also:	pfont, pfontinfo, pusage, pchar, pfontinfo.

n	for

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	foreach

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	format

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	fpstack



Usage:	fpstack

Examples:	

"fpstack"	Prints out the hardware and software floating point stacks for 
the patient.

Synopsis:	Prints out the hardware and software floating point stacks for the patient. 

See Also:	fpstack, pfloat.

n	fpu-state



Usage:	fpustate [<mode>]

Examples:	

"fpustate"	Print out the state of the coprocessor.

"fpustate w"	Dumps actual words of the numbers.

Synopsis:	Prints out the current state of the coprocessor, if any.

See Also:	fpstack, pfloat.

n	frame



Usage:	frame top
frame cur
frame get <ss> <sp> <cs> <ip>
frame next <frame>
frame prev <frame>
frame function [<frame>]
frame funcsym [<frame>]
frame scope [<frame>]
frame info [<frame>]
frame patient [<frame>]
frame register <regName> [<frame>]
frame set [<frame>]
frame setreg <regName> <value> [<frame>]
frame +<number>
frame -<number>
frame <number>

Examples:	

"var f [frame top]"
 Fetches the token for the frame at the top of the current 
thread's stack and stores it in the variable "f"

 "var f [frame next $f]"
 Fetches the token for the next frame up the stack (away from 
the top) from that whose token is in $f

 "frame register ax $f" 
Returns the value of the AX register in the given frame.

 "frame 1" 	Sets the current frame for the current thread to be the top-most 
one.

Synopsis:	This command provides access to the stack-decoding functions of swat. Most 
of the subcommands deal with frame tokens, but a few also handle frame 
numbers, for the convenience of the user.

Notes:	

u	Subcommands may be abbreviated uniquely.

u	Stack decoding works by a heuristic method, rather than relying on the 
presence of a created stack frame pointed to by BP in each function. 
Because of this, it can occasionally get confused. 

u	Frame tokens are valid only while the target machine is stopped and are 
invalidated when it is continued.

u	Each frame records the address on the stack where each register was 
most-recently pushed (i.e. by the frame closest to it on the way toward the 
top of the stack). Register pushes are looked for only at the start of a 
function in what can be considered the function prologue.

u	"frame register" and "frame setreg" allow you to get or set the value held 
in a register in the given frame. For "setreg", <value> is a standard 
address expression, only the offset of which is used to set the register.

u	"frame register" returns all registers but "pc" as a decimal number. "pc" 
is formatted as two hex numbers (each preceded by "0x") separated by a 
colon.

u	"frame info" prints out information on where the register values for 
"frame register" and "frame setreg" are coming from/going to for the 
given or currently-selected frame. Because of the speed that can be 
gained by only pushing registers when you absolutely have to, there are 
many functions in GEOS that do not push the registers they save at their 
start, so Swat does not notice that they are actually saved. It is good to 
make sure a register value is coming from a reliable source before 
deciding your program has a bug simply because the value returned by 
"frame register" is invalid.

u	For any subcommand where the <frame> token is optional, the currently- 
selected frame will be used if you give no token.

u	"frame cur" returns the token for the currently-selected stack frame.

u	"frame set" is what sets the current frame, when set by a Tcl procedure.

u	"frame +<number>" selects the frame <number> frames up the stack 
(away from the top) from the current frame. "frame -<number>" goes the 
other way.

u	"frame <number>" selects the frame with the given number, where the 
top-most frame is considered frame number 1 and numbers count up 
from there.

u	"frame funcsym" returns the symbol token for the function active in the 
given (or current) frame. If no known function is active, you get "nil".

u	"frame scope" returns the full name of the scope that is active in the given 
(or current) frame. This will be different from the function if, for example, 
one is in the middle of an "if" that contains variables that are local to it 
only.

u	"frame function" returns the name of the function active in the given (or 
current) frame. If no known function is active, you get the CS:IP for the 
frame, formatted as two hex numbers separated by a colon.

u	"frame patient" returns the token for the patient that owns the function 
in which the frame is executing.

See Also:	addr-parse, switch.

n	framewin



Usage:	framewin [del]

Examples:	

"framewin"
Creates a single-line window to display info about the current 
stack frame.

"framewin del"
Deletes the window created by a previous "framewin".

Synopsis:	Creates a window in which the current stack frame is always displayed.

Notes:	

u	Only one frame window can be active at a time.

See Also:	display, regwin, ewatch, srcwin

n	freeze



Usage:	freeze [<patient>]
freeze :<n>
freeze <patient>:<n>
freeze <id> 

Examples:	

"freeze"	Freezes the current thread.

"freeze term" 
Freezes the application thread for "term"

"freeze :1" 	Freezes thread #1 of the current patient

"freeze 16c0h" 
Freezes the thread whose handle is 16c0h.

Synopsis:	Freezing a thread prevents a thread from running unless it's the only thread 
that's runnable in the entire system.

Notes:	

u	A frozen thread is not dead in the water, as it will still run if nothing else 
is runnable. 

u	Freezing a thread is most useful when debugging multi-threaded 
applications where a bug appears to be caused by a timing problem or 
race condition between the two threads. Freezing one of the threads 
ensures a consistent timing relationship between the two threads and 
allows the bug to be reproduced much more easily. 

u	The freezing of a thread is accomplished by setting its base and current 
priorities to as high a number as possible (255) thereby making the 
thread the least-favored thread in the system. The previous priority can 
be restored using the "thaw" command.

See Also:	thaw.

n	fullscreen



Usage:	fullscreen

Examples:	

"fullscreen"

Synopsis:	Prints the full screen hierarchy from the system object down.

n	func



Usage:	func [<func name>]

Examples:	

"func"	return the current function.

"func ObjMessage"
set the frame to the first frame for ObjMessage.

Synopsis:	Get the current function or set the frame to the given function.

Notes:	

u	The <func name> argument is the name of a function in the stack frame 
of the current patient. The frame is set to the first occurrence of the 
function from the top of the stack.

u	 If no <func name> argument is given then `func' returns the current 
function.

See Also:	backtrace, up, down, finish.

n	fvardata



Usage:	fvardata <token> [<address>]

Examples:	

"fvardata ATTR_VIS_TEXT_STYLE_ARRAY *ds:si"

Synopsis:	Locates and returns the value list for the data stored under the given token 
in the vardata of the given object.

Notes:	

u	If the data are found, returns a list {<token> <data>}, where <data> is a 
standard value list for the type of data associated with the specified 
token. 

u	Returns an empty list if the object has no vardata entry of the given type. 

u	If no <address> is given, the default is *ds:si.

n	fwalk



Usage:	fwalk [<patient>]

Examples:	

"fwalk"	list all open files.

"fwalk geos"
list all open files owned by the GEOS patient.

Synopsis:	Print the list of files open anywhere in the system.

Notes:	

u	The patient argument may be used to restrict the list to a particular 
patient. The patient may be specified either as the patient name or as the 
patient's handle.

u	fwalk differs from sysfiles and geosfiles in that it deals primarily with 
GEOS data structures.

u	The `Other' column shows if there is a VM handle bound to the file.

u	The letters in the `Flags' column mean the following:

           RW	deny RW

        R	deny R

        W	deny W

        N	deny none

           rw	access RW

        r	access R

        w	access RW

        O	override, used to override normal exclusion normally used by 
FileEnum() to check out file headers.

        E	exclusive, used to prevent override. This is used by swap.geo

See Also:	fhandle, geosfiles, sysfiles.

n	gc



Usage:	gc [(off|register|<extensive-heap-checking-flag>]

Synopsis:	Implements a simple garbage collector to scavenge unreferenced symbols 
and types. If given an argument other than "off" or "register," it turns on 
extensive heap checking, which slows things down enormously but ensures 
the heap is in good shape. The "gc register" command can be use to register 
a type created by "type make"as something that is being used for an extended 
period at the Tcl level, preventing the thing from being garbage-collected. 

n	gentree



Usage:	gentree [<address>] [<instance field>]

Examples:	

"gentree"	print the generic tree starting at *DS:SI

"gentree -i"	print the generic tree under the mouse

"gentree [systemobj]"
print the generic tree starting at the system's root

"gentree @23 GI_states"
print the generic tree with generic states

"gentree *uiSystemObj"
start the generic tree at the root of the system

Synopsis:	Print a generic tree.

Notes:	

u	The <address> argument is the address to an object in the generic tree. 
This defaults to *DS:SI. The `-i' flag for an implied grab may be used.

u	The special object flags may be used to specify <object>.  For a list of these 
flags, see pobject.

u	The <instance field> argument is the offset to any instance data within 
the GenInstance which should be printed out.

u	The variable "printNamesInObjTrees" can be used to print out the actual 
app-defined labels for the objects, instead of the class, where available. 
This variable defaults to false.

See Also:	gup, vistree, impliedgrab, systemobj, pobject.

n	geosfiles

Usage:	geosfiles

Examples:	"geosfiles"

Synopsis:	Print out all the files for which I/O is currently pending in GEOS.

Notes:	

u	This looks at the same dos structure as sysfiles but this prints only those 
files also listed in GEOS' job file table.

See Also:	sysfiles, sftwalk, fwalk.

n	geos-release



Synopsis:	This variable contains the major number of the version of GEOS running on 
the target PC.

n	geowatch



Usage:	geowatch [<object>]

Examples:	

"geowatch *MyObj" 
Display geometry calls that have reached the object MyObj

"geowatch" 	Display geometry calls that have reached *ds:si (asm) or oself 
(goc)

Synopsis:	This displays geometry calls that have reached a particular object. Only one 
object at a time can be watched in this way.

Notes:	

u	Two conditional breakpoints are used by this function (see cbrk). The 
tokens for these breakpoints are returned. 

u	The special object flags may be used to specify object.  For a list of these 
flags, see pobject.

See Also:	objwatch, mwatch, cbrk, pobject.

n	get-address



Used by the various memory-access commands. Takes one argument, ADDR, 
being the address argument for the command. Typically, the command is 
declared as 

[defcmd cmd {{addr nil}} - ]

allowing the address to be unspecified. This function will return the given 
address if it was, else it will return the last-accessed address (stored in the 
global lastAddr variable as a 3-tuple from addr-parse) in the form of an 
address expression. If no address is recorded (lastAddr is nil), the 
default-addr argument is used. If it is not specified then CS:IP will be used.

n	getcc



Usage:	getcc <flag>

Examples:	

"getcc c"	Get the carry flag.

Synopsis:	Get a flag from the target machine.

Notes:	

u	The first argument is the first letter of the flag to get. The following is a 
list of the flags: 

                t 	trap

               i 	interrupt enable

          d	 direction

          o	 overflow

          s	 sign

          z	 zero

          a	 auxiliary carry

          p	 parity

          c	 carry 

u	This command is handy to run with a breakpoint to stop if a flag is set.

See Also:	setcc, clrcc, compcc.

n	getenv



Usage:	getenv <NAME>

Examples:	

"getenv PTTY"	
Fetches the value of the host machine's PTTY environment 
variable.

Synopsis:	Returns the value for a variable defined in Swat's environment.

Notes:	If the variable isn't defined, this returns the empty string.

See Also:	var, string.

n	get-key-binding



Usage:	get-key-binding <char>

Examples:	

"get-key-binding c"
Gets key binding for the character c.

"get-key-binding \045"
Gets key binding for the % key.

Synopsis:	Gets key binding for given key.

See Also:	alias, bind-key, unbind-key.

n	getvalue



Usage:	getvalue <expr>

Examples:	

"getvalue MSG_META_DETACH"
Returns the integer value of the symbol MSG_META_DETACH.

Synopsis:	This is a front-end to the "addr-parse" command that allows you to easily 
obtain the integer value of any expression. It's most useful for converting 
something the user might have given you to a decimal integer for further 
processing.

Notes:	If the expression you give does not evaluate to an address (whose offset will 
be returned) or an integer, the results of this function are undefined.

See Also:	addr-parse, addr-preprocess.

n	global

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	go



Usage:	go [<address expressions>]

Examples:	

"go"	"go drawLeftLine"

Synopsis:	Go until an address is reached.

Notes:	

u	The <address expressions> argument is as many address expressions as 
desired for breakpoints. Execution is continued until a breakpoint is 
reached. These breakpoints are then removed when the machine stops 
and are only active for the current patient.

See Also:	break, continue, det, quit.

n	grobjtree



Usage:	grobjtree [<address>] [<instance field>] 

Examples:	

"grobjtree" 	Print the grobj tree starting at *ds:si

Synopsis:	Print out a GrObj tree.

Notes:	

u	The address argument is the address of a GrObj Body This defaults to 
*ds:si. 

u	To get the address of the grobj body, use the "pbody" or "target" 
commands. 

See Also:	pbody.

n	gup



Usage:	gup [<address>] [<instance field>]

Examples:	

"gup"	print the generic object at *DS:SI and its ancestors

 "gup @23 GI_states"
print the states of object @23 and its ancestors

"gup -i"	print the generic object under the mouse and the object's 
ancestors

Synopsis:	Print a list of the object and all of its generic ancestors.

Notes:	

u	The address argument is the address to an object in the generic tree. This 
defaults to *DS:SI. The `-i' flag for an implied grab may be used.

u	The special object flags may be used to specify <object>.  For a list of these 
flags, see pobject.

u	The instance field argument is the offset to any instance data within the 
GenInstance which should be printed out.

See Also:	gentree, vup, vistree, impliedgrab.

n	handle

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	handles



Usage:	handles [<flags>] [<patient>]

Examples:	"handles"
"handles -f"
"handles ui"

Synopsis:	Print all handles in-use.

Notes:	

u	The flags argument is a collection of flags, beginning with `-', from the 
following set:

           s	print summary only.

           e	events only.

           p	don't print prevPtr and nextPtr.

           f	fast print-out - this doesn't try to figure out the block type.

                r 	reverse, i.e. starts at the end of the handle table.

               u 	print only those handles that are in-use.

u	The patient argument is a patient whose blocks are to be selectively 
printed (either a name or a core-block's handle ID). The default is to print 
all the blocks on the heap.

u	The following columns can appear in a listing:

HANDLE	The handle of the block

ADDR	The segment address of the block

SIZE	Size of the block in bytes

PREV	The previous block handle (appears with the p flag)

NEXT	The next block handle (appears with the p flag)

FLAGS	The following letters appears in the FLAGS column:
s   sharable,
S  swapable, 
D  discardable, 
L  contains local memory heap, 
d   discarded
            (by LMem module: discarded blocks don't appear here), 
a   attached (notice given to swat whenever state changes)

LOCK	Number of times the block is locked or n/a if FIXED.

OWNER	The process which owns the block

IDLE	The time since the block has been accessed in minutes:seconds

OINFO	The otherInfo field of the handle (block type dependent)

TYPE	Type of the block, for example: R#1 (dgroup) resource number 
one

u	This only prints those handles in memory while `handles' prints all 
handles used.

u	The handles may be printed with lhwalk and phandle.

See Also:	lhwalk, phandle, hgwalk.

n	handsum



Usage:	handsum

Examples:	

"handsum" 	Summarize the use to which the handle table is being put.

Synopsis:	This command analyzes the handle table and prints out a list of the number 
of handles being used by each geode, and for what purpose.

Notes:	

u	The columns of the output are labeled somewhat obscurely, owing to 
horizontal-space constraints. The headings, and their meanings are:

 Res 	Resource handles (i.e. handles for data stored in the geode's 
executable)

 Mem 	Non-resource memory handles

 File 	Open files

 Thds 	Threads

 Evs 	Recorded events

 Qs 	Event queues

 Sems 	Semaphores

 EDat 	Data for recorded events

 Tim 	Timers

 SB 	Saved blocks (handles tracking memory/resource handles 
whose contents will go to an application's state file)

 VMF 	VM files

u	The "handles" command is good at printing out all the handles for a 
particular geode, but it's generally too verbose to use for the entire handle 
table. That's why this command exists. 

u	It's a good idea to issue the command "dcache length 4096" before 
executing this command, as it ensures the entire handle table will end up 
in Swat's data cache, for quick access if you want to use the "handles" 
command immediately afterward. 

n	hbrk



Usage:	hbrk <address> (byte|word) (match|mismatch) <value>

Examples:	

"hbrk scrollTab+10 byte match 0"
print message handlers until a zero is written at scrollTab+10.

"hbrk OLScrollButton+3 word mismatch 0x654f"
Break when the word at OLScrollButton+3 is destroyed.

Synopsis:	Break when a memory location changes.

Notes:	

u	The <address> argument is the address to watch for a change.

u	The (byte|word) argument indicates whether to watch a byte or a word 
for a change.

u	The (match|mismatch) argument indicates whether to break if the value 
at the address matches or mismatches the value hbrk is called with.

u	hbrk emulates a hardware breakpoint by checking at every message call 
to see if a location in memory has been written to. If so, swat breaks and 
tells between which two messages the write occurred. The information 
and the return stack will hopefully guide you to the offending line of code.

u	The command creates two breakpoints. Remove these to get rid of the 
hardware breakpoint.

See Also:	brk, mwatch, showcalls.

n	heapspace



Usage:	heapspace <geode>
heapspace total 
heapspace syslib 

Examples:	

"heapspace geomanager" 
print out "heapspace" value for geomanager

"heapspace total" 
print out maxTotalHeapSpace

"heapspace syslib"
print out space being used by system libraries.

Synopsis:	Prints out how much space the program requires on the heap. This value may 
then be used in a "heapspace" line of the program's .gp field. This command 
only determines present usage-to determine the most heapspace your geode 
will ever use requires that you make it allocate as much space as it ever will. 
This means pulling down all menus, opening all dialog boxes, and generally 
building out all UI gadgetry. The value this command prints is roughly the 
non-discardable heap usage by the app and any transient libraries that it 
depends on, plus an additional amount for thread activity.

n	help



Usage:	help [<command>]

Synopsis:	This is the user-level access to the on-line help facilities for Swat. If given a 
topic (e.g. "brk") as its argument, it will print all help strings defined for the 
given topic (there could be more than one if the same name is used for both a 
variable and a procedure, for instance). If invoked without arguments, it will 
enter a browsing mode, allowing the user to work his/her way up and down 
the documentation tree.

n	help-fetch



Usage:	help-fetch <topic-path>

Examples:	"help-fetch top.patient"

Synopsis:	Fetches the help string for a given topic path in the help tree.

Notes:	If there is more than one node with the given path in the help tree, only the 
string for the first node will be returned.

n	help-fetch-level



Usage:	help-fetch-level

Examples:	

"help-fetch-level top.prog.obscure"
Returns the topics within the "top.prog.obscure" level of the 
help tree.

Synopsis:	Returns a list of the topics available at a given level in the help tree.

Notes:	The result is a list of node names without leading path components.

See Also:	help-fetch.

n	help-help



Usage:	help-help

Synopsis:	Provides help about using the help command (q.v.)

See Also:	help.

n	help-is-leaf



Usage:	help-is-leaf <topic-path>

Examples:	

"help-is-leaf top.prog"
See if top.prog is a leaf node in the help tree (i.e. if it has no 
children).

Synopsis:	Determines whether a given path refers to a help topic or a help category.

Notes:	Returns one if the given path refers to a leaf node, zero if it is not.

See Also:	help-fetch, help-fetch-level.

n	help-minAspect



Usage:	var help-minAspect [<ratio-times-ten>]

Synopsis:	If non-zero, contains the minimum aspect ratio to be maintained when 
displaying tables in the help browser. The ratio is expressed as the fraction

entries_per_column*10/number_of_columns

E.g. a minimum ratio of 1.5 would be 15. (We multiply by ten because Swat 
doesn't support floating point numbers.)

n	help-scan



Usage:	help-scan <pattern>

Examples:	

"help-scan break"
Looks for all nodes at any level of the help tree whose 
documentation includes the pattern "break".

Synopsis:	Scans all nodes in the help tree for those whose documentation matches a 
given pattern.

Notes:	

u	The result is a list of topic-paths.

See Also:	help-fetch.

n	help-verbose



Usage:	var help-verbose [0|1)]

Synopsis:	If non-zero, performs verbose prompting.

n	hex



Usage:	hex <number>

Examples:	

"hex 034"	print hex equivalent of octal 34.

"hex 12"	print hex equivalent of decimal 12.

Synopsis:	Print hexadecimal equivalent of a number.

n	hgwalk



Usage:	hgwalk

Examples:	

"hgwalk"	print statistics on all geodes

Synopsis:	Print out all geodes and their memory usage.

n	history



Usage:	history [<args>]

Examples:	

 "history 10" 	
Prints the last 10 commands entered via the "history subst" 
command.

 "history subst $line"
 Performs history substitution on the string in $line, enters the 
result in the history queue and returns the result.

 "var n [history cur]" 
Stores the number of the next string to be entered via "history 
subst" in the variable n.

 "history set 50" 
Limit the number of entries in the queue to 50.

 "history fetch 36" 
Returns the string entered as command number 36 in the 
history queue.

Synopsis:	This command manipulates the history list. Options are:

<number>	Prints the most-recent <number> commands

set <queue-size>
	Sets the number of commands saved

subst <str>	Performs history substitution on <str> and enters it into the 
history queue.

cur	Returns the current history number. If no argument is given, 
all saved commands are printed.

fetch <n>	Returns the string entered as command number <n> in the 
history queue.

See Also:	top-level-read

n	hwalk



Usage:	hwalk [<flags>] [<patient>]

Examples:	

"hwalk"	display the heap

"hwalk -e"	display the heap and perform error checking

"hwalk -r ui"
display the heap owned by the ui in reverse order

Synopsis:	Print the status of all blocks on the global heap.

Notes:	

u	The <flags> argument is a collection of flags, beginning with `-', from the 
following set:

r	print heap in reverse order (decreasing order of addresses)

p	print prevPtr and nextPtr as well.

e	do error-checking on the heap.

l	just print out locked blocks

f	fast print-out-this doesn't try to figure out the block type

F	print out only fixed (or pseudo-fixed) resources.

c	Print out only code resources (discardable or fixed non-lmem 
non-dgroup resources).

s <num>	start at block <num>

u	The patient argument is a patient whose blocks are to be selectively 
printed (either a name or a core-block's handle ID). The default is to print 
all the blocks on the heap.

u	The following columns can appear in a listing:

HANDLE	The handle of the block

ADDR	The segment address of the block

SIZE	Size of the block in bytes

PREV	The previous block handle (appears with the p flag)

NEXT	The next block handle (appears with the p flag)

FLAGS	The following letters appears in the FLAGS column:
s     sharable 
S    swapable 
D   discardable 
L    contains local memory heap 
d    discarded 
         (by LMem module: discarded blocks don't appear here) 
a    attached (notice given to swat whenever state changes)

LOCK	Number of times the block is locked or n/a if FIXED.

OWNER	The process which owns the block

IDLE	The time since the block has been accessed in minutes:seconds

OINFO	The otherInfo field of the handle (block type dependent)

TYPE	Type of the block, for example:
R#1 (dgroup) Resource number one, named "dgroup"
Geode Internal control block for a geode 
WINDOW, GSTATE, 
   Internal structures of the given type
GSTRING, FONT_BLK, FONT OBJ(write:0) 
   Object block run by thread write:0 
VM(3ef0h)... 
   VM block from VM file 3ef0h

u	This only prints those handles in memory while `handles' prints all 
handles used.

u	The handles may be printed with lhwalk and phandle.

See Also:	lhwalk, phandle, handles, hgwalk.

n	iacp



Usage:	iacp -ac 
              prints all connections

iacp -l 
             prints all lists without connections

iacp -d 
             prints all open documents

iacp <obj> 
             prints all connections to which <obj> is party

n	ibrk



Set a breakpoint interactively. At each instruction, you have several options:

q 	Quit back to the command level.

 n 	Go to next instruction (this also happens if you just hit return).

 p 	Go to previous instruction.

 P	 Look for a different previous instruction.

 ^D 	Go down a "page" of instructions. The size of the page is 
controlled by the global variable ibrkPageLen. It defaults to 10.

 ^U 	Go up a "page" of instructions.

 b 	Set an unconditional breakpoint at the current instruction and 
go back to command level.

 a 	Like 'b', but the breakpoint is set for all patients.

 t 	Like 'b', except the breakpoint is temporary and will be	 
removed the next time the machine stops.

 B 	Like 'b', but can be followed by a command to execute when the 
breakpoint is hit.

 A 	Like 'B', but for all patients.

 T 	Like 'B', but breakpoint is temporary.

n	ibrkPageLen



Usage:	var ibrkPageLen [<number-of-lines>]

Synopsis:	Number of instructions to skip when using the ^D and ^U commands of ibrk.

n	if

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	ignerr



Usage:	ignerr

Examples:	

"ignerr" ignore error and continue

"ignerr MyFunc::done" ignore error and continue at MyFunc::done.

Synopsis:	Ignore a fatal error and continue.

Notes:	

u	The address argument is the address of where to continue execution. If 
not specified then CS:IP is taken from the frame. 

u	The stack is patched so that execution can continue in the frame above 
the fatal error handling routine.

See Also:	why, backtrace.

n	imem



Usage:	imem [<address>] [<mode>]

Examples:	

"imem"	enter imem mode at DS:SI

"imem ds:di"
enter imem mode at DS:SI

Synopsis:	Examine memory and modify memory interactively.

Notes:	

u	The address argument is the address to examine. If not specified, the 
address after the last examined memory location is used. If no address 
has been examined then DS:SI is used for the address.

u	The mode argument determines how the memory is displayed and 
modified. Each of the four modes display the memory in various 
appropriate formats. The modes are:

u	The default mode is swat's best guess of what type of object is at the 
address.

u	imem lets you conveniently examine memory at different locations and 
assign it different values. imem displays the memory at the current 
address according to the mode. From there you can move to another 
memory address or you can assign the memory a value.

u	You may choose from the following single-character commands:

b, w, d,i	Sets the mode to the given one and redisplays the data.

n, j, <Return>
Advances to the next data item. The memory address advances 
by the size of the mode.

p, k	Returns to the preceding data item. The memory address 
decreases by the size of the mode. When displaying 
instructions, a heuristic is applied to locate the preceding 
instruction. If it chooses the wrong one, use the `P' command to 
make it search again.

<space>	Clears the data display and allows you to enter a new value 
appropriate to the current display mode. The "assign" 
command is used to perform the assignment, so the same rules 
apply to it, with the exception of `- and "-quoted strings. A 
string with `s around it (`hi mom') has its characters poked into 
memory starting at the current address. A string with "s 
around it ("swat.exe") likewise has its characters poked into 
memory, with the addition of a null byte at the end. This 
command is not valid in instruction mode.

q	quit imem and return to command level. The last address 
accessed is recorded for use by the other memory-access 
commands.

^D	Display a "page" of successive memory elements in the current 
mode.

^U	Display a "page" of preceding memory elements in the current 
mode.

h, ?	This help list.

 For ^D and ^U, the size of a "page" is kept in the global variable 
imemPageLen, which defaults to 10.

See Also:	bytes, words, dwords, assign.

n	imemPageLen



Usage:	var imemPageLen [<numlines>]

Synopsis:	Contains the number of elements to display when imem is given the ^D or 
^U command.

n	impliedgrab



Usage:	impliedgrab

Examples:	

"gentree [impliedgrab]"
print the generic tree under the mouse

Synopsis:	Print the address of the current implied grab, which is the screen object 
grabbing the mouse.

Notes:	

u	This command is normally used with gentree to get the generic tree of an 
application by placing the mouse on application's window and issuing the 
command.

See Also:	systemobj, gentree.

n	impliedwin



Usage:	impliedwin

Notes:	

"wintree [impliedwin]"
print the window tree of the window under the mouse

Synopsis:	Print the address of the current implied window (the window under the 
mouse).

Notes:	

u	Note that a window handle is returned.

u	This command is normally used with wintree. One may also use the print 
command if they properly cast the handle.

n	index

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	info

This is a Tcl primitive. See "Tool Command Language," Chapter 5.

n	int



Usage:	int [<int level> <state>]

Examples:	

"int"	report the interrupt statuses

"int 1:1 on"	allow keyboard interrupt while in swat

Synopsis:	Set or print the state of the two interrupt controllers for when then machine 
is stopped in Swat.

Notes:	

u	If no arguments are given, the current state is printed.

u	The <int level> argument is specified by their names or their numbers 
with the form <controller>:<number>. <controller> is either 1 or 2, and 
<number> ranges from 0 to 7. The interrupts and their numbers are:

Timer 1:0	System timer. Probably dangerous to enable.

Keybd 1:1	Keyboard input.

Slave 1:2	This is how devices on controller 2 interrupt. Disabling this 
disables them all.

Com2 1:3	This is the port usually used by Swat, so it can't be disabled.

Com1 1:4	The other serial port -- usually the mouse.

LPT2 1:5	The second parallel port

Floppy 1:6	Floppy-disk drive

LPT1 1:7	First parallel port

Clock 2:0	Real-time clock

Net 2:1	Network interfaces (?)

FPA 2:5	Coprocessor

HardDisk 2:6
Hard-disk drive

u	The <state> argument is either on or off.

n	intFormat



Usage:	var intFormat [<format-string>]

Examples:	

"var intFormat %d"
Sets the default format for printing unsigned integers to 
decimal.

Synopsis:	$intFormat contains the string passed to the "format" command to print an 
integer.

Notes:	The default value is {%xh}, which prints the integer in hexadecimal, followed 
by an "h".

See Also:	print, byteAsChar.

n	intr



Catch, ignore, or deliver an interrupt on the target PC. First argument is the 
interrupt number. Optional second argument is "catch" to catch delivery of 
the interrupt, "ignore" to ignore the delivery, or "send" to send the interrupt 
(the machine will keep going once the interrupt has been handled). If no 
second argument is given, the interrupt is delivered.

n	io



Usage:	io [w] <port> [<value>]

Examples:	

"io 21h"	Reads byte-sized I/O port 21h.

"io 20h 10"	Writes decimal 10 to byte-sized I/O port 20h.

Synopsis:	Provides access to any I/O port on the PC.

Notes:	

u	If you give the optional first argument "w" then Swat will perform a 
16-bit I/O read or write, rather than the default 8-bit access. Be aware 
that most devices don't handle this too well. 

u	<port> must be a number (in any radix); it cannot be a register or other 
complex expression. 

u	If you don't give a <value>, you will be returned the contents of the I/O 
port (it will not be printed to the screen). 

n	irq



Usage:	irq
irq (no|yes)
irq (set|clear)

Examples:	

"irq"	Returns non-zero if an interrupt is pending.

"irq no"	Disable recognition and acting on a break request from the 
keyboard.

"irq set"	Pretend the user typed Ctrl-C.

Synopsis:	Controls Swat's behavior with respect to interrupt requests from the 
keyboard.

Notes:	

u	Swat maintains an interrupt-pending flag that is set when you type 
Ctrl+C (it can also be set or cleared by this command). It delays acting on 
the interrupt until the start of the next or the completion of the current 
Tcl command, whichever comes first. 

u	When given no arguments, it returns the current state of the 
interrupt-pending flag. This will only ever be non-zero if Swat is ignoring 
the flag (since the command wouldn't actually return if the flag were set 
and being paid attention to, as the interpreter would act on the flag to 
vault straight back to the command prompt). 

u	If given "no" or "yes" as an argument, it causes Swat to ignore or pay 
attention to the interrupt-pending flag, respectively. 

u	You can set or clear the flag by giving "set" or "clear" as an argument.

n	is-obj-in-class



Usage:	is-obj-in-class <obj-addr> <class-name>

Examples:	

"is-obj-in-class ^l4e10h:1eh GenPrimaryClass" 
see if the object at ^l4e10h:1eh is in GenPrimaryClass.

Synopsis:	Returns whether a given object in the specified class.

Notes:	

u	Returns one if the object is in the specified class, zero otherwise. It will 
return one if the object's class is a subclass of the passed class.

u	The special object flags may be used to specify <object>.  For a list of these 
flags, see pobject.

See Also:	psup.

n	istep



Usage:	istep [<default command>]

Examples:	

"is"	enter instruction step mode

"istep n"	enter instruction step mode, <ret> does a next command

Synopsis:	Step through the execution of the current patient. This is THE command for 
stepping through assembly code.

Notes:	

u	The default command argument determines what pressing the <Return> 
key does. By default, <Return> executes a step command. Any other 
command listed below may be substituted by passing the letter of the 
command.

u	Istep steps through the patient instruction by instruction, printing 
where the ip is, what instruction will be executed, and what the 
instruction arguments contain or reference. Istep waits for the user to 
type a command which it performs and then prints out again where istep 
is executing.

u	This is a list of istep commands:

q, <Esc>, ` `	Stops istep and returns to command level.

b	Toggles a breakpoint at the current location.

c	Stops istep and continues execution.

n	Continues to the next instruction, skipping procedure calls, 
repeated string instructions, and software interrupts. Using 
this procedure, istep only stops when the machine returns to 
the right context (i.e. the stack pointer and current thread are 
the same as they are when the "n" command was given). 
Routines which change the stack pointer should use "N" 
instead.

o	Like "n" but steps over macros as well.

l	Goes to the next library routine.

N	Like `n', but stops whenever the breakpoint is hit, whether 
you're in the same frame or not.

O	Like `N' but steps over macros as well.

m, M	Goes to the next method called. Doesn't work when the 
message is not handled anywhere.

F	Finishes the current message.

f	Finishes out the current stack frame.

s, <Return>	Steps one instruction.

A	Aborts the current stack frame.

S	Skips the current instruction

B	Backs up an instruction (opposite of "S").

J	Jump on a conditional jump, even when "Will not jump" 
appears. This does not change the condition codes.

g	Executes the `go' command with the rest of the line as 
arguments.

e	Executes a Tcl command and returns to the prompt.

r	Lists the registers (uses the regs command)

R	References either the function to be called or the function 
currently executing.

h, ?	Displays a help message.

u	If the current patient isn't the actual current thread, istep waits for the 
patient to wake up before single-stepping it.

See Also:	sstep, listi, ewatch.
