Swat Reference

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

• 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.
• 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.
• 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 .
• * +
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.

  _print ...
  addr-parse ...
  alias ...
  assign ...
  bits ...
  car ...
  continue-patient ...
  dbrk ...
  debug ...
  delassoc ...
  drivewalk ...
  elist ...
  fatalerr_auto_explain ...
  flagwin ...
  fpstack ...
  func ...
  getenv ...
  handsum ...
  help ...
  hwalk ...
  imem ...
  intr ...
  keyboard ...
  load ...
  memsize ...
  noStructEnum ...
  objmessagebrk ...
  patchin ...
  pdisk ...
  pgs ...
  pinst ...
  pobjmon ...
  print-cell ...
  printRegions ...
  ptext ...
  pvismon ...
  read-reg ...
  ret ...
  scope ...
  showcalls ...
  smatch ...
  stdpaths ...
  stream ...
  symbolCompletion ...
  text-fixup ...
  twalk ...
  varwin ...
  wclear ...

_print

 _print <expression>

Examples:

"_print ax-10"

print ax less 10 decimal.

Print the value of an expression.

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.

abort

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.

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.

• If no argument is given, code through the current frame is aborted.
• <frame num> are the numbers that appear at the left of the backtrace.

See Also: finish, backtrace.

abortframe

abortframe <frame-token>

Examples:

"abortframe $cur"

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

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

• The argument is a frame token, as returned by the "frame" command.
• 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.
• The command returns zero if the machine aborted executing in the given frame; non-zero if it was interrupted before that could happen.

addr-parse

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

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

• This will generate an error if there's an error parsing the <addr>
• <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.
• <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.
• <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.
• 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.
• 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.
• 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.

addr-preprocess

 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.

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

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

addr-with-obj-flag

addr-with-obj-flag

Examples:

"var addr [addr-with-obj-flag $addr]"

If $addr is "-i", returns the address of the current implied grab.

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.

• Special values accepted for <address>:

-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

• 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
• If <address> isn't one of the above, this just returns <address>.

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

alias

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.

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

• If you give no arguments the current aliases are all displayed.
• 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.
• The <body> string is usually in curly braces, as it usually involves whitespace and can contain newlines for the longer aliases.
• 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.
• 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.
• $* will interpolate all the arguments.
• $# will interpolate the actual number of arguments.
• If you do not use any of these pseudo-variables, all the arguments given to the alias will be appended to the <body>.
• Interpolation of the values for these pseudo-variables occurs regardless of braces in the <body>.
• It is an error to specify an argument number when there are fewer than that many arguments given to the alias.

See Also: unalias.

alignFields

var alignFields [(0|1)]

Examples:

"var alignFields 1"

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

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.

• 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.
• The default value for this variable is zero.

See Also: print.

antifreeze

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.

antithaw

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.

appobj

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

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

See Also: impliedgrab.

apropos

apropos [<string>]

Examples:

"apropos vis"

Find all commands related to vis

"apropos text"

Find all commands related to text

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

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

aset

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.

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

• <array-name> is the name of the variable, not the value of the variable to be altered.
• This command returns nothing.
• 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.

assoc

assoc <list> <key>

Examples:

"assoc $classes GenPrimaryClass"

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

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.

• A typical associative list is made of key/value pairs, like this:
  {{<key> <value>} {<key> <value>} ...}
• 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.

assign

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

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.

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

att

att [<args>]

Examples:

"att"

attach Swat to GEOS.

Attach Swat to GEOS.

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.

attach

attach [<boot>]

Examples:

"attach"

attach to the target PC

Attach swat to the target PC.

• 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.
• If you give no <boot> argument, swat will use the most-recent one.
• By default, swat will locate the symbols for all geodes and threads active on the PC when it attaches.
• If any geode has changed since you detached from the PC, its symbols are re-read.

See Also: att, detach, quit.

autoload

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.

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

• 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.
• 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).
• 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, defcommand, proc.

backtrace

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

Print all the active stack frames for the patient.

• The <frames to list> argument is the number of frames to print. If not specified, then all are printed.
• 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.

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

bin

bin <number> [<field-width>]

Examples:

"bin 5"

returns "0101" (five in binary)

"bin 10h"

returns "0001 0000"

"bin 10h 3"

returns "0000 0001 0000"

Prints numbers in binary.

• The field width is in nibbles.
• The default field width is the minium number of nibbles to display the number.

bindings

bindings

Shows all current key bindings

bind-key

bind-key <ascii_value> <function>

Examples:

"bind-key \321 scroll_srcwin_down"

Binds scroll-down key to the scroll_srcwin_down Tcl routine.

Binds an ASCII value to a function.

See Also: alias, unbind-key.

bits

bits [<address>] [<length>] [<type>]

Examples:

"bits"

lists 16 bytes worth of bits at ds:si

"bits ds:di 8"

lists 8 bytes worth of bits at ds:di

"bits ds:di 24 w"

lists 24 words worth of bits at ds:di

Examine memory as a dump of bits in sets of 8, 16, or 32 (byte,word, or dword).

• 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.
• The length argument is the number of units to examine. It defaults to 16.
• They type argument is bytes, words or dwords. It defaults to bytes.
• Pressing return after this command continues the list.

break-taken

 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.

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

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.

brkload

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.

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

• Only one brkload may be active at a time; registering a second one automatically unregisters the first.
• If you give no <handle> argument, the previously-set brkload will be unregistered.

See Also: handle.

byteAsChar

var byteAsChar [(0|1)]

Examples:

"var byteAsChar 1"

Print byte variables as characters.

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

• If $byteAsChar is 0, $intFormat is used.
• The default value for this variable is 0.

bytes

bytes [<address>] [<length>]

Examples:

"bytes"

lists 16 bytes at DS:SI

"bytes ds:di 32"

lists 32 bytes at DS:SI

Examine memory as a dump of bytes and characters.

• 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.
• The <length> argument is the number of bytes to examine. It defaults to 16.
• Pressing <Return> after this command continues the list.
• Characters which are not typical ASCII values are displayed as a period.

See Also: words, dwords, imem, assign.

call

 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"'

Call a function in the current thread.

• 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.
• 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).
• All current registers are preserved and restored when the call is complete. Variables are not.
• 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.
• 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.
• 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.

call-patient

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

Examples:

"call-patient MemLock bx $h"

Locks down the block whose handle ID is in $h.

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.

• Returns non-zero if the call completed successfully.
• 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.
• Arguments after <function> are as for "call".
• If the called routine is in movable memory, this will lock the containing block down before issuing the call, as you'd expect.
• Calling anything that makes message calls while on the geos:0 thread is a hazardous undertaking at best.

See Also: call.

car

car <list>

Examples:

"car $args"

Returns the first element of $args.

Returns the first element of a list.

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.

cdr

cdr <list>

Examples:

"cdr $args"

Returns the remaining arguments yet to be processed.

Returns all but the first element of a list.

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.

classes

classes [<patient>]

Examples:

"classes "

Print list of classes in current patient.

"classes myapp"

Print list of classes in myapp patient.

Prints list of classes defined by the given patient.

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.

clrcc

clrcc <flag> [<value>]

Examples:

"clrcc c"

clear the carry flag

Clear a flag in the target computer.

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.

columns

columns

Examples:

"columns"

Return the number of columns on the screen.

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

compcc

compcc <flag>

Examples:

"compcc c"

complement the carry flag

Complement a flag in the target computer.

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.

completion

completion <list-of-names>

Examples:

"completion {martial marital}"

Returns "mar," the common prefix.

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

condenseSmall

var condenseSmall [(0|1)]

Examples:

"var condenseSpecial 0"

Force even small structures to be printed one field per line.

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.

The default value of this variable is one.

See Also: print, condenseSpecial.

condenseSpecial

var condenseSpecial [(0|1)]

Examples:

"var condenseSpecial 0"

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

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

• The default value of this variable is 1.
• 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.

cont

cont

Examples:

"cont"

continue execution

"c"

continue execution

Continue GEOS.

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

content

content

Examples:

"vistree [content]"

print the visual tree of the content of the view under the mouse.

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

• 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.
• If the pointer is not over a GenView object, this is the same as the "impliedgrab" command.

See Also: systemobj, gentree, impliedgrab.

continue-patient

continue-patient

Examples:

"continue-patient"

Allow the target machine to continue executing GEOS.

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

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.

cup

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

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.

current-level

current-level

Examples:

"var l [current-level]"

Store the current interpreter nesting level in $l.

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

• This is currently used only to modify the command prompt to indicate the current nesting level.
• The top-most command loop is level one.

See Also: top-level.

current-registers

current-registers

Examples:

"current-registers"

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

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

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

cvtrecord

cvtrecord <type> <number>

Examples:

"cvtrecord [symbol find type HeapFlags] 36"

Return a value list for the number 36 cast to a HeapFlags record.

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

• <type> is a type token for a record (or a structure made up exclusively of bitfields).
• <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.
• Returns a value list suitable for "value store" or for "fmtval".

See Also: value, fmtval, expr, getvalue.

cycles

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

See Also: timingProcessor.

dbrk

dbrk <addr> <num> [<command>|default]
dbrk set <break> <num> [<command>|default]
dbrk list [<break>]
dbrk {clear,delete} <break>
dbrk cur <break> <num>
dbrk max <break> <num>
dbrk cmd <break> [<command>]
dbrk reset <break>
dbrk enable <break>
dbrk disable <break>

Examples:

"dbrk ObjMessage 30"

Break at the 30th call to ObjMessage

"dbrk set 5 30"

Break after hitting brk5 30 times.

"dbrk set brk3 10 default"

Break after hitting brk3 10 times; Each time brk3 is hit, perform the default command.

"dbrk cmd brk2 {echo foo}"

Echo a string whenever brk2 is hit.

"dbrk cmd brk2 default"

Use the default command for brk2.

"dbrk disable 2"

Stop counting brk2; it will now always be taken.

This command creates "delayed" breakpoints, creating breakpoints that don't activate until they've been hit a specified nuber of times.

• break may be a number, or a full breakpoint token (brk<n>) num is a number; and command is a string that will be evaluated. If command may also be the string "default", in which case a default command will be used. The first argument to dbrk may be abbreviated; only the first 3 characters are significant.
• Deleting a breakpoint with "brk del" removes the dbrk also.
• With the exception of brk, all the commands that take <break> must be given a breakpoint that has been delayed. The "dbrk list" command will show these.
• "dbrk list" will show how many times a breakpoint has been hit, the maximum number of times to skip the breakpoint, and the command to evaluate whenever the breakpoint is hit. If no breakpoint is passed, the status of all dbrks will be shown.
• "dbrk clear" and "dbrk delete" are synonyms. These commands will cause the delayed breakpoint to become normal again, and clear out the global variables used to store the dbrk's state: brk N cur, brk N max, brk N cmd where N is a number.
• "dbrk cur", "dbrk max", and "dbrk cmd" set the current count, the maximum count, and the command of the specified breakpoint respectively.
• "dbrk reset break " is a quick way of saying "dbrk cur break 0"
• "dbrk enable" and "dbrk disable" are used to enable and disable a dbrk. Disabled dbrks will always be taken, and their counter will not be incremented.
• Since this command is just a front-end to brk cmd, you can use dbrk and brk cond to create more complex breakpoints; for instance, you can "mwatch MSG_VIS_DRAW ", then "dbrk set brk 30 print-method" to break after MSG_VIS_DRAW has been received 30 times.

dcache

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.

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

• 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.
• The default cache block size is 32 bytes, with a default cache length of 64 blocks.
• 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.
• The <blockSize> must be a power of 2 and no more than 128.
• Changing the block size causes all cached blocks to be flushed (any modified cache blocks are written to the PC).
• Changing the cache length will only flush blocks if there are more blocks currently in the cache than are allowed by the new length.
• The "dcache stats" command prints statistics giving some indication of the efficacy of the data cache. It does not return anything.
• 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.

dcall

dcall [<args>]

Examples:

"dcall Dispatch"

Display when the routine Dispatch is called

"dcall none"

stop displaying all routines

Display calls to a routine.

• The <args> argument normally is the name of the routine to monitor. Whenever a call is made to the routine its name is displayed.
• If `none' or no argument is passed, then all the routines will stop displaying.
• 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.

debug

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

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.

• The breakpoint for <proc-name> can be removed using the "undebug" command.
• <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.

debugger

var debugger [<command-name>]

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

debugOnError

var debugOnError [(0|1)]

Examples:

"var debugOnError 1"

Turn on debugging when there's a Tcl error.

Enter debug mode when Swat encounters a Tcl error.

• The 0|1 simply is a false|true to stop and debug upon encountering an error in a Tcl command.
• If an error is caught with the catch command, Swat will not enter debug mode.

See Also: debugger.

defcmd

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.

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

• <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."
• 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.

defcommand

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

Examples: Look at almost any .tcl file in the system library for an example.

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

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

defhelp

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.

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

• This cannot override a string that resides in the /pcgeos/tcl/doc file.
• You only really need this if you have defined your own help-topic category.
• <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.

defvar

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.

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.

• If the variable is one the user may want to change, give it on-line help using the <help-class> and <help-string> arguments.
• <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.

delassoc

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

Examples:

"delassoc $val murphy"

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

Deletes an entry from an associative list.

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

detach

detach [<options>]

Examples:

"detach cont"

continue GEOS and quit swat

Detach swat from the PC.

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

dirs

dirs

Prints the directory stack for the current thread.

See Also: pwd, stdpaths.

discard-state

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 .

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

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.

diskwalk

diskwalk <drive>

Examples:

"diskwalk F"

Prints the disks registered in drive F.

"diskwalk"

Prints all the disks registered with the system.

Prints out the information on registered disks.

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.

display

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

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

• 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.
• You can list all the active displays by giving "list" instead of a number as the first argument.
• 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.

dosMem

dosMem

Examples:

"dosMem"

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

down

down [<frame offset>]

Examples:

"down"

move the frame one frame down the stack

"down 4"

move the frame four frames down the stack

Move the frame down the stack.

• 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.
• This command may be repeated by pressing <Return>.

See Also: backtrace, up.

drivewalk

drivewalk

Examples:

"drivewalk"

Prints the table of drives known to the system.

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

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

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

dumpstack

dumpstack [<address>] [<length>]

Examples:

"dumpstack"

dump the stack at SS:SP

"ds ds:si 10"

dump ten words starting at DS:SI

Dump the stack and perform some simple interpretation upon it.

• The <address> argument is the address of the list of words to dump. This defaults to SS:SP.
• The <length> argument is the number of words to dump. This defaults to 50.
• This dumps the stack and tries to make symbolic sense of the values, in terms of handles, segments, and routines.
• 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.

dwordIsPtr

var dwordIsPtr [(0|1)]

Examples:

"var dwordIsPtr 1"

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

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

• For debugging C code, a value of 0 is more appropriate, while 1 is best for debugging assembly language.
• The default value for this variable is 1.

See Also: intFormat, print.

dwords

dwords [<address>] [<length>]

Examples:

"dwords"

lists 4 double words at DS:SI

"dwords ds:di 8"

lists 8 double words at DS:DI

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

• 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.
• The <length> argument is the number of dwords to examine. It defaults to 4.
• Pressing <Return> after this command continues the list.

See Also: bytes, words, imem, assign.

ec

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

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

• 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

adds register checking to Swat. If this flag is turned on, Swat will check whether ds and es are valid memory handle at various points in the debugging cycle by calling ECCheckSegment() .

lmemMove

force lmem blocks to move whenever possible

unlockMove

forces unlocked blocks to move whenever possible. This ensures that your code isn't referencing into an unstable block location. I.e., a block which may move, but usually doesn't , therefore causing non-reproducible (and quite frustrating) errors.

vm

vmem file structure checking

vmemDiscard

force vmem blocks to be discarded if possible

• If there isn't an argument, `ec' reports the current error checking flags.
• 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.

echo

echo [-n] <string>+

Examples:

"echo -n yes?"

Prints "yes?" without a newline.

"echo hi mom"

Prints "hi mom" followed by a newline.

Prints its arguments, separated by spaces.

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

See Also: flush-output.

elist

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

Display all events pending for a patient.

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.

ensure-swat-attached

ensure-swat-attached

Examples:

"ensure-swat-attached"

Stop if Swat isn't attached to GEOS.

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

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.

eqfind

eqfind [-p]

Examples:

"eqfind" list all event queues in the system.

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

Display all event queues in the system.

See Also: elist, eqlist, erfind.

eqlist

eqlist <queue handle> <name>

Examples:

"eqlist 8320 geos:2"

show the event list for geos:2

Display all events in a queue.

• The queue handle argument is the handle to a queue.
• The name argument is the name of the queue.

See Also: elist.

erfind

erfind [-p]

Examples:

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

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

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.

exit

exit <patient>

Examples:

"exit faxmon"

Causes the faxmon application to exit.

Sends messages required to make an application quit.

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.

exit-thread

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.

Exit the current thread.

• The exit code argument is the status to return to the current thread's parent, which defaults to zero.
• Do not invoke this function for an event-driven thread; send it a MSG_META_DETACH instead.

See Also: quit.

explain

explain

Examples: "explain"

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

• 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.
• 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 .
• This command also relies on programmers having explained their FatalErrors when defining them.
• For certain fatal errors, additional information is provided by invoking the command <patient>::<error code name>, if it exists.

explode

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.

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.

This is especially useful for parsing command switches.

See Also: foreach, index, range.

fatalerr_auto_explain

var fatalerr_auto_explain [(0|1)]

Examples:

"var fatalerr_auto_explain 0"

Turn off automatic generation of the explanation for any fatal-error hit.

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.

• Explanations are loaded from <patient>.fei files stored in the system Tcl library directory when an error in <patient> is encountered.
• You can also obtain an explanation of an error via the "explain" command.

fetch-optr

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.

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

• <offset> is an actual offset, not a chunk handle, while <handle> is a handle ID, not a handle token.
• 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.
• 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.

fhandle

fhandle <handle id>

Examples: "fhandle 3290h"

Print out a file handle.

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

See Also: fwalk.

field

field <list> <field name>

Examples:

"field [value fetch ds:si MyBox] topLeft"

return the offset of the topLeft field in MyBox

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

• The <list> argument is a structure-value list from the "value" command.
• The <field name> argument is the field in the structure.

See Also: value, pobject, piv.

fieldwin

fieldwin

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

find

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

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

• 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.
• There must already be a source window displayed for find to work.
• Possible options to find are:

-r

reverse search

-i

case insensitive search

find-opcode

find-opcode <addr> <byte>+

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.

finish

finish [<frame num>]

Examples:

"finish"

finish executing the current frame

"finish 3"

finish executing up to the third frame

Finish the execution of a frame.

• 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.
• The machine continues to run until the frame above is reached.

See Also: backtrace.

finishframe

finishframe [<frame-token>]

Examples:

"finishframe $cur"

Run the machine to continue until it has returned from a particular stack frame.

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

• 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.
• The command returns zero if the machine finished executing in the given frame; non-zero if it was interrupted before that could happen.
• The argument is a frame token, as returned by the "frame" command.

See Also: event, frame, finish.

flagwin

flagwin [<on>|off]

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

See Also: pflags.

flowobj

flowobj

Examples:

"pobject [flowobj]"

print out the flow object.

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

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

flush-output

flush-output

Examples:

"flush-output"

Forces pending output to be displayed.

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

See Also: echo.

fmtoptr

fmtoptr <handle-id> <chunk>

Examples:

"fmtoptr 3160h o"

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

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

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

fmtval

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.

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.

• <value-list> is the return value from "value fetch". You can, of course, construct one of these if you feel so inclined.
• <type-token> is the token for the type-description used when fetching the value.
• <indent> is the base indentation for all output. When "fmtval" calls itself recursively, it increases this by 4 for each recursive call.
• <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.
• <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.

focus

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.

Prints the focus hierarchy below an object.

• If no argument is specified, the system object is used.
• The special object flags may be used to specify <object>. For a list of these flags, see pobject.
• 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.
• 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.

focusobj

focusobj

Examples:

"focusobj"

print model hierarchy from system object down

"pobj [focusobj]"

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

Returns the object with the focus.

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

fonts

fonts [<args>]

Examples:

"fonts"

summarize general font usage

"fonts -u"

list fonts currently in use

Print various font info.

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

• 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, pfontinfo.

fpstack

fpstack

Examples:

"fpstack"

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

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

See Also: fpu-state.

fpu-state

fpustate [<mode>]

Examples:

"fpustate"

Print out the state of the coprocessor.

"fpustate w"

Dumps actual words of the numbers.

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

See Also: fpstack.

frame

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.

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.

• Subcommands may be abbreviated uniquely.
• 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.
• Frame tokens are valid only while the target machine is stopped and are invalidated when it is continued.
• 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.
• "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.
• "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.
• "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.
• For any subcommand where the <frame> token is optional, the currently- selected frame will be used if you give no token.
• "frame cur" returns the token for the currently-selected stack frame.
• "frame set" is what sets the current frame, when set by a Tcl procedure.
• "frame +<number>" selects the frame <number> frames up the stack (away from the top) from the current frame. "frame -<number>" goes the other way.
• "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.
• "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".
• "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.
• "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.
• "frame patient" returns the token for the patient that owns the function in which the frame is executing.

See Also: addr-parse, switch.

framewin

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

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

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

See Also: display, regwin, srcwin.

freeze

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.

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

• A frozen thread is not dead in the water, as it will still run if nothing else is runnable.
• 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.
• 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.

fullscreen

fullscreen

Examples:

"fullscreen"

Prints the full screen hierarchy from the system object down.

func

func [<func name>]

Examples:

"func"

return the current function.

"func ObjMessage"

set the frame to the first frame for ObjMessage.

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

• 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.
• If no <func name> argument is given then `func' returns the current function.

See Also: backtrace, up, down, finish.

fvardata

fvardata <token> [<address>]

Examples:

"fvardata ATTR_VIS_TEXT_STYLE_ARRAY *ds:si"

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

• 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.
• Returns an empty list if the object has no vardata entry of the given type.
• If no <address> is given, the default is *ds:si.

fwalk

fwalk [<patient>]

Examples:

"fwalk"

list all open files.

"fwalk geos"

list all open files owned by the GEOS patient.

Print the list of files open anywhere in the system.

• 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.
• fwalk differs from sysfiles and geosfiles in that it deals primarily with GEOS data structures.
• The `Other' column shows if there is a VM handle bound to the file.
• 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.

gc

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

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.

gentree

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

Print a generic tree.

• 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.
• The special object flags may be used to specify <object>. For a list of these flags, see pobject.
• The <instance field> argument is the offset to any instance data within the GenInstance which should be printed out.
• 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.

geosfiles

geosfiles

Examples: "geosfiles"

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

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

geos-release

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

geowatch

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)

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

• Two conditional breakpoints are used by this function (see cbrk). The tokens for these breakpoints are returned.
• The special object flags may be used to specify object . For a list of these flags, see pobject.

See Also: objwatch, mwatch, cbrk, pobject.

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.

getcc

getcc <flag>

Examples:

"getcc c"

Get the carry flag.

Get a flag from the target machine.

• 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

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

See Also: setcc, clrcc, compcc.

getenv

getenv <NAME>

Examples:

"getenv PTTY"

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

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

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

See Also: var, string.

get-key-binding

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.

Gets key binding for given key.

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

getvalue

getvalue <expr>

Examples:

"getvalue MSG_META_DETACH "

Returns the integer value of the symbol MSG_META_DETACH.

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.

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.

go

go [<address expressions>]

Examples:

"go"

"go drawLeftLine"

Go until an address is reached.

• 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, detach, quit.

gup

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

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

• 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.
• The special object flags may be used to specify <object>. For a list of these flags, see pobject.
• 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.

handles

handles [<flags>] [<patient>]

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

Print all handles in-use.

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

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

• This only prints those handles in memory while `handles' prints all handles used.
• The handles may be printed with lhwalk and phandle.

See Also: lhwalk, phandle, hgwalk.

handsum

handsum

Examples:

"handsum"

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

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.

• 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

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

hbrk

    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.

Break when a memory location changes.

• The <address> argument is the address to watch for a change.
• The (byte|word) argument indicates whether to watch a byte or a word for a change.
• The (match|mismatch) argument indicates whether to break if the value at the address matches or mismatches the value hbrk is called with.
• 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.
• The command creates two breakpoints. Remove these to get rid of the hardware breakpoint.

See Also: brk, mwatch, showcalls.

heapspace

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.

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.

When using this command, you should run your application on the device it is to run on. One or more system libraries may be XIP (running from ROM) on the device, but run from RAM on your target PC's emulator. Thus, to get a more accurate picture of memory usage, run the application on the planned device.

help

help [<command>]

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.

help-fetch

help-fetch <topic-path>

Examples: "help-fetch top.patient"

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

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.

help-fetch-level

help-fetch-level

Examples:

"help-fetch-level top.prog.obscure"

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

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

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

See Also: help-fetch.

help-help

help-help

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

See Also: help.

help-is-leaf

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

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

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

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

help-minAspect

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

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

help-scan

help-scan <pattern>

Examples:

"help-scan break"

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

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

• The result is a list of topic-paths.

See Also: help-fetch.

help-verbose

var help-verbose [0|1)]

If non-zero, performs verbose prompting.

hex

hex <number>

Examples:

"hex 034"

print hex equivalent of octal 34.

"hex 12"

print hex equivalent of decimal 12.

Print hexadecimal equivalent of a number.

hgwalk

hgwalk

Examples:

"hgwalk"

print statistics on all geodes

Print out all geodes and their memory usage.

history

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.

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.

hwalk

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

Print the status of all blocks on the global heap.

• 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>

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

• This only prints those handles in memory while `handles' prints all handles used.
• The handles may be printed with lhwalk and phandle.

See Also: lhwalk, phandle, handles, hgwalk.

iacp

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

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.

ibrkPageLen

var ibrkPageLen [<number-of-lines>]

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

ignerr

ignerr

Examples:

"ignerr" ignore error and continue

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

Ignore a fatal error and continue.

• The address argument is the address of where to continue execution. If not specified then CS:IP is taken from the frame.
• The stack is patched so that execution can continue in the frame above the fatal error handling routine.

See Also: why, backtrace.

imem

imem [<address>] [<mode>]

Examples:

"imem"

enter imem mode at DS:SI

"imem ds:di"

enter imem mode at DS:SI

Examine memory and modify memory interactively.

• 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.
• 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:

• The default mode is swat's best guess of what type of object is at the address.
• 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.
• 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.

imemPageLen

var imemPageLen [<numlines>]

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

impliedgrab

impliedgrab

Examples:

"gentree [impliedgrab]"

print the generic tree under the mouse

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

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

impliedwin

impliedwin

"wintree [impliedwin]"

print the window tree of the window under the mouse

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

• Note that a window handle is returned.
• This command is normally used with wintree. One may also use the print command if they properly cast the handle.

int

int [<int level> <state>]

Examples:

"int"

report the interrupt statuses

"int 1:1 on"

allow keyboard interrupt while in swat

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

• If no arguments are given, the current state is printed.
• 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

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

intFormat

var intFormat [<format-string>]

Examples:

"var intFormat %d"

Sets the default format for printing unsigned integers to decimal.

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

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

See Also: print, byteAsChar.

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.

io

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.

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

• 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.
• <port> must be a number (in any radix); it cannot be a register or other complex expression.
• 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).

irq

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.

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

• 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.
• 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).
• If given "no" or "yes" as an argument, it causes Swat to ignore or pay attention to the interrupt-pending flag, respectively.
• You can set or clear the flag by giving "set" or "clear" as an argument.

is-obj-in-class

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 .

Returns whether a given object is in the specified class.

• 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.
• The special object flags may be used to specify <object>. For a list of these flags, see pobject.

See Also: psup.

istep

istep [<default command>]

Examples:

"is"

enter instruction step mode

"istep n"

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

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

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

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

keyboard

keyboard [<object>]

Examples:

"keyboard"

print keyboard hierarchy from system object down

"keyboard -i"

print keyboard hierarchy from implied grab down

"keyboard ^l4e10h:20h"

print keyboard hierarchy from ^l4e10h:20h down.

Prints the keyboard hierarchy below an object.

• If no object is specified, the system object is used.

• The special object flags may be used to specify <object>. For a list of these flags, see pobject.
• 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, focus, mouse, model, pobject.

keyboardobj

keyboardobj

Examples:

"keyboardobj"

return object with keyboard grab

"pobj [keyboardobj]"

do a pobject on the object with the keyboard grab (equivalent to "pobj -kg".

Returns the object with the keyboard grab.

See Also: target, focus, mouse, keyboard, mouseobj.

lastCommand

$lastCommand

Examples:

"var repeatCommand $lastCommand"

Set the current command as the command to execute next time.

$lastCommand stores the text of the command currently being executed.

This variable is set by top-level-read. Setting it yourself will have no effect, unless you call set-address or some similar routine that looks at it.

See Also: repeatCommand.

lhwalk

lhwalk [<address>]

Examples:

"lhwalk 1581h"

list the lm heap at 1581h:0

Prints out information about a local memory heap.

• The address argument is the address of the block to print. The default is the block pointed to by DS.

See Also: hwalk, objwalk.

link

link <library> [<patient>]

Examples:

"link motif"

Makes the library "motif" a library of the current patient as far as Swat is concerned.

Allows you to link a patient to act as an imported library of another patient, even though the other patient doesn't actually import the patient. This is useful only for symbol searches.

• sym-default is a much better way to have Swat locate symbols for libraries that are loaded by GeodeUseLibrary() .
• Cycles are not allowed. I.e. don't link your application as a library of the UI, as it won't work--or if it does, it will make Swat die.
• The link persists across detach/attach sequences so long as the <patient> isn't recompiled and downloaded.
• If you don't give <patient>, then the current patient will be the one made to import <library>
• Both <library> and <patient> are patient names , not tokens.

See Also: help-fetch.

listi

listi [<address>] [<length>]

Examples:

"l"

disassemble at the current point of execution

"listi geos::Dispatch"

disassemble at the kernel's dispatch routine

"listi DocClip:IsOut"

disassemble at the local label

"listi cs:ip 20"

disassemble 20 instructions from the current point of execution

Disassemble at a memory address.

• 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 CS:IP is used for the address.
• The <length> argument is the number of instructions to list. It defaults to 16.
• Pressing <Return> after this command continues the list.

See Also: istep, sstep, skip.

load

load <file>

Load a file of Tcl commands.

• If the file cannot be found as given, it is looked for in all the directories mentioned in the "load-path" variable. This variable is initialized from the SWATPATH environment variable, which is in the form <dir1>:<dir2>:...:<dirN>.
• The Swat library directory is appended to this path so you need not include it yourself. The file need not end in ".tcl".
• When searching, file , file .tcl, and file .tlc are searched for. If load finds a file .tlc file, that file will be used only if it is more recent than any corresponding file .tcl or file file.

loadapp

Load an application from swat. Single argument is the file name of the application to launch (application must reside in the appl subdirectory of the GEOS tree).

The application is opened in normal application mode. Note that the application will not be loaded until you continue the machine, as the loading is accomplished by sending a message to the UI.

loadgeode

Load a geode from swat. Mandatory first argument is the name of the file to load (with path from top-level GEOS directory, using / instead of \ as the path separator).

Second and third arguments are the data words to pass to the geode. The second argument is passed to the geode in cx, while the third argument is passed in dx.

Both the second and third arguments are optional and default to 0. They likely are unnecessary.

locals

locals [<func>]

Examples:

"locals"

Print the values of all local variables and arguments for the current frame.

"locals WinOpen"

Print the names of all local variables for the given function. No values are printed.

Allows you to quickly find the values or names of all the local variables of a function or stack frame.

See Also: print, frame, info.

localwin

localwin [<numlines>]

Examples:

"localwin"

Display local variables in a 10-line window

"localwin 15"

Display local variables in a 15-line window

"localwin off"

Turn off the local variable display

Turn on or off the continuous display of local variables.

• Passing an optional numerical argument turns on display of that size. The default size is 10 lines.
• Only one local variable display may be active at a time.

loop

Simple integer loop procedure. Usage is:
loop <loop-variable> <start>,<end> [step <step>] <body>

<start>, <end>, and <step> are integers. <body> is a string for Tcl to evaluate. If no <step> is given, 1 or -1 (depending as <start> is less than or greater than <end>, respectively) is used. <loop-variable> is any legal Tcl variable name.

map

map <var-list> <data-list>+ <body>

Examples:

"map {i j} {a b} {c d} {list $i $j}"

Executes the command "list $i $j" with i and j assigned to successive elements of the lists {a b} and {c d}, respectively, merging the results into the list {{a c} {b d}}

This applies a command string to the successive elements of one or more lists, binding each element in turn to a variable and evaluating the command string. The results of all the evaluations are merged into a result list.

• The number of variables given in <var-list> must match the number of <data-list> arguments you give.
• All the <data-list> arguments must have the same number of elements.
• You do not specify the result of the <body> with the "return" command. Rather, the result of <body> is the result of the last command executed within <body>.

See Also: foreach, mapconcat.

mapconcat

mapconcat <var-list> <data-list>+ <body>

Examples:

"mapconcat {i j} {a b} {c d} {list $i $j}"

Executes the command "list $i $j" with i and j assigned to successive elements of the lists {a b} and {c d}, respectively, merging the results into a string.

map-method

map-method <number> <object>
map-method <number> <class-name> [<object>]

Examples:

"map-method ax ^lbx:si"

Prints the name of the message in ax, from the object at ^lbx:si's perspective.

"map-method 293 GenClass"

Prints the name of message number 293 from GenClass's perspective.

Maps a message number to a human-readable message name, returning that name. This command is useful both for the user and for a Tcl procedure.

• When called from a Tcl procedure, the <class-name> argument should be the fullname of the class symbol (usually obtained with the obj-class function), and <object> should be the address of the object for which the mapping is to take place. If no <object> argument is provided, map-method will be unable to resolve messages defined by one of the object's superclasses that lies beyond a variant superclass.
• If no name can be found, the message number, in decimal, is returned.
• The result is simply returned, not echoed. You will need to echo the result yourself if you call this function from anywhere but the command line.

See Also: obj-class.

mcount

mcount [<args>]

Examples:

"mcount"

start the method count or print the count

"mcount reset"

restart the method count

"mcount stop"

stop the method count

"mcount MyAppRecalcSize"

count messages handled by MyAppRecalcSize

Keep a count of the methods called.

The args argument may be one of the following:

nothing

start the method count or print the current count

'reset'

reset the count to zero

'stop'

stop the method count and remove it's breakpoint

message handler

start the method count for a particular method

See Also: mwatch, showcalls.

memsize

memsize [<memory size>]

Examples:

"memsize"

"memsize 512"

Change the amount of memory that GEOS thinks that it has.

• The <memory size> argument is the size to make the heap. If none is specified then the current memory size is returned.
• Memsize can only be run at startup, before the heap has been initialized. Use this right after an `att -s'.
• Memsize accounts for the size of the stub.

methods

methods <class>
methods <object>
methods <flags>

Examples:

"methods -p"

Print out methods defined for process

"methods ui::GenDocumentClass"

Print out GenDocumentClass methods

"methods 3ffch:072fh"

Print out methods for class at addr

"methods -a"

Print methods of top class of app obj

Prints out the method table for the class specified, or if an object is passed, for the overall class of the object. Useful for getting a list of candidate locations to breakpoint.

model

model [<object>]

Examples:

"model"

print model hierarchy from system object down

"model -i"

print model hierarchy from implied grab down

"model ^l4e10h:20h"

print model hierarchy from ^l4e10h:20h down.

Prints the model hierarchy below an object.

• If no object is specified, the system object is used.
• The special object flags may be used to specify <object>. For a list of these flags, see pobject.
• Remember that the object you start from may have the model exclusive within its part of the hierarchy, but still not have the exclusive because something in a different part of the tree has it.
• 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, focus, mouse, keyboard, pobject.

modelobj

modelobj

Examples:

"modelobj"

print model hierarchy from system object down

"pobj [modelobj]"

Do a pobject on the object with the model grab (the equivalent of a "pobj -m").

Returns the object with the model grab.

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

mouse

mouse [<object>]

Examples:

"mouse"

print mouse hierarchy from system object down

"mouse -i"

print mouse hierarchy from implied grab down

"mouse ^l4e10h:20h"

print mouse hierarchy from ^l4e10h:20h down.

Prints the mouse hierarchy below an object.

• If no object is specified, the system object is used.
• The special object flags may be used to specify <object>. For a list of these flags, see pobject.
• 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, focus, model, keyboard, pobject.

mouseobj

mouseobj

Examples:

"mouseobj"

return object with mouse grab

"pobj [mouseobj]"

do a pobject on the object with the mouse grab (equivalent to "pobj -mg").

Returns the object with the mouse grab.

See Also: target, focus, mouse, keyboard, keyboardobj.

mwatch

mwatch <msg>+
mwatch add <msg>+
mwatch list
mwatch clear

Examples:

"mwatch MSG_VIS_DRAW MSG_METAQUIT"

watch these messages

"mwatch add MSG_META_START_SELECT "

watch this message also

"mwatch"

clear all message watches

Display all deliveries of a particular message.

• The msg argument is which messages to watch. Those specified replace any messages watched before. If none are specified then any messages watched will be cleared.
• You may specify up to eight messages to be watched (fewer if you have other conditional breakpoints active). See cbrk for more information about conditional breakpoints.
• "mwatch clear" will clear all message watches.
• "mwatch add" will add the specified messages to the watch list.
• "mwatch list" will return a list of breakpoints that have been set by previous calls to mwatch.

See Also: objwatch, objbrk, objmessagebrk, procmessagebrk.

next

next

Examples:

"next"

execute the next assembly instruction without entering it

"n"

Execute the patient by a single assembly instruction, skipping over any calls, repeated instructions, or software interrupts.

• next does not protect against recursion, so when the breakpoint for the next instruction is hit, the frame of execution may be one lower.

See Also: step, istep.

noStructEnum

var noStructEnum [(0|1)]

Examples:

"var noStructEnum 1"

Don't put "struct" or "enum" before the data type for variables that are structures or enumerated types.

Structure fields that are structures or enumerated types normally have "struct" or "enum" as part of their type description. This usually just clutters up the display, however, so this variable shuts off this prepending.

The default value of this variable is one.

See Also: print.

null

null <val>

Examples:

"null $sym"

Sees if the symbol token stored in $sym is the empty string or "nil."

Checks to see if a string is either empty or "nil," special values returned by many commands when something isn't found or doesn't apply. Returns non-zero if <val> is either of these special values.

The notion of "nil" as a value comes from lisp.

See Also: index, range.

objbrk

objbrk [<obj address>] [<message>]

Examples:

"objbrk ds:si MSG_VIS_DRAW "

break when a MSG_VIS_DRAW reaches the object

"objbrk -p"

Break when any message is sent to the process object.

Break when a particular message reaches a particular object.

• If you do not give a <message> argument after the <obj> argument, the machine will stop when any message is delivered to the object.
• <obj> is the address of the object to watch.
• The <objbrk> argument to "objbrk del" is the token/number returned when you set the breakpoint.

See Also: objwatch, objmessagebrk, mwatch.

obj-class

objclass <obj-addr>

Examples:

"var cs [obj-class ^lbx:si]"

Store the symbol token for the class of the object ^lbx:si in the variable $cs.

Figures out the class of an object, coping with unrelocated object blocks and the like.

• The value return is a symbol token, as one would pass to the "symbol" command. Using "symbol name" or "symbol fullname" you can obtain the actual class name.
• We decide whether to relocate the class pointer ourselves based on the LMF_RELOCATED bit in the LMBH_flags field of the object 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.

See Also: symbol.

objcount

objcount [-q] [-X] [-Y] [-b #] [-o #] [-p #]

Examples:

"objcount"

count all objects

"objcount -p welcome"

count all objects owned by welcome

"objcount -o *desktop::DiskDrives"

count this one object

"objcount -b 0x3270"

count all objects in this block.

Count up instances of various objects on the heap.

• The first argument specifies the options:

q

quiet operation - no progress output (not applicable with X, Y)

o #

check only object #

b #

check ONLY block #

p #

check only blocks for patient #

c #

check only objects of class #

C #

check only objects of top-level class #

X

show general verbose info

Y

show search verbose info

• Output fields:

direct

number of direct instances of this class

indirect

number if indirect instance of this class (i.e object's superclass is this class)

size

total size of instance data for this class (excludes instance data inherited from superclass)

• Status output:

.

processing heap block

,

processing matching object's top-level class

;

processing matching object's non-top-level class

See Also: hwalk, objwalk, lhwalk.

obj-foreach-class

obj-foreach-class <function> <object> [<args>]

Examples:

"obj-foreach-class foo-callback ^lbx:si"

calls foo-callback with each class in turn to which the object ^lbx:si belongs.

Processes all the classes to which an object belongs, calling a callback procedure for each class symbol in turn.

• <function> is called with the symbol for the current class as its first argument, <object> as its second, and the arguments that follow <object> as its third and subsequent arguments.
• <function> should return an empty string to continue up the class tree.
• obj-foreach-class returns whatever <function> returned, if it halted processing before the root of the class tree was reached. It returns the empty string if <function> never returned a non-empty result.

See Also: obj-class.

objmessagebrk

objmessagebrk [<address>]

Examples:

"objmessagebrk MyObj"

break whenever a message is sent to MyObj

"objmessagebrk"

stop intercepting messages

Break whenever a message is sent to a particular object via ObjMessage.

• The <address> argument is the address to an object to watch for messages being sent to it. If no argument is specified then the watching is stopped.
• This breaks whenever a message is sent (before they get on the message queue. This enables one to track identical messages to an object which can be removed.

See Also: objwatch, mwatch, procmessagebrk, pobject.

objwalk

objwalk [<address>]

Examples: "objwalk"

Prints out information about an object block.

• The <address> argument is the address of the block to print. The default is the block pointed at by DS.

See Also: lhwalk, pobject.

objwatch

objwatch [<address>]

Examples:

"objwatch ds:si"

watch the messages which reach the object at DS:SI

"objwatch MyObject"

watch the messages which reach MyObject

"objwatch"

Watch the messages which reach the process object.

Display message calls that have reached a particular object.

• The <address> argument is the address of the object to watch.
• This returns the token of the breakpoint being used to watch message deliveries to the object. Use the "brk" command to enable, disable, or turn off the watching of the object.

See Also: brk, mwatch, objmessagebrk, procmessagebrk, pobject.

omfq

omfq <message> <object> <args>* 

Examples:

"omfq MSG_META_QUIT *HelloApp"

Sends MSG_META_QUIT to the * HelloApp object.

Forces a message for an object onto its event queue.

• This command calls ObjMessage, passing it
  di=mask MF_FORCE_QUEUE.
• <args> is the set of additional parameters to pass to ObjMessage. It consists of <variable/register> <value> pairs, which 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 message has been queued.
• The registers active before you issued this command are always restored, regardless of whether the call to ObjMessage completes successfully. This is in contrast to the "call" command, which leaves you where the machine stopped with the previous state lost.
• This command will only work when execution halts in the thread that is to receive the message.

See Also: call.

pappcache

pappcache

Examples:

"pappcache"

Print out current state of the app-cache

Prints out the current state of the system application cache, for systems operating in transparent launch mode.

Specifically, this command prints out:

• Applications in the cache (First choice for detaching)
• Top full-screen App (Not detached except by another full screen app)
• Desk accessories (detached only as last resort)
• Application geodes in the process of detaching

patch

patch [<addr>]
patch del <addr>*

Patch assists in creating breakpoints that invisibly make small changes to code. This can help the programmer find several bugs without remaking and redownloading.

• If you give no <addr> when creating a patch, the patch will be placed at the most-recently accessed address, as set by the command that most-recently accessed memory (e.g. bytes, words, listi, imem, etc.)
• When creating a patch, you are prompted for its contents, each line of which comes from the following command set:

Patch Command Set

<flag> is taken from the set TF, IF, DF, OF, SF, ZF, PF, AF, CF and must be in upper-case.

The "scall" command has no effect on the current registers (not even for purposes of return values), while the "mcall" command changes whatever registers the function called modifies. See the "call" documentation for the format of <regs>.

patchin

Patchin undoes the work of patchout.

patchout

This command causes a RET to be placed at the start of a routine.

patient-default

patient-default [<geode-name>]

Examples:

"patient-default hello2"

Makes "hello2" the default patient.

"patient-default"

Prints the names of the current default patient.

Specifies the default patient. The send and run commands will use this as the default patient to operate on if none is passed to them.

pbitmap

pbitmap <address>

Print a bitmap graphically.

• The address argument is the address of the Bitmap or CBitmap structure.
• Color bitmaps are printed with a letter representing the color as well. The letters are index from the string (kbgcrvnAaBGCRVYW).

pcarray

pcarray [-eth] [<address>]

Examples:

"pcarray"

Print the chunk array at *DS:SI (header only)

"pcarray es:di"

Print the chunk array at ES:DI (header only)

"pcarray -e"

Print the chunk array at *DS:SI and print the elements in the array

"pcarray -tMyStruct"

Print the chunk array at *DS:SI and print the elements where the elements are of type MyStruct

"pcarry -tMyStruct -TMyExtraStruct"

Like above, but data after MyStruct is printed as an array of MyExtraStruct structures.

"pcarray -e3"

Print the chunk array at *DS:SI and print the third element

"pcarray -hMyHeader"

Print the chunk array at *DS:SI (header only) where the header is of type MyHeader

Print information about a chunk array.

• The flags argument can be any combination of the flags "e", "t", and "h". The "e" flag prints all elements. If followed by a number (e.g. "-e3"), then only the third element will be printed.
• The `t' flag specifies the elements' type. It should be followed
  immediately by the element type. You can also use "-tgstring" if
  the elements are GString Elements.
• The `h' flag specifies the header type. It should be followed immediately by the element type.
• The `l' flag specifies how many elements to print. It can be used in conjunction with the `e' flag to print a range of element numbers.
• The `H' flag suppresses printing of the header.
• All flags are optional and may be combined.
• The address argument is the address of the chunk array. If not specified then *ds:si is used.

pcbitmap

pcbitmap <address> <width> <height> [<no space flag>]

Examples:

"pcbitmap *ds:si 64 64 t"

print the bitmap without spaces

Print out a one-bit deep packbits-compacted bitmap.

• The <address> argument is the address to the bitmap data.
• The <width> argument is the width of the bitmap in pixels.
• The <height> argument is the height of the bitmap in pixels.
• The <no space flag> argument removes the space normally printed between the pixels. Anything (like "t") will activate the flag.

See Also: pncbitmap.

pcelldata

pcelldata [<addr>]

Examples:

"pcelldata *es:di"

Print cell data for cell at *es:di.

Prints data for a spreadsheet data.

If no address is given, *es:di is used.

See Also: content, pcelldeps.

pcelldeps

pcelldeps <filehan> [<addr>]

Examples:

"pcelldeps 4be0h *es:di"

print dependencies of cell in file 4be0h.

Prints dependencies for a cell in the spreadsheet.

If no address is given, *es:di is used.

See Also: content, pcelldata.

pclass

pclass [<address>]

Examples:

"pclass"

prints the class of *DS:SI

"pclass ^l4ac0h:001eh"

Print the class of the object at the given address.

Print the object's class.

• The <address> argument is the address of the object to find the class of. This defaults to *DS:SI.

pdb

Produces useful information about a DBase block. For now, only information about the map block of the DBase file is produced. First arg H is the SIF_FILE or SIG_VM handle's ID. Second arg B is the VM block handle for which information is desired.

pdgroup

pdgroup [<flags>] [<patient>]

Examples:

"pdgroup"

Prints out all dgroup variables of the current patient

"pdgroup -e *lock*"

Prints out all dgroup variables matching expression "*lock*" of the current patient

"pdgroup term"

Prints out all dgroup variables of the patient "term"

"pdgroup -e *lock* term"

Prints out all dgroup variables matching expression "*lock*" of the patient "term"

Prints out the variables defined in dgroup.

• Flags:

-e <expression>

Only prints out the variables matching <expression>. When -e flag is used, expression argument must be supplied. The expression syntax is the same as the one specified in "string match" command.

See Also: print, pscope.

pdisk

pdisk <disk-handle>

Examples:

"pdisk 00a2h"

Prints information about the disk whose handle is 00a2h.

Prints out information about a registered disk, given its handle.

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: diskwalk, drivewalk.

pdrive

pdrive <drive-handle>
pdrive <drive-name>
pdrive <drive-number>

Examples:

"pdrive si"

Print a description of the drive whose handle is in SI

"pdrive al"

Print a description of the drive whose number is in AL

"pdrive C"

Print a description of drive C

Provides the same information as "drivewalk," but for a single drive, given the offset to its DriveStatusEntry structure in the FSInfoResource.

This is intended for use by implementors of IFS drivers, as no one else is likely to ever see a drive handle.

See Also: drivewalk.

pdw

pdr <register pair>

Examples:

"pdw dxax"

"pdw dx.ax"

"pdw dx:ax"

Prints the dword value of register pair dx:ax

Prints the dword value of a register pair.

The first register is the high register while the second is the low register.

See Also: print.

penum

penum <type> <value>

Examples:

"penum FatalErrors 0"

print the first FatalErrors enumeration

Print an enumeration constant given a numerical value.

• The <type> argument is the type of the enumeration.
• The <value> argument is the value of the enumeration in a numerical format.

See Also: print, precord.

pevent

pevent <handle>

Examples:

"pevent 39a0h"

Print event with handle.

Print an event given its handle.

See Also: elist, eqlist, eqfind, erfind.

pflags

pflags

Prints the current machine flags (carry, zero, etc.).

See Also: setcc, getcc.

pfont

pfont [-c] [<address>]

Examples:

"pfont"

print bitmaps of the characters of the font in BX.

"pfont -c ^h1fd0h"

list the characters in the font at ^h1fd0h.

Print all the bitmaps of the characters in a font.

• The "-c" flag causes pfont to list which characters are in the font and any special status (i.e. NOT BUILT).
• The <address> argument is the address of the font. If none is specified then ^hbx is used.

See Also: fonts, pusage, pfontinfo.

pfontinfo

pfontinfo <font ID>

Examples: "pfontinfo FID_BERKELEY"

Prints font header information for a font. Also lists all sizes built.

• The <font ID> argument must be supplied. If not known, use `fonts -u' to list all the fonts with their IDs.

See Also: fonts, pfont.

pgen

pgen <element> [<object>]

Examples:

"pgen GI_states @65"

print the states of object 65

"pgen GI_visMoniker"

print the moniker of the object at *DS:SI

"pgen GI_states -i"

print the states of the object at the implied grab

Print an element of the generic instance data.

• The <element> argument specifies which element in the object to print
• The <object> argument is the address to the object to print out. It defaults to *DS:SI and is optional. The `-i' flag for an implied grab may be used.

See Also: gentree, gup, pobject, piv, pvis.

pgs

pgs <address>

Examples:

"pgs"

List the graphics string at DS:SI

"pgs ^hdi"

Lift the graphics string whose handle is in DI, starting at the current position.

"pgs -s ^hdi"

List the graphics string whose handle is in DI, starting at the beginning of the graphics string.

"pgs -l3 ^hdi"

List three elements of the graphics string whose handle is in DI, starting at the current position.

List the contents of a graphics string.

• The <address> argument is the address of a graphics string. If none is specified then DS:SI is used as a pointer to a graphics string.
• The passed address may also be the base of a gstate (e.g. "^hdi"). In this case, the gstring that is associated with the gstate will be printed.
• The -s option can be used to specify that the gstring should be listed from the beginning of the string. By default, gstrings will be listed starting at the current position.
• The -g option can be used to specify that the passed address is the address of a GrObj (GStringClass) object-- the gstring for that object will be listed.

See Also: pbitmap.

phandle

phandle <handle ID>

Examples:

"phandle 1a8ch"

print the handle 1a8ch

Print out a handle.

• The <handle ID> argument is just the handle number. Make sure that the proper radix is used.
• The size is in paragraphs.

See Also: hwalk, lhwalk.

pharray

pharray [<flags>] [<vmfile> <dirblk>]

Examples:

"pharray"

Print the huge array at ^vbx:di (header only)

"pharray dx cx"

Print the huge array at ^vdx:cx (header only)

"pharray -e"

Print the huge array at ^vbx:di and print the elements in the array

"pharray -tMyStruct"

Print the huge array at ^vbx:di and print the elements where the elements are of type MyStruct

"pharray -e3"

Print the huge array at ^vbx:di and print the third element

"pharray -h"

Print the header of the HugeArray at ^vbx:di, using the default header type (HugeArrayDirectory).

"pharray -hMyHeader"

Print the huge array at ^vbx:di (header only) where the header is of type MyHeader

"pharray -d"

Print the directory elements of a HugeArray

"pharray -e5 -l8"

Print 8 HugeArray elements starting with number 5

Print information about a huge array.

• The flags argument can be any combination of the flags `e', `t', and `h'. The `e' flag prints all elements. If followed by a number "-e3", then only the third element is printed.

The `t' flag specifies the elements' type. It should be followed immediately by the element type. You can also use "gstring", in which case the elements will be interpreted as GString Elements.

The `h' flag specifies the header type. It should be followed immediately by the element type. If no options are specified, then "-hHugeArrayDirectory" is used. If any other options are specified, then the printing of the header is disabled. So, for example, if you want both the header and the third element, use "-h -e3".

The `d' flag specifies that the HugeArray directory entries should be printed out.

The `l' flag specified how many elements to print.

The `s' flag requests that a summary table be printed.

All flags are optional and may be combined.

• The address arguments are the VM file handle and the VM block handle for the directory block. If nothing is specified, then bx:di is used

pini

pini [<category>]

Examples:

"pini Lights Out"

Print out the contents of the Lights Out category in each .ini file

"pini"

Print out each currently loaded .ini file.

Provides you with the contents of the .ini files being used by the current GEOS session.

<category> may contain spaces and other such fun things. In fact, if you attempt to quote the argument (e.g. "pini {Lights Out}"), this will not find the category.

pinst

pinst [<address>]

Examples:

"pinst"

print the last master level of instance data of the object at *DS:SI

"pinst *MyObject"

print the last master level of instance data of MyObject.

"pinst -i"

print the last master level of the windowed object at the mouse pointer.

Print out all the instance data to the last level of the object.

• The <address> argument is the address of the object to examine. If not specified then pinst will use a default address. If you are debugging a C method, then the oself value will be used. Otherwise, *DS:SI is assumed to be an object.
• This command is useful for classes you've created and you are not interested in the data in the master levels which pobject would display.
• The following special values are accepted for <address>:

-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

• pinst prints out the same information as "pobj l".

See Also: pobject, piv.

piv

piv <master> <iv> [<address>]

Examples:

"piv Vis VCNI_viewHeight"

print Vis.VCNI_viewHeight at *DS:SI

This prints out the value of the instance variable specified.

• The <master> argument expects the name of a master level. The name may be found using pobject to print the levels, and then using the name that appears after "master part:" and before the "_offset".
• The <iv> argument expects the name of the instance variable to print.
• The <address> argument is the address of the object to examine. If not specified then *DS:SI assumed to be an object.
• This command is useful for when you know what instance variable you want to see but don't want to wade through a whole pobject command.

See Also: pobject, pinst.

Prints a keyboard map in assembly-language format.

plines

plines <start> [<obj-address>]

Examples:

"plines 12"

Print lines starting at line 12.

"plines 12 ^l6340h:0020h"

Print lines starting at line 12 of object at given address.

Print information about the lines in a text object.

The printed line-starts are not correct.

See Also: ptext.

plist

Prints out a list of structures stored in an lmem chunk. It takes two arguments, the structure type that makes up the list, and the lmem handle of the chunk. e.g. plist FontsInUseEntry ds:di

pncbitmap

pncbitmap <address> <width> <height> [<no space flag>]

Examples:

"pncbitmap *ds:si 64 64 t"

print the bitmap without spaces

Print out a one-bitdeep noncompacted bitmap.

• The <address> argument is the address to the bitmap data.
• The <width> argument is the width of the bitmap in pixels.
• The <height> argument is the height of the bitmap in pixels.
• The <no space flag> argument removes the space normally printed between the pixels. Anything (like `t') will activate the flag.

See Also: pcbitmap.

pnormal

pnormal [-v]

Examples:

"pnormal -v"

Print out verbose information about the current normal transfer item.

Prints out information about the current "normal" transfer item on the clipboard.

If you give the "-v" flag, this will print out the contents of the different transfer formats, rather than just an indication of their types.

See Also: pquick, print-clipboard-item.

pobjarray

pobjarray [<address>]

Examples:

"pobjarray"

Print the array of ODs at *ds:si.

Print out an array of objects.

See Also: pbody.

pobject

pobject [<address>] [<detail>]

Examples:

"pobj"

print the object at *ds:si from Gen down if Gen is one of its master levels; else, print all levels

"pobj *MyGenObject"

print MyGenObject from Gen down

"pobj Gen"

print the Gen level for the object at *ds:si

"pobj last"

print the last master level for the object at *ds:si

"pobj *MyObject"

all print all levels of MyObject

"pobj -i sketch"

print the master level headings of the windowed object at the mouse pointer

"pobj *MyObject FI_foo"

print the FI_foo instance variable for MyObject

"pobj HINT_FOO"

print the HINT_FOO variable data entry for the object at *ds:si

"pobj v"

print the variable data for the object at *ds:si

Print all or part of an object's instance and variable data.

• The <address> argument is the address of the object to examine. If not specified then oself is used, unless the current function is written in assembly, in which case *DS:SI .
• The following flag values are accepted in lieu of an address:

-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

• The detail argument specifies what information should be printed out about the object. If none is specified, all levels of the object from the Gen level down will be printed if Gen is one of the object's master levels; else, the whole object will be printed.
• The following values are accepted for detail :

all (or a )

all master levels

last (or l )

last master level only

sketch (or s )

master level headings only

vardata (or v )

vardata only

a master level name

an instance variable name

a variable data entry name

See Also: pinst, piv, pvardata.

pobjmon

pobjmon [<address>] [<text only>]

Examples:

"pobjmon"

print the VisMoniker from the gentree object at *DS:SI

• The <address> argument is the address of an object with a VisMoniker. If none is specified then *DS:SI is used.
• The <text only> argument returns a shortened description of the structure. To set it use something other than `0' for the second argument.
• The special object flags may be used to specify <object>. For a list of these flags, see pobject.

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

pod

pod <address>

Examples:

"pod ds:si"

Print in output descriptor format (^l<handle>:<chunk>) the address passed.

The address argument is the address of an object.

ppath

ppath (current|docClip|winClip) [<gstate>]

Examples:

"ppath"

print the current path of the GState in ^hdi

"ppath docClip ^hgstate"

print the document clip path of the GState with handle gstate .

"ppath winClip ds"

print the window clip path of the GState in the DS register.

Print the structure of a path.

Unique abbreviations for the path to be printed are allowed.

pquick

pquick [-v]

Examples:

"pquick -v"

Print out verbose information about the current quick transfer item.

Prints out information about the current "quick" transfer item on the clipboard.

If you give the "-v" flag, this will print out the contents of the different transfer formats, rather than just an indication of their types.

See Also: pnormal, print-clipboard-item.

precord

precord <type> <value> [<silent>]

Examples:

"precord GSControl c0h"

print the GSControl record with the top two bits set

Print a record using a certain value.

• The <type> argument is the type of the record.
• The <value> argument is the value of the record.
• The <silent> argument will suppress the text indicating the record type and value. This is done by passing a non zero value like `1'. This is useful when precord is used by other functions.

See Also: print, penum.

preg

preg [-g] <addr>

Examples:

"preg *es:W_appReg"

Prints the application-defined clipping region for the window pointed to by es.

"preg -g ds:si"

Prints a "graphical" representation of the region beginning at ds:si

Decodes a graphics GEOS region and prints it out, either numerically, or as a series of x's and spaces.

• This command can deal with parameterized regions. When printing a parameterized region with the -g flag, the region is printed as if it were unparameterized, with the offsets from the various PARAM constants used as the coordinates.
• If no address is given, this will use the last-accessed address (as the "bytes" and "words" commands do). It sets the last-accessed address, for other commands to use, to the first byte after the region definition.

print

print <expression>

Examples:

"print 56h"

print the constant 56h in various formats

"print ax - 10"

print ax less 10 decimal

"print ^l31a0h:001eh"

print the absolute address of the pointer

Print the value of an expression.

• The <expression> argument is usually an address that has a type or that is given a type by casting and may span multiple arguments. The contents of memory of the given type at that address is what's printed. If the expression has no type, its offset part is printed in both hex and decimal. This is used for printing registers, for example.
• The first argument may contain the following flags (which start with `-'):

x

integers (bytes, words, dwords if dwordIsPtr false) printed in hex

d

integers printed in decimal

o

integers printed in octal c bytes printed as characters (byte arrays printed as strings, byte variables/fields printed as character followed by integer equivalent)

C

bytes treated as integers

a

align structure fields

A

Don't align structure fields

p

dwords are far pointers

P

dwords aren't far pointers

r

parse regions

R

don't try to parse regions

• These flags operate on the following Tcl variables:

intFormat

A printf format string for integers.

bytesAsChar

Treat bytes as characters if non-zero.

alignFields

Align structure fields if non-zero.

dwordIsPtr

DWords are far pointers if non-zero.

noStructEnum

If non-zero, doesn't print the "struct", "enum" or "record" before the name of a structured/enumerated type -- just gives the type name.

printRegions

If non-zero, prints what a Region points to (bounds and so on).

condenseSpecial

If non-zero, condense special structures (Rectangles, OutputDescriptors, ObjectDescriptors, TMatrixes and all fixed-point numbers) to one line.

• This does not print enumerations. Use penum for that.

See Also: precord, penum, _print.

print-cell

print-cell [row column <cfp ds:si>]

Examples:

"print-cell 1 1"

print the cell <1,1>

"print-cell 1 2 *ds:si"

print the cell <1,2> given *DS:SI

Print information about a cell

See Also: print-row, print-row-block, print-cell-params, print-column-element.

print-cell-params

print-cell-params [<address>]

Examples:

"print-cell-params"

print the CellFunctionParameters at ds:si.

"print-cell-params ds:bx"

print the CellFunctionParameters at ds:bx.

Print a CellFunctionParameters block.

See Also: print-row, print-column-element, print-row-block, print-cell.

print-clipboard-item

print-clipboard-item [-v] <vmfile> <vmblock>
print-clipboard-item [-v] <memhandle>
print-clipboard-item [-v] <addr> 

Examples:

"print-clipboard-item bx"

Print out info about the transfer item whose memory handle is in the BX register.

Prints out information about a transfer item.

• If you give the "-v" flag, this will print out the contents of the different transfer formats, rather than just an indication of their types.
• The -v flag will not work unless the transfer item is in a VM file.

See Also: pnormal, pquick.

print-column-element

print-column-element [<address>]

Examples:

"print-column-element"

Print the ColumnArrayElement at ds:si.

"print-column-element ds:bx" print the ColumnArrayElement at ds:bx

Print a single ColumnArrayElement at a given address.

print-db-group

print-db-group file group

Examples:

"print-db-group ax bx"

print the group at bx/ax.

Print information about a dbase group block.

See Also: print-db-item.

print-db-item

print-db-item file group item

Examples:

"print-db-item bx ax di"

print the item at bx/ax/di

Print information about a single dbase item

See Also: print-db-group.

print-eval-dep-list

print-eval-dep-list [<addr>] 

Examples:

"print-eval-dep-list es:0"

Print dependency list at ES:0.

Prints a dependency list used for evaluation.

See Also: content, pcelldeps.

printNamesInObjTrees

var printNamesInObjTrees (0|1)

Examples:

"var printNamesInObjTrees 1"

Sets "gentree," "vistree," etc. commands to print object names (where available).

Determines whether object names are printed (where available) rather than class names when using the following commands: vistree, gentree, focus, target, model, mouse, keyboard.

The default value for this variable is zero.

See Also: gentree, vistree, focus, target, model, mouse, keyboard.

print-obj-and-method

print-obj-and-method <handle> <chunk> <message> [<cx> [<dx> 
                                                   [<bp> [<class>]]]] 

Examples:

"print-obj-and-method [read-reg bx] [read-reg si]"

Prints a description of the object ^lbx:si with the value stored and a hex representation.

"print-obj-and-method $h $c $m [read-reg cx] [read-reg dx] [read-reg bp]"

Prints a description of the object ^l$h:$c and the name of the message whose number is in $c. This is followed by the three words of data in cx, dx, and bp.

Prints a nicely formatted representation of an object, with option message, register data, label, hex address, & carriage return. The class indication may also be overriden.

• You may specify anywhere from 0 to 5 arguments after the message number. These are interpreted as the value of the message, the registers CX, DX and BP, and the symbol token of the class to print, respectively.
• All arguments must be integers, as this is expected to be called by another procedure, not by the user, so the extra time required to call getvalue would normally be wasted. (The user should call pobj , gup , or other such functions for this sort of print out.)

See Also: mwatch, map-method, objwatch.

printRegions

var printRegions [(0|1)]

Examples:

"var printRegions 1"

If a structure contains a pointer to a region, "print" will attempt to determine its bounding box.

Controls whether "print" parses regions to find their bounding rectangle.

The default value for this variable is one.

See Also: print, condenseSpecial.

print-row

print-row [<address *DS:SI>]

Examples:

"print-row"

print the row at *DS:SI

"print-row ds:si"

print the row at DS:SI

Print a single row in the cell file given a pointer to the row.

See Also: print-column-element, print-cell-params, print-row-block, print-cell.

print-row-block

print-row-block [<address ds>]

Examples:

"print-row-block"

print the row-block at DS:0

"print-row-block es"

print the row-block at ES:0

Print a row-block.

See Also: print-row, print-cell-params, print-column-element, print-cell.

printStop

This variable controls how the current machine state is printed each time the machine comes to a complete stop. Possible values:

asm

Print the current assembly-language instruction, complete with the values for the instruction operands.

src

Print the current source line, if it's available. If the source line is not available, the current assembly-language instruction is displayed as above.

why

Print only the reason for the stopping, not the current machine state. "asm" and "src" modes also print this.

nil

Don't print anything.

procmessagebrk

procmessagebrk [<handle>]

Examples:

"procmessagebrk MyObj"

break whenever a message is sent to MyObj

"procmessagebrk"

stop intercepting messages

Break whenever a message is sent to a particular process via ObjMessage.

• The <handle> argument is the handle to a process to watch for messages being sent to it. If no argument is specified then the watching is stopped. The process' handle may be found by typing "ps -p". The process's handle is the number before the process's name.
• This command breaks whenever a message is sent (before they get on the message queue. This enables one to track identical messages to a process which can be removed.

See Also: objwatch, mwatch, objmessagebrk, pobject.

ps

ps [<flags>]

Examples:

"ps -t"

list all threads in GEOS.

Print out GEOS' system status.

The flags argument may be one of the following:

-t

Prints out info on all threads. May be followed by a list of patients whose threads are to be displayed.

-p

Prints out info on all patients. May be followed by a list of patients to be displayed.

-h

Prints out info on all handles. May be followed by a list of patients whose handles are to be displayed.

The default is `-p'.

See Also: switch, sym-default.

pscope

pscope [<scope-name> [<sym-class>]]

Examples:

"pscope WinOpen"

Prints out all the local labels, variables, and arguments within the WinOpen() procedure

This prints out all the symbols contained in a particular scope.

• This can be useful when you want to know just the fields in a structure, and not the fields within those fields, or if you know the segment in which a variable lies, but not its name. Admittedly, this could be overkill.
• sym-class can be a list of symbol classes to restrict the output. For example, "pscope Filemisc proc" will print out all the procedures within the Filemisc resource.

See Also: whatis, locals.

psize

psize <structure>

Examples: "psize FontsInUseEntry"

Print the size of the passed structure.

pssheet

pssheet [-isSfrcvd] <address>

Examples:

"pssheet -s ^l3ce0h:001eh"

print style attributes.

"pssheet -f -i 94e5h:0057h"

print file info from instance data.

Prints out information about a spreadsheet object.

• If you are in the middle of debugging a spreadsheet routine and have a pointer to the Spreadsheet instance, the "-i" flag can be used to specify the object using that pointer.
• If you simply have the OD of the spreadsheet object, use that.
• Alternatively, you can do:

 pssheet <flags> [targetobj]

See Also: content, targetobj.

psup

psup [<object>]

Examples:

"psup"

print superclasses of object at *ds:si.

"psup -i"

print superclasses of object under mouse.

"psup ^l4e10h:20h"

print superclasses of object at ^l4e10h:20h.

Prints superclasses of an object.

If no object is specified, *ds:si is used.

See Also: is-obj-in-class.

ptext

ptext [<options>] <addr>

Examples:

"ptext"

Prints the text in the object for the method being executed in the current stack frame.

Prints out the text and related structures for a text object

The flag may be one or more of the following:

- c

Print out the char attr structures.

- e

Print out elements in addition to runs.

- f < field >

Print out given field of each element (default is Meta part).

- g

Print out graphics structures.

- l

Print out line and field structures.

- p

Print out para attr structures.

- r

Print out region attr structures.

- s

Print out style structures.

- t

Print out type structures.

- E

Limit printout to just the elements of whatever arrays are requeste. Do not attempt to print out associated text.

- N

Print out associated names.

- R

Print out full region descriptions.

pthread

pthread <id>

Examples:

"pthread 16c0h"

Prints information about the thread whose handle is 16c0h.

Provides various useful pieces of information about a particular thread including its current priority and its current registers.

<id> is the thread's handle ID, as obtained with the "ps -t" or "threadstat" command.

See Also: threadstat.

ptimer

ptimer <handle>

Examples:

"ptimer bx"

Print out information about the timer whose handle is in the BX register.

Prints out information about a timer registered with the system: when it will fire, what it will do when it fires, etc.

<handle> may be a variable, register, or constant.

See Also: twalk, phandle.

ptrans

ptrans [<flags>] [<address>]

Examples:

"ptrans"

print the normal transform for the object at *ds:si.

"ptrans -s"

print the sprite transform for the GrObj object at *ds:si.

"ptrans ^lbx:cx"

print the normal transform for the object whose OD is ^lbx:cx.

Prints the ObjectTransform data structure as specified.

• The -s flag can be used to print the "sprite" transform (the "sprite" is the shape's outline which is drawn to give feedback to the user when said user is moving/rotating/etc. the GrObj).
• <address> defaults to *ds:si

See Also: pobject.

ptreg

ptreg <start> [<obj-addr>]

Examples:

"ptreg 12"

Print lines for region 12

"ptreg 12 ^lcx:dx"

Print lines for region 12 of object ^lcx:dx

Print information about the lines in a region.

See Also: ptext.

pusage

pusage [<address>]

Examples:

"pusage"

print the usage of characters in the font

List the characters in a font and when they were last used.

• The <address> argument is the address of a font. If none is given then ^hbx is used.

See Also: fonts, pfont, pfontinfo, plist.

pvardata

pvardata [<entry>]

Examples:

"pvardata ds:si"

Prints vardata of object at *ds:si

"pvardata -i"

Prints vardata of object with implied grab.

• The address argument is the address of an object with variable data. The default is *ds:si.

pvardentry

pvardentry <address> <object>

Examples:

"pvardentry ds:bx *ds:si"

• The address argument is the address of a variable data entry in an object's variable data storage area. The default is ds:bx.
• The <object> argument is required to determine the name of the tag for the entry, as well as the type of data stored with it.

pvis

pvis <element> [<object>]

Examples:

"pvis VI_bounds @65"

print the bounds of object 65

"pvis VI_optFlags"

print the flags of the object at *DS:SI

"pvis VI_attrs -i"

print the attributes of the object at the implied grab

Print an element of the visual instance data.

• The <element> argument specifies which element in the object to print
• The <object> argument is the address to the object to print out. It defaults to *DS:SI and is optional. The `-i' flag for an implied grab may be used.

See Also: vistree, vup, pobject, piv, pgen.

pvismon

pvismon [<address>] [<text only>]

Examples:

"pvismon"

print the moniker at *DS:SI

"pvismon -i 1"

print a short description of the implied grab object.

Print a visual moniker structure at an absolute address.

• The <address> argument is the address to an object in the visual tree. This defaults to *DS:SI. The `-i' flag for an implied grab may be used.
• The <text only> argument returns a shortened description of the structure. Pass a non-zero value to turn on this flag.
• The special object flags may be used to specify <object>. For a list of these flags, see pobject.

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

pvmb

Prints out the VMBlockHandle for a VM block given the file handle H and the VM block handle B .

pvmt

pvmt [-p] [-a] [-s] [-c] (<handle> | <segment>)

Examples:

"pvmt bx"

Print out all used blocks for the open VM file whose file handle is in BX.

"pvmt -as ds"

Print out all blocks for the open VM file the segment of whose header block is in DS.

Prints out a map of the VM block handles for a VM file.

• The -p flag will only print out blocks that have the Preserve flag set. Useful for examining object blocks in GeoCalc files, for example.
• The -a flag causes pvmt to print out all block handles, not just those that have been allocated. The other two types of block handles are "assigned" (meaning they're available for use, but currently are tracking unused space in the file) and "unassigned" (they're available for use).
• The -s indicates the final argument is a segment, not a file handle. This is used only if you're inside the VM subsystem of the kernel.
• The -c flag requests a count of the different types of blocks at the end of the printout.
• The blocks are printed in a table with the following columns:

han

VM block handle (in hex)

flags D if the block is dirty,

C if the block is clean,
- if the block is non-resident,
L if the block is LMem,
B if the block has a backup,
P if the preserve handle bit is set for the block,
! if the block is locked

memhan

Associated memory handle. Followed by "(d)" if the memory for the block was discarded but the handle retained. Followed by (s) if the memory has been swapped out.

block type

The type of block:

VMBT_USED a normal in-use block,

VMBT_DUP an in-use block that has been backed up or allocated since the last call to VMSave()

VMBT_BACKUP a place-holder to keep track of the previous version of a VMBT_DUP block. The uid is the VM block handle to which the file space used to belong.

VMBT_ZOMBIE a block that has been freed since the last VMSave() . The handle is preserved in case of a VMRevert() (a VMBT_BACKUP block retains the file space).

uid

The "used ID" bound to the block.

size

Number of bytes allocated for the block in the file.

pos

The position of those bytes in the file.

See Also: pgs.

pvsize

pvsize [<object>]

Examples:

"pvsize"

print the dimensions of the visual object at *ds:si.

Print out the dimensions of a visual object.

• The object argument is the address to the object to print out. It defaults to *ds:si and is optional. The `-i' flag for an implied grab may be used.
• The special object flags may be used to specify <object>. For a list of these flags, see pobject.

pwd

pwd

Examples: "pwd"

Prints the current working directory for the current thread.

See Also: dirs, stdpaths.

quit

quit [<options>]

Examples:

"quit cont"

continue GEOS and quit swat

"quit det"

detach from the PC and quit swat.

Stop the debugger and exit.

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

See Also: detach.

read-char

read-char [<echo>]

Examples:

"read-char 0"

Read a single character from the user and don't echo it.

Reads a character from the user.

If <echo> is non-zero or absent, the character typed will be echoed.

See Also: read-line.

read-line

read-line [<isTcl> [<initial input> [<special chars>]]]

Examples:

"read-line"

reads a single line of text.

"read-line 1"

reads a Tcl command.

"read-line 1 {go}"

reads a Tcl command that starts with "go "

"read-line 1 {} {\e\4}"

reads a Tcl command, considering escape and control-d cause for immediate return, regardless of whether braces and brackets are balanced

Reads a single line of input from the user. If optional argument is non-zero, the line is interpreted as a Tcl command and will not be returned until all braces/brackets are balanced. The final newline is stripped. Optional second argument is input to be placed in the buffer first. This input must also be on-screen following the prompt, else it will be lost.

• If <isTcl> is non-zero, the input may span multiple lines, as read-line will not return until all braces and brackets are properly balanced, according to the rules of Tcl. This behavior may be overridden by the <special chars> argument.
• If <initial input> is given and non-empty, it is taken to be the initial contents of the input line and may be edited by the user just as if s/he had typed it in. The string is not automatically displayed; that is up to the caller.
• <special chars> is an optional string of characters that will cause this routine to return immediately. The character that caused the immediate return is left as the last character of the string returned. You may use standard backslash escapes to specify the characters. This will return even if the user is entering a multi-line Tcl command whose braces and brackets are not yet balanced.
• The user's input is returned as a single string with the final newline stripped off.

read-reg

read-reg <register>

Examples:

"read-reg ax"

return the value of AX

"read-reg CC"

return the value of the conditional flags

Return the value of a register in decimal.

• The <register> argument is the two letter name of a register in either upper or lower case.

See Also: frame, assign, setcc, clrcc.

regs

regs

Print the current registers, flags, and instruction.

See Also: assign, setcc, clrcc, read-reg.

regwin

regwin [off]

Examples: "regwin"
"regwin off"

Turn the continuous display of registers on or off.

• If you give the optional argument "off", you will turn off any active register display.
• If you give no argument, the display will be turned on.
• Only one register display may be active at a time.

See Also: display.

repeatCommand

var repeatCommand <string>

Examples:

"var repeatCommand [list foo nil]"

Execute the command "foo nil" if the user just hits <Enter> at the next command prompt.

This variable holds the command Swat should execute if the user enters an empty command. It is used by all the memory-referencing commands to display the next chunk of memory, and can be used for other purposes as well.

• repeatCommand is emptied just before top-level-read returns the command the interpreter should execute and must be reset by the repeated command if it wishes to continue to be executed when the user just hits <Enter>.
• The text of the current command is stored in lastCommand , should you wish to use it when setting up repeatCommand .

See Also: target, focus, mouse, keyboard.

require

require <name> [<file>]

Examples:

"require fmtval print"

Ensure the procedure "fmtval" is defined, loading the file "print.tcl" if it is not.

This ensures that a particular function, not normally invoked by the user but present in some file in the system library, is actually loaded.

If no <file> is given, a file with the same name (possibly suffixed ".tcl") as the function is assumed.

See Also: autoload.

resize

resize <window> <numLines>

Examples:

"resize varwin 5"

Resizes the varwin to 5 lines.

"resize va 5"

Resizes the varwin to 5 lines.

Resizes the source window or a varwin or localwin.

• The window argument is the name of the window to be resized, or a unique abbreviation of that name. Possible names are: "varwin", "localwin", "view", "doc", and "srcwin"; the last three all refer to the source window.
• The numLines argument is the desired window size.
• This command will not resize a flagwin, regwin, or framewin, as the optimal size of those windows does not vary.

restore-state

restore-state

Examples:

"restore-state"

Set all registers for the current thread to the values saved by the most recent save-state.

Pops all the registers for a thread from the internal state stack.

• This is the companion to the "save-state" command.
• All the thread's registers are affected by this command.

See Also: save-state.

ret

ret [<function name>]

Examples: "ret"
"ret ObjMessage"

Return from a function and stop.

• The <function name> argument is the name of a function in the patient's stack after which swat should stop. If none is specified then Swat returns from the current function.
• The function returned from is the first frame from the top of the stack which calls the function (like the "finish" command).
• This command does not force a return. The machine continues until it reaches the frame above the function.

See Also: finish, backtrace.

return-to-top-level

return-to-top-level

Examples:

"return-to-top-level"

Returns to the top-level interpreter.

Forces execution to return to the top-level interpreter loop, unwinding intermediate calls (protected commands still have their protected clauses executed, but nothing else is).

See Also: top-level, protect.

rs

rs

Examples:

"rs"

restart GEOS without attaching

Restart GEOS without attaching.

See Also: att, attach.

run

run [<patient-name>]

Examples:

"run uki"

Run the application with patient name "uki".

"run -e uki"

run EC Uki

"run -n uki"

run non-EC Uki

"run -p games\ukiec.geo "

run games\ukiec.geo

"run"

run the default patient, as specified by the patient-default command.

"Runs" an application by loading it via a call to UserLoadApplication() and stopping when the app reaches the GenProcess handler for MSG_META_ATTACH . Return patient created, if any (In the examples shown, this would be "uki").

• May be used even if stopped inside the loader, in which case GEOS will be allowed to continue starting up, and the specified app run after GEOS is Idle.
• If the machine stops for any other reason other than the call's completion, you are left wherever the machine stopped.

See Also: patient-default, send, spawn, switch.

rwatch

rwatch [(on|off)]

Examples:

"rwatch on"

Watch text-recalculation as it happens

"rwatch off"

Turn output off

"rwatch"

See what the status is

Displays information about text recalculation. Specifically designed for tracking bugs in the rippling code.

See Also: ptext.

save

save (<#lines>|<filename>)

Examples:

"save 500"

Save the last 500 lines that scroll off the screen.

"save /dumps/puffball"

Save the contents of the entire scroll buffer to the file "puffball".

Controls the scrollback buffer Swat maintains for its main command window.

• If the argument is numeric, it sets the number of lines to save (the default is 1,000).
• If the argument is anything else, it's taken to be the name of a file in which the current buffer contents (including the command window) should be saved. If the <filename> is relative, it is taken relative to the directory in which the executable for the patient to which the current stack frame's function belongs is located. If the file already exists, it is overwritten.

save-state

save-state

Examples:

"save-state"

Push the current register state onto the thread's state stack.

Records the state of the current thread (all its registers) for later restoration by "restore-state".

• Swat maintains an internal state stack for each thread it knows, so calling this has no effect on the target PC.
• This won't save any memory contents, just the state of the thread's registers.

See Also: restore-state, discard-state.

sbwalk

sbwalk [<patient>]

Examples:

"sbwalk"

list the saved blocks of the current patient.

"sbwalk geos"

list the saved blocks of the GEOS patient.

List all the saved blocks in a patient.

• The <patient> argument is any GEOS patient. If none is specified then the current patient is used.

scope

scope [<scope-name>]

Examples:

"scope"

Returns the name of the current auxiliary scope.

This changes the auxiliary scope in which Swat looks first when trying to resolve a symbol name in an address expression.

• This command isn't usually typed by users, but it is the reason you can reference local labels after you've listed a function unrelated to the current one.
• You most likely want to use the set-address Tcl procedure, rather than this command.
• If <scope-name> is "..", the auxiliary scope will change to be the lexical parent of the current scope.

See Also: set-address, addr-parse, whatis.

screenwin

screenwin

Print the address of the current top-most screen window.

send

send [-enpr] <geode-name>

Examples:

"send icon"

send EC Icon Editor if running in EC mode; send non-EC Icon Editor if running in non-EC mode.

"send -r icon"

send appropriate icon editor, then run it. (See documentation for "run" above.)

"send -e icon"

send EC Icon editor.

"send -n icon"

send non-EC Icon Editor

"send -p c:/pcgeos/appl/icon/icon.geo"

send c:/pcgeos/appl/icon/icon.geo

"send"

send the default patient (as set by the patient-default command).

Send a geode from the host to target machine.

send-file

send-file <file> <targfilename>

Examples:

"send-file /pcgeos/appl/sdk/mess1/mess1.geo WORLD/soundapp.geo"

Send the mess1.geo file on the host machine to the WORLD directory of the host machine, where it will be called soundapp.geo .

Sends a file from the host machine to the target.

set-address

Set the last-accessed address recorded for memory-access commands. Single argument is an address expression to be used by the next memory-access command (except via <return>).

setcc

setcc <flag> [<value>]

Examples:

"setcc c"

set the carry flag

"setcc z 0"

clear the zero flag

Set a flag in the computer.

• The first argument is the first letter of the flag to set. 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

• The second argument is the value to assign the flag. It defaults to one but may be zero to clear the flag.

See Also: clrcc, compcc.

set-masks

set-masks <mask1> <mask2>

Examples:

"set-masks 0xff 0xff"

Allow no hardware interrupts to be handled while the machine is stopped.

Sets the interrupt masks used while the Swat stub is active. Users should use the "int" command.

• <mask1> is the mask for the first interrupt controller, with a 1 bit indicating the interrupt should be held until the stub returns the machine to GEOS. <mask2> is the mask for the second interrupt controller.
• These masks are active only while the machine is executing in the stub, which usually means only while the machine is stopped.

See Also: int.

set-repeat

Sets the command to be repeated using a template string and the lastCommand variable. The variables $0...$n substitute the fields 0...n from the lastCommand variable. The final result is placed in repeatCommand which will be executed should the user type Enter.

set-startup-ec

set-startup-ec [<args>]

Examples:

"set-startup-ec +vm"

turn on VM error checking when starting up

"set-startup-ec none"

turn off all ec code when starting up

Executes the "ec" command upon startup, to allow one to override the default error checking flags.

See Also: ec.

sftwalk

sftwalk

Examples: "sftwalk"

Print the system file table out by blocks.

• This is different than sysfiles in that it shows less details of the files and instead shows where the SFT blocks are and what files are in them.

See Also: sysfiles, geosfiles, fwalk.

showcalls

showcalls [<flags>] [<args>]

Examples:

"showcalls -o"

show all calls using ObjMessage and ObjCall*

"showcalls -ml"

show all calls changing global and local memory

"showcalls"

stop showing any calls

Display calls to various parts of GEOS.

• The <flags> argument determines the types of calls displayed. Multiple flags must all be specified in the first argument such as "showcalls -vl". If no flags are passed then showcalls stops watching. The flags may be any of the following:

-p

Modify all other flags to work for the current patient only

-a

Show calls associated with attaching, detaching, state-saving, restoring from state

-b

Monitors builds of Vis objects

-d

Show dispatching of threads

-e

Show FOCUS, TARGET, MODAL . exclusive grabs & releases

-f

Show certain file operations

-g

Show geometry manager resizing things (all sizes in hex)

-h

Show all hierarchical exclusive grabs and releases (associated with focus, target, and model).

-i

Show call far calls made to movable routines.

-l

Show local memory create, destroy, relocate

-m

Show global memory alloc, free, realloc

-o

Show ObjMessage() and ObjCall ... ()

-s

Monitors shutdown: MSG_DETACH , DETACH_COMPLETE , ACK , DETACH_ABORT

-t

Show clipboard activity

-v

Show video driver calls

-w

Show WinOpen() , WinClose() , WinMoveResize() , WinChangePriority() .

-F

Show file-change notifications produced by the system.

-G

Show GrCreateState() and GrDestroyGState() .

-H

Show heap space allocation (using .gp heapspace values, not actual allocation values)

-I

Show invalidation mechanism at work.

-L

Show library loading calls

-N

Show navigation calls (between fields, and between windows)

-S

Show stack borrowing activity.

-T

Show text-object related information.

-V

Show loading and unloading of resources to and from statefiles during shutdown.

• The<args> argument is used to pass values for some of options.

See Also: mwatch, objwatch.

showMethodNames

var showMethodNames

If this variable is non-zero, Swat prints out the names of the method in the AX register when unassembling a message call.

skip

skip [<number of instructions>]

Examples:

"skip"

skip the current instruction

"skip 6"

skip the next six instructions

Skip one or more instructions.

• The <number of instructions> argument defaults to one if not specified.

See Also: istep, sstep, patch.

sleep

sleep <seconds>

Examples:

"sleep 5"

Pauses Swat for 5 seconds.

This pauses Tcl execution for the given number of seconds, or until the user types Ctrl-C.

• Messages from the PC continue to be processed, so a FULLSTOP event will be dispatched if the PC stops, but this command won't return until the given length of time has elapsed.
• <seconds> is a real number, so "1.5" is a valid argument.
• Returns non-zero if it slept for the entire time, or 0 if the sleep was interrupted by the user.

slist

slist [<args>]

Examples:

"slist"

list the current point of execution

"slist foo.asm::15"

list foo.asm at line 15

"slist foo.asm::15,45"

list foo.asm from lines 15 to 45

List source file lines in swat.

• The args argument can be any of the following:

<address>

Lists the 10 lines around the given address

<line>

Lists the given line in the current file

<file>::<line>

Lists the line in the given file

<line1>,<line2>

Lists the lines between line1 and line2, inclusive, in the current file

<file>::<line1>,<line2>

Lists the range from <file>

• The default is to list the source lines around CS:IP.

See Also: listi, istep, regs.

smatch

Look for symbols of a given class by pattern. First argument <pattern> is the pattern for which to search (it's a standard Swat pattern using shell wildcard characters). Optional second argument <class> is the class of symbol for which to search and is given directly to the "symbol match" command. Defaults to "any".

sort

sort [-r] [-n] [-u] <list>

Examples:

"sort -n $ids"

Sorts the list in $ids into ascending numeric order.

This sorts a list into ascending or descending order, lexicographically or numerically.

• If "-r" is given, the sort will be in descending order.
• If "-u" is given, duplicate elements will be eliminated.
• If "-n" is given, the elements are taken to be numbers (with the usual radix specifiers possible) and are sorted accordingly.
• The sorted list is returned.

See Also: map, foreach, mapconcat.

spawn

spawn <processName> [<addr>]

Set a temporary breakpoint in a not-yet-existent process/thread, waiting for a new one to be created. First argument is the permanent name of the process to watch for. Second argument is an address expression specifying where to place the breakpoint. If no second argument is present, the machine will be stopped and Swat will return to the command level when the new thread is spawned by GEOS.

• This can also be used to catch the spawning of a new thread.
• If the machine stops before the breakpoint can be set, you'll have to do this again.

srcwin

srcwin <numLines>

Examples:

"srcwin 6"

Show 6 lines of source context around CS:IP

"srcwin 0"

Show no source lines, i.e. turn the display off.

Set the number of lines of source code to be displayed when the target machine stops.

• Only one source display may be active at a time.

See Also: display, regwin.

sstep

sstep [<default command>]

Examples:

"ss"

enter source step mode

"sstep n"

enter source step mode, <ret> does a next command

Step through the execution of the current patient by source lines. This is THE command for stepping through high-level (e.g., C) code.

• 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.
• Sstep steps through the patient line by line, printing where the instruction pointer is and what line is to be executed Sstep waits for the user to type a command which it performs and then prints out again where sstep is executing.
• This is a list of sstep commands:

q , < Esc >,` `

Stops sstep and returns to command level.

b

Toggles a breakpoint at the current location.

c

Stops sstep and continues execution.

n

Continues to the next source line, skipping procedure calls, repeated string instructions, and software interrupts. 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).

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.

M

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

f

Finishes out the current stack frame.

s , < Ret >

Steps one source line

S

Skips the current instruction

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

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

h , ?

A help message.

• Emacs will load in the correct file executing and following the lines where sstep is executing if its server is started and if ewatch is on in swat. If ewatch is off emacs will not be updated.
• If the current patient isn't the actual current thread, sstep waits for the patient to wake up before single-stepping it.

See Also: istep, listi.

stdpaths

stdpaths

Examples: "stdpaths"

Print out all paths set for standard directories

See Also: pwd, dirs.

step

step

Examples:

"step"

execute the next instruction

"s"

Execute the patient by a single machine instruction.

• If waitForPatient is non-zero, step waits for the machine to stop again.
• This doesn't do any of the checks for special conditions (XchgTopStack, software interrupts, etc.) performed by the `s' command in istep.

See Also: istep, next.

step-patient

step-patient 

Examples:

"step-patient"

Execute a single instruction on the target PC.

Causes the PC to execute a single instruction, returning only when the instruction has been executed.

• Unlike the continue-patient command, this command will not return until the machine has stopped again.
• No other thread will be allowed to run, as timer interrupts will be turned off while the instruction is being executed.

See Also: help-fetch.

step-until

step-until expression [byte|word]

Examples:

"step-until ax=0"

Single-step until ax is zero.

"step-until ds:20h!=0 byte"

Single-step until byte at ds:20h is non-zero

"step-until ds:20h!=0 word"

Single-step until word at ds:20h is non-zero

"step-until c=0"

Single-step until the carry is clear

"step-until ax!=ax"

Step forever

This command causes Swat to step until a condition is met.

Useful for tracking memory or register trashing bugs.

stop

stop in <class>::<message> [if <expr>]
stop in <procedure> [if <expr>]
stop in <address-history-token> [if <expr>]
stop at [<file>:]<line> [if <expr>]
stop <address> [if <expr>]

Examples: "stop in main"
"stop in @3"
"stop at /staff/pcgeos/Loader/main.asm:36 if { joe_local ==22}"
"stop at 25"
"stop MemAlloc+3 if {ax==3}"

Specify a place and condition at which the machine should stop executing. This command is intended primarily for setting breakpoints when debugging a geode created in C or another high-level language, but may also be used when debugging assembly-language geodes.

• "stop in" will set a breakpoint at the beginning of a procedure, immediately after the procedure's stack frame has been set up.
• "stop at" will set a breakpoint at the first instruction of the given source line. If no <file> is specified, the source file for the current stack frame is used.
• If a condition is specified, by means of an "if <expr>" clause, you should enclose the expression in {}'s to prevent any nested commands, such as a "value fetch" command, from being evaluated until the break-point is hit.
• For convenience, "stop in" also allows address-history tokens. This is useful when used in conjunction with the "methods" command.

See Also: brk, ibrk.

stop-catch

stop-catch <body>

Examples:

"stop-catch {go ProcCallModuleRoutine}"

Let machine run until it reaches ProcCallModuleRoutine() , but do not issue a FULLSTOP event when it gets there.

Allows a string of commands to execute without a FULLSTOP event being generated while they execute.

A number of things happen when a FULLSTOP event is dispatched, including notifying the user where the machine stopped. This is inappropriate in something like "istep" or "cycles" that is single-stepping the machine, for example.

See Also: event, continue-patient, step-patient.

stop-patient

stop-patient

Examples:

"stop-patient"

Stops the target PC.

Stops the target PC, in case you continued it and didn't wait for it to stop on its own.

This is different from the "stop" subcommand of the "patient" command.

See Also: continue-patient.

stream

stream open <file> (r|w|a|r+|w+)
stream read (line|list|char) <stream>
stream print <list> <stream>
stream write <string> <stream>
stream rewind <stream>
stream seek (<posn>|+<incr>|-<decr>|end) <stream>
stream state <stream>
stream eof <stream>
stream close <stream>
stream flush <stream>
stream watch <stream> <what> <procName>
stream ignore <stream>

Examples:

"var s [stream open kmap.def w]"

Open the file "kmap.def" for writing, creating it if it wasn't there before, and truncating any existing file.

"stream write $line $s"

Write the string in $line to the open stream.

This allows you to read, write, create, and otherwise manipulate files on the host machine from Swat.

• Subcommands may be abbreviated uniquely.
• Streams are a precious resource, so you should be sure to always close them when you are done. This means stream access should usually be performed under the wings of a "protect" command so the stream gets closed even if the user types Ctrl+C.
• Swat's current directory changes as you change stack frames, with the directory always being the one that holds the executable file for the patient to which the function in the current frame belongs. If the <file> given to "stream open" isn't absolute, it will be affected by this.
• The global variable file-init-dir contains the absolute path of the directory in which Swat was started. It can be quite useful when forming the <file> argument to "stream open".
• The second argument to "stream open" is the access mode of the file. The meanings of the 5 possible values are:

r

read-only access. The <file> must already exist.

w

write-only access. If <file> doesn't already exist, it will be created. If it does exist, it will be truncated.

a

append mode. The file is opened for writing only. If <file> doesn't already exist, it will be created. If it does exist, writing will commence at its end.

r+

read/write. The <file> must already exist. A single read/write position is maintained, and it starts out at the start of the file.

w+

read/write. If <file> doesn't already exist, it will be created. If it does exist, it will be truncated. A single read/write position is maintained, and it starts out at the start of the file.

• "stream read" can read data from the stream in one of three formats:

line

Returns all the characters from the current position up to the first newline or the end of the file, whichever comes first. The newline, if seen, is placed at the end of the string as \n. Any other non-printable characters or backslashes are similarly escaped.

list

Reads a single list from the stream, following all the usual rules of Tcl list construction. If the character at the current read position is a left brace, this will read to the matching right brace, bringing in newlines and other whitespace. If there is whitespace at the initial read position, it is skipped. Standard Tcl comments before the start of the list are also skipped over (so if the first non-whitespace character encountered is #, the characters up to the following newline or end-of-file will also be skipped).

char

This reads a single character from the stream. If the character isn't printable ASCII, it will be returned as one of the regular Tcl backslash escapes.

If there's nothing left to read, you will get an empty string back.

• "stream write" writes the string exactly as given, without interpreting backslash escapes. If you want to include a newline or something of the sort in the string, you'll need to use the "format" command to generate the string, or place the whole thing in braces and have the newlines in there literally.
• While the syntax for "stream print" is the same as for "stream write", there is a subtle difference between the two. "stream write" will write the string as it's given, while "stream print" is intended to write out data to be read back in by "stream read list". Thus the command

 stream write {foo biff} $s

would write the string "foo biff" to the stream. In contrast,

 stream print {foo biff} $s

would write "{foo biff}" followed by a newline.

• To ensure that all data you have written has made it to disk, use the "stream flush" command. Nothing is returned.
• "stream rewind" repositions the read/write position at the start of the stream. "stream seek" gives you finer control over the position. You can set the stream to an absolute position (obtained from a previous call to "stream seek") by passing the byte number as a decimal number. You can also move forward or backward in the file a relative amount by specifying the number of bytes to move, preceded by a "+", for forward, or a "-", for backward. Finally, you can position the pointer at the end of the file by specifying a position of "end".
• "stream seek" returns the new read/write position, so a call of "stream seek +0 $s" will get you the current position without changing anything. If the seek couldn't be performed, -1 is returned.
• "stream state" returns one of three strings: "error", if there's been some error accessing the file, "eof" if the read/write position is at the end of the file, or "ok" if everything's fine. "stream eof" is a shortcut for figuring if you've reached the end of the file.
• "stream close" shuts down the stream. The stream token should never be used again.
• "stream watch" and "stream ignore" are valid only on UNIX and only make sense if the stream is open to a device or a socket. "stream watch" causes the procedure <procName> to be called whenever the stream is ready for the access indicated by <what>, which is a list of conditions chosen from the following set:

read

the stream has data that may be read.

write

the stream has room for data to be written to it.

When the stream is ready, the procedure is called:

 <procName> <stream> <what>

where <what> is the list of operations for which the stream is ready.

See Also: protect, source, file.

switch

switch <thread-id>
switch [<patient>] [:<thread-num>]

Examples:

"switch 3730h"

Switches swat's current thread to be the one whose handle ID is 3730h.

"switch :1"

Switches Swat's current thread to be thread number 1 for the current patient.

"switch parallel:2"

Switches Swat's current thread to be thread number 2 for the patient "parallel"

"switch write"

Switches Swat's current thread to be thread number 0 (the process thread) for the patient "write"

"switch"

Switches Swat's current thread to be the current thread on the PC.

Switches between applications/threads.

• Takes a single argument of the form <patient>:<thread-num> or <threadID>. With the first form, :<thread-num> is optional -- if the patient has threads, the first thread is selected. To switch to another thread of the same patient, give just :<thread-num>. You can also switch to a patient/thread by specifying the thread handle ID. NOTE: The switch doesn't happen on the PC--just inside swat.
• If you don't give an argument, it switches to the actual current thread in the PC.

symbolCompletion

var symbolCompletion [(0|1)]

Examples:

"var symbolCompletion 1"

Enable symbol completion in the top-level command reader.

This variable controls whether you can ask Swat to complete a symbol for you while you're typing a command. Completion is currently very slow and resource-intensive, so you probably don't want to enable it.

• Even when symbolCompletion is 0, file-name, variable-name, and command- name completion are always enabled, using the keys described below.
• When completion is enabled, three keys cause the interpreter to take the text immediately before the cursor and look for all symbols that begin with those characters. The keys are:

Ctrl+D

Produces a list of all possible matches to the prefix.

Escape

Completes the command as best possible. If the characters typed so far could be the prefix for more than one command, Swat will fill in as many characters as possible.

Ctrl+]

Cycles through the list of possible symbols, in alphabetical order.

sym-default

sym-default [<name>]

Examples:

"sym-default motif"

Make swat look for any unknown symbols in the patient named "motif" once all other usual places have been searched.

Specifies an additional place to search for symbols when all the usual places have been searched to no avail.

• The named patient need not have been loaded yet when you execute this command.
• A typical use of this is to make whatever program you're working on be the sym-default in your .swat file so you don't need to worry about whether it's the current one, or reachable from the current one, when the machine stops and you want to examine the patient's state.
• If you don't give a name, you'll be returned the name of the current sym-default.

sysfiles

sysfiles

Examples:

"sysfiles"

Print out all open files from dos's system file table.

Normally SFT entries that aren't in-use aren't printed. If you give the optional argument "all", however, all SFT entries, including those that aren't in-use, will be printed.

See Also: geosfiles, sftwalk, fwalk.

systemobj

systemobj

Examples:

"gentree [systemobj]"

print the generic tree starting at the system's root

"pobject [systemobj]"

print the system object

Prints out the address of the uiSystemObj, which is the top level of the generic tree.

• This command is normally used with gentree as shown above to print out the whole generic tree starting from the top.

See Also: gentree, impliedgrab.

target

target [<object>]

Examples:

"target"

print target hierarchy from the system object down

"target -i"

print target hierarchy from implied grab down

"target ^l4e10h:20h"

print target hierarchy from ^l4e10h:20h down

"target [content]"

print target hierarchy from content under mouse.

Prints the target hierarchy below an object.

• If no argument is specified, the system object is used.
• The special object flags may be used to specify <object>. For a list of these flags, see pobject.
• Remember that the object you start from may have the target within its part of the hierarchy, but still not have the target because something in a different part of the tree has it.
• 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: focus, model, mouse, keyboard, pobject.

targetobj

targetobj

Examples:

"targetobj"

return object with target

"pobj [targetobj]"

do a pobject on the target object (equivalent to "pobj -t").

Returns the object with the target.

See Also: target, focus, focusobj, modelobj.

tbrk

tbrk <addr> <condition>*
tbrk del <tbrk>+
tbrk list
tbrk cond <tbrk> <condition>*
tbrk count <tbrk>
tbrk reset <tbrk>
tbrk address <tbrk>

Examples:

"tbrk ObjCallMethodTable"

Count the number of times ObjCallMethodTable() is called.

"tbrk count 2"

Find the number of times tally breakpoint number 2 was hit.

"tbrk reset 2"

Reset the counter for tbrk number 2 to 0.

"tbrk list"

Print a list of the set tally breakpoints and their current counts.

This command manipulates breakpoints that tally the number of times they are hit without stopping execution of the machine--the breakpoint is noted and the machine is immediately continued. Such a breakpoint allows for real-time performance analysis, which is nice.

• If you specify one or more <condition> arguments when setting the tally breakpoint, only those stops that meet the conditions will be counted.
• The condition argument is exactly as defined by the "brk" command, q.v..
• When you've set a tally breakpoint, you will be returned a token of the form "tbrk<n>", where <n> is some number. You use this token, or just the <n>, if you're not a program, wherever <tbrk> appears in the Usage description, above.
• There are a limited number of tally breakpoints supported by the stub. You'll know when you've set too many.
• "tbrk address" returns the address at which the tbrk was set, as a symbolic address expression.

See Also: brk, cbrk.

tcl-debug

tcl-debug top 
tcl-debug next <tcl-frame>
tcl-debug prev <tcl-frame>
tcl-debug args <tcl-frame>
tcl-debug getf <tcl-frame>
tcl-debug setf <tcl-frame> <flags>
tcl-debug eval <tcl-frame> <expr>
tcl-debug complete <tcl-frame>
tcl-debug next-call 

Examples:

"var f [tcl-debug top]"

Sets $f to be the frame at which the debugger was entered.

"var f [tcl-debug next $f]"

Retrieves the next frame down (away from the top) the Tcl call stack from $f.

This provides access to the internals of the Tcl interpreter for the Tcl debugger (which is written in Tcl, not C). It will not function except after the debugger has been entered.

See Also: debug.

text-fixup

1. Run geos under swat, run swat on the development system
2. Run GeoWrite
3. Open the GeoWrite file that needs fixing
4. Set the breakpoint in swat:

 patch text::CalculateRegions
 => text-fixup

This will set a breakpoint at the right spot

5. Turn on the error-checking code in swat:

 ec +text 

6. Enter a <space> into the document. This forces recalculation which will cause CalculateRegions() to be called which will cause text-fixup to be called.

If it worked, this code should patch together the file. If it's not, you'll get a FatalError right now.

7. Turn off the ec code and disable the fixup breakpoint.

 ec none

 dis <breakpoint number>

 continue 

8. Delete the space and save the file.

To do another file, you can just enable the breakpoint once the new file is open and turn on the ec code.

Helps fix up trashed GeoWrite documents.

thaw

thaw [<patient>]
thaw :<n>
thaw <patient>:<n>
thaw <id>

Examples:

"thaw"

Thaw the current thread.

"thaw term"

Allows the application thread for "term" to run normally

"thaw :1"

Allows thread #1 of the current patient to run normally

"thaw 16c0h"

Allows the thread whose handle is 16c0h to run normally.

Thawing a thread restores its priority to what it was before the thread was frozen.

See Also: freeze.

threadname

threadname <id>

Examples:

"threadname 21c0h"

Returns the name of the thread whose handle id is 21c0h.

Given a thread handle, produces the name of the thread, in the form <patient>:<n>

If the handle is not one of those swat knows to be for a thread, this returns the string "unknown."

See Also: thread, patient.

threadstat

threadstat

Examples:

"threadstat"

Provides information about all threads and various thread queues and synchronization points in the system.

See Also: ps.

timebrk

timebrk <start-addr> <end-addr>+
 timebrk del <timebrk>+
 timebrk list
 timebrk time <timebrk>
 timebrk reset <timebrk>

Examples:

"timebrk LoadResourceData -f"

Calculate the time required to process a call to LoadResourceData() .

"timebrk time 2"

Find the amount of time accumulated for timing breakpoint number 2.

"timebrk reset 2"

Reset the counter for timebrk number two to zero.

"timebrk list"

Print a list of the set timing breakpoints and their current counts and time.

This command manipulates breakpoints that calculate the amount of time executing between their starting point and a specified ending point. The breakpoints also record the number of times their start is hit, so you can figure the average amount of time per hit.

• You can specify a place at which timing should end either as an address or as "-f". If you use "-f", timing will continue until the finish of the routine at whose start you've placed the breakpoint. Such a breakpoint may only be set at the start of a routine, as the stub hasn't the wherewithal to determine what the return address is at an arbitrary point within the function.
• You may specify more than one ending point. Timing will stop when execution reaches any of those points.
• When you've set a timing breakpoint, you will be returned a token of the form "timebrk<n>", where <n> is some number. You use this token, or just the <n>, if you're not a program, wherever <timebrk> appears in the Usage description, above.

See Also: brk, cbrk, tbrk.

timingProcessor

var timingProcessor [i86|i88|i286|V20]

The processor for which to generate cycle counts.

See Also: cycles.

tmem

tmem

Examples:

"tmem"

turn on memory tracing.

Trace memory usage.

The tmem command catches calls to DebugMemory, printing out the parameters passed (move, free, realloc, discard, swapout, swapin, modify).

top-level

top-level

Examples:

"top-level"

Begin reading and interpreting Tcl commands in a nested interpreter.

This is the top-most read-eval-print loop of the Swat Tcl interpreter.

This command will only return if the user issues the "break" command. Otherwise it loops infinitely, reading and executing and printing the results of Tcl commands.

tundocalls

tundocalls [-acPCrR]

Examples:

"tundocalls -a" Print out all text undo calls

"tundocalls -r" Print run undo calls

"tundocalls -R" Print replace undo calls

"tundocalls -c" Print info when undo information is created

"tundocalls -cP" Print info about para attributes only

"tundocalls -cC" Print info about char attributes only

"tundocalls"

Prints out information about each undo call made to the text object.

See Also: ptext, showcalls.

twalk

twalk

Examples:

"twalk"

print all the timers in the system.

"twalk -o ui"

print all the timers in the system for the ui thread.

"twalk -a"

print all the timers with the "real" data for the time for time remaining rather than maintaining a total.

List all the timers in GEOS.

unalias

unalias <name>+

Examples:

"unalias p"

Removes "p" as an alias for print.

This removes an alias.

• In fact, this actually can be used to delete any command at all, including Tcl procedures and Swat built-in commands. Once they're gone, however, there's no way to get them back.

See Also: alias.

unassemble

unassemble [<addr> [<decode-args>]]

Examples:

"unassemble cs:ip 1"

Disassemble the instruction at CS:IP and return a string that shows the values of the arguments involved.

This decodes data as machine instructions and returns them to you to display as you like. It is not usually typed from the command line.

• The return value is always a four-element list:

 {<symbolic-addr> <instruction> <size> <args>}

where <symbolic-addr> is the address expressed as an offset from some named symbol, <instruction> is the decoded instruction (without any leading whitespace), <size> is the size of the instruction (in bytes) and <args> is a string displaying the values of the instruction operands, if <decode-args> was given and non-zero (it is the empty string if <decode-args> is missing or 0).

• If <addr> is missing or "nil", the instruction at the current frame's CS:IP is returned.

See Also: listi.

unbind-key

unbind-key <ascii_value>

Examples:

"unbind-key \321"

Unbinds scroll-down key on host machine.

Unbinds the passed ASCII value.

See Also: alias, bind-key, get-key-binding.

undebug

undebug <proc-name>+

Examples:

"undebug fooproc"

Cease halting execution each time "fooproc" is executing.

Removes a Tcl breakpoint set by a previous "debug" command.

See Also: debug.

up

up [<frame offset>]

Examples:

"up"

move the frame one frame up the stack

"up 4"

move the frame four frames up the stack

Move the frame up the stack.

• The <frame offset> argument is the number of frame to move up the stack. If none is specified then the current frame is moved up one frame.
• This command may be repeated by pressing <Return>.

See Also: backtrace, down.

value

value fetch <addr> [<type>]
value store <addr> <value> [<type>]
value hfetch <num>
value hstore <addr-list>
value hset <number-saved>
value log <addr> <stream> [<type>]

Examples:

"value fetch ds:si [type word]"

Fetch a word from ds:si

"value store ds:si 0 [type word]"

Store 0 to the word at ds:si

"value hfetch 36"

Fetch the 36th address list stored in the value history.

"value hstore $a"

Store the address list in $a into the value history.

"value hset 50"

Keep track of up to 50 address lists in the value history.

"value log ds:si $s [type word]"

Fetch a word from ds:si and dump the binary data to stream $s.

This command allows you to fetch and alter values in the target PC. It is also the maintainer of the value history, which you normally access via @<number> terms in address expressions.

• "value fetch" returns a value list that contains the data at the given address. If the address has an implied data type (it involves a named variable or a structure field), then you do not need to give the <type> argument.

All integers and enumerated types are returned in decimal. 32-bit pointers are returned as a single decimal integer whose high 16 bits are the high 16 bits (segment or handle) of the pointer. 16-bit pointers are likewise returned as a single decimal integer.

Characters are returned as characters, with non-printable characters converted to the appropriate backslash escapes (for example, newline is returned as \n).

Arrays are returned as a list of value lists, one element per element of the array.

Structures, unions and records are returned as a list of elements, each of which is a 3-element list: {<field-name> <type> <value>} <field-name> is the name of the field, <type> is the type token for the type of data stored in the field, and <value> is the value list for the data in the field, appropriate to its data type.

• You will note that the description of value lists is recursive. For example, if a structure has a field that is an array, the <value> element in the list that describes that particular field will be itself a list whose elements are the elements of the array. If that array were an array of structures, each element of that list would again be a list of {<field-name> <type> <value>} lists.
• The "field" command is very useful when you want to extract the value for a structure field from a value list.
• As for "value fetch", you do not need to give the <type> argument to
• "value store" if the <addr> has an implied data type. The <value> argument is a value list appropriate to the type of data being stored, as described above.
• "value hstore" returns the number assigned to the stored address list. These numbers always increase, starting from 1.
• If no address list is stored for a given number, "value hfetch" will generate an error.
• "value hset" controls the maximum number of address lists the value history will hold. The value history is a FIFO queue; if it holds 50 entries, and the 51st entry is added to it, the 1st entry will be thrown out.
• "value log" has the same functionality as value fetch except that data fetched from the PC are dumped into the stream as raw binary data.

See Also: addr-parse, assign, field.

varwin

varwin <num-lines> <var-name> 

view

view [<args>]

Examples:

"view foo.goc"

Bring up foo.goc in the source window.

View a file in Swat.

See Also: view-default, srcwin.

view-default

view-default [patient]

Examples:

"view-default spool"

sets the default view to the spool patient.

"view-default"

turns off the view default.

If the view-default is set the view command will automatically look for source files from that patient. If it's not set then the view command will look for files from the current patient.

See Also: view, srcwin.

vistree

vistree [<address>] [<instance field>]

Examples:

"vistree"

print the visual tree starting at *DS:SI

"vistree -i"

print the visual tree under the mouse

"vistree @23 VI_optFlags"

print the visual tree with opt flags

"vistree *uiSystemObj"

starts the visual tree at the root of the system.

Print out a visual tree.

• 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.
• The special object flags may be used to specify <object>. For a list of these flags, see pobject.
• The <instance field> argument is the offset to any instance data within the VisInstance which should be printed out.
• 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: vup, gentree, impliedgrab, pobject.

vup

vup [<address>] [<instance field>]

Examples:

"vup"

print the visual object at *DS:SI and its ancestors

"vup @23 VI_optFlags"

print the states of object @23 and its ancestors

"vup -i"

print the visual object under the mouse and the object's ancestors

Print a list of the object and all of its visual ancestors.

• The <address> argument is the address to an object in the visual tree. This defaults to *DS:SI. The `-i' flag for an implied grab may be used.
• The special object flags may be used to specify <object>. For a list of these flags, see pobject.
• The <instance field> argument is the offset to any instance data within the GenInstance which should be printed out.

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

wait

wait

Examples:

"wait"

Wait for the target PC to halt.

This is used after the machine has been continued with "continue-patient" to wait for the machine to stop again. Its use is usually hidden by calling "cont" or "next".

• This returns 0 if the patient halted naturally (because it hit a breakpoint), and 1 if it was interrupted (by the user typing Ctrl+C to Swat).
• Most procedures won't need to use this function.

See Also: brk, ibrk.

waitForPatient

var waitForPatient [(1|0)]

Examples:

"var waitForPatient 0"

Tells Swat to return to the command prompt after continuing the machine.

Determines whether the command-level patient-continuation commands (step, next, and cont, for example) will wait for the machine to stop before returning.

• The effect of this is to return to the command prompt immediately after having issued the command. This allows you to periodically examine the state of the machine without actually halting it.
• The output when the machine does stop (e.g. when it hits a breakpoint) can be somewhat confusing. Furthermore, this isn't fully tested, so it should probably be set to 0 only in somewhat odd circumstances.

See Also: step, next, cont, int.

wakeup

Wait for a given patient/thread to wake up. WHO is of the same form as the argument to the "switch" command, ("help switch" to find out more). Leaves you stopped in the kernel in the desired thread's context unless something else causes the machine to stop before the patient/thread wakes up. WHO defaults to the current thread.

wakeup-thread

Subroutine to actually wake up a thread. Argument WHO is as for the "switch"command. Returns non-zero if the wakeup was successful and zero if the machine stopped for some other reason.

wclear

wclear

Clears the current window.

wcreate

wcreate <height>

Create a window of the given height and return a token for it. The window is placed just above the command window, if there's room. If there aren't that many lines free on the screen, an error is returned.

wdelete

wdelete <window>

Delete the given window. All windows below it move up and the command window enlarges.

whatat

whatat [<address>]

Examples:

"whatat"

name of variable at *DS:SI

"whatat ^l2ef0h:002ah"

name of variable at the specified address

Print the name of the variable at the address.

• The <address> argument specifies where to find a variable name for. The address defaults to *DS:SI.
• If no appropriate variable is found for the address, `*nil*' is returned.

See Also: pobject, hwalk, lhwalk.

whatis

whatis (<symbol>|<addr>)

Examples: "whatis WinColorFlags"

This produces a human-readable description of a symbol, giving whatever information is pertinent to its type.

• For type symbols (e.g. structures and enumerated types), the description of the type is fully displayed, so if a structure has a field with an enumerated type, all the members of the enumerated type will be printed as well. Also all fields of nested structures will be printed. If this level of detail isn't what you need, use the "pscope" command instead.
• It's not clear why you'd need the ability to find the type of an address-expression, since those types always come from some symbol or other, but if you want to type more, you certainly may.

why

why

Examples: "why"

Print a description of why the system crashed.

• 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.
• This simply looks up the enumerated constant for the error code in AX 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 application defines this enumerated type by virtue of having included ec.def or ec.goh .
• For certain fatal errors, additional information is provided by invoking the command <patient>::<error code name>, if it exists.

See Also: regs, backtrace, explain.

wintree

wintree <window handle> [<data field>]

Examples:

"wintree ^hd060h"

print a window tree starting at the handle d060h

Print a window tree starting with the root specified.

• The <window address> argument is the address to a window.
• The <data field> argument is the offset to any instance data within a window (like W_ptrFlags).

See Also: vistree, gentree.

winverse

winverse

Sets the inverse-mode of the current window (whether newly-echoed characters are displayed in inverse video) on or off, depending on its argument (1 is on).

wmove

wmove [(+|-)] <x-coord> [(+|-)] <y-coord>

Moves the cursor for the current window. Takes two arguments: the new x position and the new y position. These positions may be absolute or relative (absolute positions begin with + or -). If you attempt to move outside the current window, an error is generated. This command returns the new cursor position as { x y }.

words

words [<address>] [<length>]

Examples:

"words"

lists 8 words at DS:SI

"words ds:di 16"

lists 16 words starting at DS:DI

Examine memory as a dump of words.

• 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.
• The <length> argument is the number of bytes to examine. It defaults to 8.
• Pressing <Return> after this command continues the list.

See Also: bytes, dwords, imem, assign.

wpop

wpop

Revert the current window to its previously pushed value.

wpush

wpush <window>

Switch to a new window, saving the old current-window. Use wpop to go back to the previous window. All I/O goes through the current window.

wrefresh

wrefresh

Synchronizes the current window with the screen. This need only be performed if you don't echo a newline, as echoing a newline refreshes the current window.

wtop

wtop <flag>

Sets where windows go. If argument is non-zero, windows go at the top of the screen and work down. Else windows go at the bottom of the screen and work up