3. Command Dictionary

Example

topaz 1> set transactionmode manualbegin

transaction aborted and mode changed to manualBegin

topaz 1> begin

<perform database operations>

topaz 1> commit

Successful commit

break aSubCommand

Establishes or displays a method breakpoint within GemStone Smalltalk code. Subcommands are method, classmethod, list, enable, disable, and delete. For more information about using breakpoints, see Chapter 2, “Debugging Your GemStone Smalltalk Code”.

Setting Breakpoints

You can set breakpoints on a method, or at any step point within a method. Step points includes assignments, message sends, and method returns. To display the step points for a method, use the list steps command.

In the following commands, the argument @ stepPoint specifies the step point within that method where the break is to occur. If you omit the step point, the breakpoint is established at step 1 of the method.

You may not set method breakpoints in any method whose sole function is to perform any of the following actions: return self, return nil, return true, return false, return or update the value of an instance variable, return the value of a literal, or return the value of a literal variable (that is, a class variable, a pool variable, or a variable defined in your symbol list).

You can specify the method using method/classmethod, or using the >> syntax.

break METHOD classSpecification methodName [ @ stepPoint ]

break CLASSMETHOD classSpecification methodName [ @ stepPoint ]

break METHOD methodSpecification [ @ stepPoint ]

break CLASSMETHOD methodSpecification [ @ stepPoint ]

break @ stepPoint

classSpecification can be defined in these ways:

methodSpecification is an unsigned 64-bit decimal OOP value of a GsNMethod instance, which defines both the class and method.

The @ stepPoint format applies after certain other commands that set a specific selected method, such as lookup and list.

The break command accepts the >> syntax to specify a method, using the following forms:

break className >> methodName [ @ stepPoint ]

break className class >> methodName [ @ stepPoint ]

break className (implementationClassName) >> methodName [ @ stepPoint ]

break className class (implementationClassName) >> methodName [ @ stepPoint ]

The implementationClassName specifies that the method lookup begins with implementationClassName, normally a superclass of className. This style is used in topaz stack summaries, and allows paste in of lines from the stack.

break KeyValueDictionary >> at:put: @ 1

break @79361 >> at:put: @ 2

break IdentityDictionary (KeyValueDictionary) >> at:put: @ 3

break method KeyValueDictionary at:put: @ 4

break method @79361 at:put: @ 5

set class KeyValueDictionary

break method ^ at:put: @ 7

exec KeyValueDictionary %

break method ** at:put: @ 6

break method @5094401 @ 8

lookup KeyValueDictionary >> at:put:

break @9

Displaying Breakpoints

break list
Lists all currently set breakpoints. In the display, each breakpoint is identified by a break index for subsequent use in break disable, break enable, and break delete commands.

Disabling and Enabling Breakpoints

break disable anIndex
Disables the breakpoint identified by anIndex in the break list command.

break disable all
Disables all currently set breakpoints.

break enable anIndex
Reenables the breakpoint identified by anIndex in the break list command.

break enable all
Reenables all disabled breakpoints.

Deleting Breakpoints

break delete anIndex
Deletes the breakpoint identified by anIndex in the break list command.

break delete all
Deletes all currently set breakpoints.

Examples

topaz 1> break method GsFile nextLine

Establishes a breakpoint at step point 1 of the instance method nextLine for GsFile.

topaz 1> break classmethod GsFile openRead: @ 2

Establishes a breakpoint at step point 2 of the class method openRead: for GsFile.

topaz 1> set class Stringtopaz 1> break method ^ < @ 2

Establishes a breakpoint at step point 2 of the instance method “<” for the current
class (String).

topaz 1> break list

1: GsFile >> nextLine @ 1

2: GsFile class >> openRead: @ 2

3: String >> < @ 2

topaz 1> break disable 2

topaz 1> break list

1: GsFile >> nextLine @ 1

2: GsFile class >> openRead: @ 2 (disabled)

3: String >> < @ 2

topaz 1> break enable 2

topaz 1> break list

1: GsFile >> nextLine @ 1

2: GsFile class >> openRead: @ 2

3: String >> < @ 2

topaz 1> break delete 1

topaz 1> break list

2: GsFile class >> openRead: @ 2

3: String >> < @ 2

topaz 1> break delete all

topaz 1> break list

No breaks set

category: aCategoryName

Sets the current category, the category for subsequent method compilations. If you try to compile a method without first selecting a category, the new method is inserted in the default category “as yet unspecified.” This command has the same effect as the set category: command.

If the category you name doesn’t already exist, Topaz creates it when you first compile a method. If you wish to include spaces in the category name you specify, enclose the category name in single quotes.

Specifying a new class with set class does not change your category. However, when you edit or fileout a method, that method’s category becomes the current category.

The current category is cleared by the logout, login, and set session commands.

topaz 1> category: Accessing

topaz 1> category: 'Public Methods'

classmethod [: aClassName]

Compiles a class method for the class whose name is given as a parameter. The class of the method you compile is automatically selected as the current class. If you don’t supply a class name, the method is compiled for the current class (as defined by the most recent set class:, list categoriesin:, method:, classmethod:, removeAllMethods, removeAllClassMethods, or fileout class: command).

Text of the method should follow this command on subsequent lines. The method text is terminated by the first line that contains a % character as the first character in the line. For example:

topaz 1> classmethod: Animal

returnAString

	^String new

%

Topaz sends the method’s text to GemStone for compilation and inclusion in the current category of the specified class. If you haven’t yet selected a current category, the new method is inserted in the default category “as yet unspecified.”

continue [anObjectSpec]

c [anObjectSpec]

Attempts to continue GemStone Smalltalk execution on the active call stack after encountering a breakpoint, a pause message, or a user-defined error. The call stack becomes active, and the continue command becomes accessible, when you execute GemStone Smalltalk code containing a breakpoint.

continue
Attempts to continue execution.

continue anObjectSpec
Replaces the value on the top of the stack with anObjectSpec and attempts to continue execution.

The argument anObjectSpec can be specified using any of the formats described in Specifying Objects.

For more information about breakpoints, see the discussion of the break command here, or see Chapter 2, “Debugging Your GemStone Smalltalk Code”.

For information about replacing the value on the top of the stack, see the GciContinueWith function in the GemBuilder for C Manual

For information about Object’s pause method, see the method comments for Object>>pause.

For information about user-defined errors, see the discussion of error-handling in the Programming Guide for GemStone/S 64 Bit. User manuals for the GemStone interfaces, such as GemBuilder for Smalltalk, also contain discussions of error-handling.

debuggem processId token

Takes two integer arguments, a processId and a token.

The processId must be the PID of a gem or topaz -l, running on localhost, which was either configured with GEM_LISTEN_FOR_DEBUG=true, or which has previously executed System class >> listenForDebugConnection.

The token is a random integer printed by that target gem process to its log file (or stdout and current .out file of the topaz -l), or returned by System class >> listenForDebugConnection.

debuggem attempts to attach to the target gem and create a topaz session in this topaz process which has debugging control over the target gem.

If Smalltalk execution is in progress in the target gem, it is interrupted with equivalent of GciSoftBreak() and the resulting stack can be examined by the topaz session created by debuggem.

If execution is not in progress, then the debuggem topaz gets control of the target gem, blocking further GCI calls from the target gem's client or blocking further topaz commands from the target's topaz -l.

If a fetch or store traversal is in progress, the debuggem topaz will get control of the target gem when the traversal completes.

While a topaz session from debuggem is control of a target gem, commit by the target gem is not allowed.

LOGOUT or CONTINUE will close the topaz session created by debuggem and release the target gem or topaz -l to continue execution and servicing of GCI or topaz commands.

Certain topaz commands such as BREAK, STEP, STACK TRIM that would alter the stack are disallowed in the debuggem session; the stack from the synthesized soft break can be examined and then continued with CONTINUE or LOGOUT.

debuggem cannot be abbreviated, it must be typed in full.

For more information, see Debugging in a different Gem.

define [aVarName [anObjectSpec [aSelectorOrArg]...]]

Defines local Topaz variables that allow you to refer to objects in commands such as send and object.

All Topaz object specification formats (as described in Specifying Objects) are legal in define commands. The variable name aVarName must begin with a letter (a..z or A..Z) or an underscore, can be up to 255 characters in length, and cannot contain white space.

You may not redefine the topaz predefined variables CurrentMethod, ErrorCount, CurrentCategory, CurrentClass, LastResult, LastText, and myUserProfile.

define
Lists all current local variable definitions.

define aVarName
Deletes the definition of the variable aVarName.

define aVarName anObjectSpec
Define a local variable whose value is result of anObjectSpec.

define aVarName anObjectSpec aSelectorOrArg ...
Sends a message to the object specified by anObjectSpec, and saves the result as a local variable with the name aVarName.

For example:

topaz 1> define CurrentSessions System currentSessionNames

topaz 1> define UserId myUserProfile userId

topaz 1> define

Current definitions are:

  UserId            = 2673409

  CurrentSessions   = 33659905

------------------------

  CurrentMethod     = nil

  ErrorCount        = 2

  CurrentCategory   = nil

  CurrentClass      = nil

  LastResult        = nil

  LastText          = nil

  myUserProfile     = 1458177

Topaz tries to interpret all command line tokens following anObjectSpec as a message to the specified object.

disassem [ aClassParameter ] aParamValue

The disassem command allows you to disassemble the specified GsNMethod, displaying the assembly code instructions.

The disassem command is intended for use in a linked (topaz -L) session only. If the session is remote, the output goes to stdout of the remote Gem, which is the gem log.

disassem @anOop
Disassemble the method or code object with the specified oop.

disassem method: aSelectorSpec
Disassemble the specified instance method for the class previous set by the set class command.

disassem classmethod: aSelectorSpec
Disassemble the specified class method for the class previous set by the set class command.

display aDisplayFeature

The display and omit commands control the display of Gemstone Smalltalk objects and other features related to output.

The display command turns on these display attributes, and the omit command turns them off.;

topaz 1> exec #[ 97 98 99 ] %

  1 'abc'                      61 62 63

topaz 1> exec #[ 97 98 99 ] %

 1 'abc'                       97  98  99

deprecated

deprecated: 

deprecatedNotification:

topaz 1> implementors concurrencyMode

System class >> concurrencyMode

topaz 1> omit deprecated

topaz 1> implementors concurrencyMode

(Omitted 1 deprecated methods)

using line editor

not using line editor

Execution has been suspended by a "pause" message.

Topaz pausing after error, type <return> to continue, ctl-C to quit ? 

display interactive pause on errors

omit interactive pause on errors

display interactive pause on warnings

omit interactive pause on warnings

down [anInteger]

Moves the active frame down within the current stack, and displays the frame selected as a result. The optional argument anInteger specifies how many frames to move down. If no argument is supplied, the scope will go down one frame. See also stack down here.

The frame displayed includes parameters and temporaries for the frame, unlike the results displayed by stack down.

topaz 1> where

1 ZeroDivide (AbstractException) >> _signalWith: @6 line 25

2 ZeroDivide (AbstractException) >> signal      @2 line 47

3 SmallInteger (Number) >> _errorDivideByZero   @6 line 7

==> 4 SmallInteger >> /                             @6 line 7

5 [] in  Executed Code                          @2 line 1

6 Array (Collection) >> do:                     @5 line 10

7 Executed Code                                 @2 line 1

8 UndefinedObject (GsNMethod class) >> _gsReturnToC @1 line 1

topaz 1> down

3 SmallInteger (Number) >> _errorDivideByZero   @6 line 7

    receiver 1

topaz 1> where

1 ZeroDivide (AbstractException) >> _signalWith: @6 line 25

2 ZeroDivide (AbstractException) >> signal      @2 line 47

==> 3 SmallInteger (Number) >> _errorDivideByZero   @6 line 7

4 SmallInteger >> /                             @6 line 7

5 [] in  Executed Code                          @2 line 1

6 Array (Collection) >> do:                     @5 line 10

7 Executed Code                                 @2 line 1

8 UndefinedObject (GsNMethod class) >> _gsReturnToC @1 line 1

edit aSubCommandOrSelector [aSelector]

Allows you to edit GemStone Smalltalk source code. You can create or modify methods or blocks of code to be executed. You can also edit the text of the last run, printit, doit, method:, or classmethod: command.

Before you can use this command, you must first establish the name of the host operating system editor you wish to use. You can do this by setting the host environment variable EDITOR or by invoking the Topaz set editorname command interactively or in your Topaz initialization file.

Do not use the edit command for batch processing. Instead, use the method: and classmethod: commands to create methods in batch processes, and the run, printit or doit commands to execute blocks of code in batch.

If you supply any parameter to edit, other than one of its subcommands, Topaz assumes that you are naming an existing instance method to be edited.

Creating or Modifying Blocks of GemStone Smalltalk Code

edit last
Allows you to edit the text of the last run, printit, doit, method:, or classmethod: command. (You can inspect that text before you edit by issuing the Topaz command object LastText.) Topaz opens, as a subprocess, the editor that you’ve selected. When you exit the editor, Topaz saves the edited text in its temporary file and asks you whether you’d like to compile and execute the altered code. If you tell Topaz to execute the code, it effectively reissues your run or printit command with the new text.

edit new text
Allows you to create a new block of GemStone Smalltalk code for compilation and execution. This is similar to edit last, but with a new text object.

Creating or Modifying GemStone Smalltalk Methods

edit new
If you type edit new with no additional keywords, Topaz assumes that you want to create a new instance method for the current class.

edit new method
Allows you to create a new instance method for the current class and category. Before you can use this command, you must first use set class to select the current class. If you haven’t yet selected a current category, the new method is inserted in the default category, “as yet unspecified.”

edit new classmethod
Allows you to create a new class method for the current class and category. Before you can use this command, you must first use set class to select the current class. If you haven’t yet selected a current category, the new method is inserted in the default category, “as yet unspecified.”

edit selectorSpec

edit method: selectorSpec
Allows you to edit the source code of an existing instance method. Before you can use this command, you must first use set class to select the current class. The category of the method you edit is automatically selected as the current category. For example:

topaz 1> set class Animal

topaz 1> edit habitat

edits the instance method in class Animal whose selector is habitat.

edit classmethod: selectorSpec
Allows you to edit the source code of an existing class method. Before you can use this command, you must first use set class to select the current class. The category of the method you edit is automatically selected as the current category.

env [anInteger]

Sets the compilation environmentId used for method compilations, lookups of senders and implementors, and run, printit, etc. anInteger must be between 0 and 255 and is 0 by default. Values other than 0 are invoked in additional execution environments and are used in specialized applications.

With no arguments, prints the current compilation environmentId.

The compilation environment may also be set using the commend set compile_env:.

exit[aSmallInt | anObjectSpec]

Leaves Topaz, returning to the parent process or operating system. If you are still logged in to GemStone when you type exit, this aborts your transactions and logs out all active sessions.

You can include an argument (a SmallInteger, or an object specification that resolves to a SmallInteger) to specify an explicit exitStatus for the Topaz process. Only 8 bits of the integer are returned. To get valid return values, the argument should always resolve to a value in the range 0..255.To use an object specification, including errorcount, you must be logged in when the exit command is executed.

If you do not specify an argument, the exitStatus will be either 0 (no errors occurred during Topaz execution) or 1 (there was a GCI error or the Topaz errorCount was nonzero).

For example:

topaz 1> exec ( 42 - 3) %

topaz 1> exit **

Logging out session 1.

--- 08/11/2020 14:11:53.619 PDT Logging out

unix> echo $? 

39

exit is ignored when reading a file using input, when stdin is a tty. If topaz stdin is redirected to a file and the file does not end with a QUIT or EXIT, topaz considers EOF on stdin to be an error, and will result in a non-zero topaz exit status.

This command cannot be abbreviated.

To exit from topaz with an exit status directly from Smalltalk code, you can use the ExitClientError class. For example,

topaz 1> run

ExitClientError 

	signal: 'Disallowed Operation' 

	status: 34 

%

ERROR 3004 , a ExitClientError occurred (error 3004), , Disallowed Operation (ExitClientError)

Logging out session 1.

--- 08/11/2020 15:21:17.137 PDT Logging out

expectbug bugNumber value resultSpec [ integer ] | error errCategory errNumCls [ resultSpec [ resultSpec ]..]

Specifies that the result of the following execution results in the specified answer (either a value or an error). If the expected result occurs, Topaz prints a confirmation message and increments the error count.

The expectbug command is intended for use in self-checking scripts to verify the existence of a known error. Only one expectbug command (at most) can be in effect during a given execution. Topaz honors the last expectbug command issued before the execution occurs. Expectbug can be used in conjunction with the expecterror and expectvalue commands—an expectbug command does not count against the maximum of five such expecterror and expectvalue commands permitted.

bugNumber is a parameter identifying the bug or behavior you expect to see. In most cases this would be a number, but it can equally well be a character string. (If it contains white space, enclose the string in single quotes.) The parameter is included in the confirmation message.

resultSpec is specified as in the expectvalue command (described here).

errorCategory and errNumCls
are specified as in the expecterror command (described here).

For example, suppose you know that the ‘*’ operator has been reimplemented in a way that returns the erroneous answer ‘5’ for the expression ‘2 * 3’. You can use the expectbug command in a script to verify that the bug is present:

topaz 1> expectbug 123 value 5

topaz 1> printit

2 * 3

%

5

BUG EXPECTED: BUG NUMBER 123

If the expected bug does not occur, Topaz checks for an expecterror or expectvalue command that matches the answer received. If it finds a match, Topaz displays a “FIXED BUG” message. If not, the error is reported in the same way the expecterror or expectvalue command would report it (“ERROR: WRONG VALUE” for example). If no expecterror or expectvalue commands are in effect, execution proceeds without comment.

expecterror anErrorCategory anErrorNumCls [anErrorArg [anErrorArg] ...]

Indicates that the next compilation or execution is expected to result in the specified error. If the expected result occurs, Topaz reports the error in the conventional manner but does not increment its error count and allows execution to proceed without further action or comment.

If the execution returns a result other than the expected error (including unexpected success), Topaz increments the error count and invokes any iferror actions that have been established.

Up to five expecterror or expectvalue commands may precede an execution command. If the result of the execution satisfies any one of them, the error count variable is not incremented. This mechanism allows you to build self-checking scripts to check for errors that can’t be caught with GemStone Smalltalk exception handlers.

Expecterror must be reset for each command; it is only checked against a single return value. Expecterror is normally used before the commands run, printit, doit, method:, classmethod:, commit, and send.You must also use it before executing continue after a breakpoint.

anErrorCategory must be a Topaz object specification that evaluates to the object identifier of an error category; normally, GemStoneError.

anErrorNumCls must be a Topaz object specification that evaluates either to a SmallInteger legacy error number, or to the object identifier of a subclass of Abstract Exception.

All Topaz object specification formats (as described in Specifying Objects) are legal in expecterror commands.

The following example shows an expecterror command followed by the expected error. Note that although the error is reported, the error count is not incremented.

topaz 1> errorcount

0

topaz 1> expecterror GemStoneError MessageNotUnderstood

topaz 1> printit

1 x

%

ERROR 2010 , a MessageNotUnderstood occurred (error 2010), a

SmallInteger does not understand  #'x' (MessageNotUnderstood)

topaz 1> errorcount

0

If execution returns unanticipated results, Topaz prints a message (in this example, “ERROR: WRONG CLASS of Exception”), then invokes the actions established by the iferror command (in this example, a stack dump) and bumps the error count:

topaz 1> errorcount

0

topaz 1> iferror where

topaz 1> expecterror GemStoneError MessageNotUnderstood

topaz 1> printit

1 / 0

%

ERROR 2026 , a ZeroDivide occurred (error 2026),

reason:numErrIntDivisionByZero, attempt to divide 1 by zero (ZeroDivide)

ERROR: WRONG CLASS of Exception, does not match expected class

topaz > exec iferr 1 : where 

==> 1 ZeroDivide (AbstractException) >> _signalWith: @5 line 25

2 ZeroDivide (AbstractException) >> signal      @2 line 47

3 SmallInteger (Number) >> _errorDivideByZero   @6 line 7

4 SmallInteger >> /                             @6 line 7

5 Executed Code                                 @2 line 1

6 UndefinedObject (GsNMethod class) >> _gsReturnToC @1 line 1

topaz 1> errorcount

1

Further arguments to EXPECTERROR

In addition to the error category and class, you may optionally specify additional arguments. The expecterror argument values are tested against the argument values returned with the error. If one or more of the argument values do not match, errorcount is incremented. .

In additional to standard object specification formats, you may use additional formats to specify instances of classes as error arguments:

%className An instance of the class className.

/className An instance of the class className or an instance of any of its subclasses. (In other words, an instance of a ‘kind of’ className.)

If anErrorArg is specified as a String or Symbol (enclosed in single quotes and/or with a leading #), then it will be regarded as matching if the result if the two are equal (=).

Otherwise, Topaz regards it as matching the result if the two are identical (==).

You may omit arguments, which will not count as an error. If you specify more expecterror arguments than the actual error returns, then errorcount will be incremented. To match any error argument, use /Object.

For example:

topaz 1> errorcount

2

topaz 1> expecterror GemStoneError OffsetError %Array 3 6

topaz 1> run

   (Array new: 3) at: 6

%

ERROR 2003 , a OffsetError occurred (error 2003),

reason:objErrBadOffsetIncomplete, max:3 actual:6 (OffsetError)

topaz 1> errorcount

2

expectvalue anObjectSpec [anInt]

Indicates that the result of the following compilation or execution is expected to be a specified value, denoted by anObjectSpec. If it is not, the error count is incremented. Up to five expectvalue or expecterror commands may precede an execution command. If the result of the execution satisfies any one of them, the error count variable is not incremented.

Expectvalue must be reset for each command; it is only checked against a single return value. Expectvalue is normally used before the commands run, printit, doit, method:, classmethod:, commit, and send. You must also use it before executing continue after a breakpoint.

All Topaz object specification formats (as described in Specifying Objects”) are legal in expectvalue commands. In addition, this command takes further formats that allow you to specify instances of classes:

%className
An instance of the class className.

%@OOPOfClass
An instance of the class that has the OOP OOPOfClass.

/className
An instance of the class className or an instance of any of its subclasses. (In other words, an instance of a ‘kind of’ className.)

/@OOPOfClass
An instance of the class that has the OOP OOPOfClass, or an instance of any of its subclasses.

If anObjectSpec is specified as a String or Symbol (enclosed in single quotes and/or with a leading #), then it will be regarded as matching if the result if the two are equal (=).

Otherwise, Topaz regards it as matching the result if the two are identical (==).

If the anInt argument is present, the result of sending the method size to the result of the following execution must be the integer anInt.

The commit command has an internal result of true for success and false for failure. All other Topaz commands have an internal result of true for success and @0 for failure.

The following example uses expectvalue to test that the result of the printit command is a SmallInteger. The expected result is returned, so execution proceeds without comment:

topaz 1> expectvalue %SmallInteger

topaz 1> printit

2 * 5

%

10

If execution returns unanticipated results, Topaz prints a message (in this example, “ERROR: WRONG VALUE”), then invokes the actions established by the iferror command (in this example, a stack dump) and bumps the error count:

topaz 1> errorcount

0

topaz 1> iferror stack

topaz 1> expectvalue %SmallInteger

topaz 1> printit

2 * 5.5

%

1.1000000000000000E+01

ERROR: WRONG VALUENow executing the following command saved from "iferror":

	stack

Stack is not active

topaz 1> errorcount

1

fileformat 8bit | utf8

This command controls the interpretation of Character data for input and fileout, to allow strings containing Characters with codepoints over 255 to be input and output.

This is meaningful if you are using text that contains any Characters with values over 127. Characters 127 and below are 7-bit, and the code points are the same as the UTF-8 encoded values, and so are not affected by this setting.

Characters in the range of 128-255 can be read and written with their 8-bit codepoints, or read and written encoded as UTF-8; these produce different results. So if such text is written as UTF8, it must be read in with a fileformat of UTF8 in order to get correct results, and similarly both written and read as 8-bit in order to recreate the same text.

To avoid misinterpretation of fileouts, the fileout command writes a fileformat command at the start of the fileout. A fileformat command within a file only has effect within that file and any nested files.

Note that this setting does not apply to files produced by the output command. output push, etc. write files in UTF-8 format, regardless of the setting for fileformat.

The following options are supported:

fileout [command] clsOrMethod [tofile: filename
[format: fileformat]]

Writes out class and method information in a format that can be fed back into Topaz with the input command. Subcommands are used to specify whether to file out the entire class, or specific method or methods. If none of the defined subcommands follow the fileout, then the next word is assumed to be a selector for an instance method on the current class.

By default, the fileout command outputs the fileout text to stdout. To direct this to a file, follow the specification of what to fileout with the tofile: keyword. For example:

topaz 1> fileout class: Object toFile: object.gs

If you specify a host environment name such as $HOME/foo.bar as the output file, Topaz expands that name to the full filename. If the output file does not include an explicit path specification, Topaz writes to the named file in the directory where you started Topaz.

When using the tofile: keyword, you may also optionally specify the format: keyword. This must be either 8bit or UTF8, and specifies whether the file is written out in bytes, or encoded in UTF-8. This overrides the current topaz setting for fileformat.

All fileout output generated from the fileout command include commands setting the fileformat and set sourcestringclass, based on the current settings or the format: command.

fileout class: [aClassName]
Writes out the class definition and all the method categories and their methods. To write out the definition of the current class, type:

topaz 1> fileout class: ^

If you omit the class name parameter, the current class is written out.

The class that you file out becomes the current class for subsequent Topaz commands.

fileout category: aCategoryName
Writes out all the methods contained in the named category for the current class.

fileout classcategory: aCategoryName
Writes out all the class methods contained in the named category for the current class.

fileout classmethod: selectorSpec
Writes out the specified class method (as defined for the current class). The category of that method will automatically be selected as the current category.

fileout method: selectorSpec
Writes out the specified method (as defined for the current class). The category of that method will automatically be selected as the current category.

fileout selectorSpec
Writes out the specified method (as defined for the current class). You may use this form of the fileout command (that is, you may omit the method: keyword) only if the selector that you specify does not conflict with one of the other fileout keywords. For example, to file out a method named category:, you would need to explicitly include the method: keyword.

fr_1 [anInteger]

Similar to the frame command (described here), but for large numbers (more than eight) of method and temporary variables, these are displayed one per line rather than in four columns.

This command cannot be abbreviated.

fr_cls [anInteger]

Similar to the frame command (described here), but also displays OOPs of classes along with class names in the specified stack frames.

This command cannot be abbreviated.

frame [anInteger]

Moves the active frame to the frame specified by anInteger, within the current stack, and displays the frame selected as a result. The display includes parameters and temporaries.

If no argument is supplied, displays the current frame.

See also stack scope here, the up command on here and the down command here.

For example:

topaz 1> printit

{ 1 . 2} do: [:x | x / 0 ]

%

ERROR 2026 , a ZeroDivide occurred (error 2026),

reason:numErrIntDivisionByZero, An attempt was made to divide 1 by zero. (ZeroDivide)

topaz 1> where

==> 1 ZeroDivide (AbstractException) >> _signalWith: @6 line 25

2 ZeroDivide (AbstractException) >> signal      @2 line 47

3 SmallInteger (Number) >> _errorDivideByZero   @6 line 7

4 SmallInteger >> /                             @6 line 7

5 [] in  Executed Code                          @2 line 1

6 Array (Collection) >> do:                     @5 line 10

7 Executed Code                                 @2 line 1

8 UndefinedObject (GsNMethod class) >> _gsReturnToC @1 line 1

topaz 1> frame 4

4 SmallInteger >> /                             @6 line 7

    receiver 1

    aNumber 0

topaz 1> where

1 ZeroDivide (AbstractException) >> _signalWith: @5 line 25

2 ZeroDivide (AbstractException) >> signal      @2 line 47

3 SmallInteger (Number) >> _errorDivideByZero   @6 line 7

==> 4 SmallInteger >> /                             @6 line 7

5 [] in  Executed Code                          @2 line 1

6 Array (Collection) >> do:                     @5 line 10

7 Executed Code                                 @2 line 1

8 UndefinedObject (GsNMethod class) >> _gsReturnToC @1 line 1

topaz 1> frame 7

7 Executed Code                                 @2 line 1

    receiver nil

gcitrace aFileName

Turns GCI tracing on. Subsequent GCI calls are logged to the file aFileName. If aFileName is '' (empty string), then turns GCI tracing off.

This command cannot be abbreviated.

help [aTopicName]

Invokes a hierarchically-organized help facility that can provide information about all Topaz commands. Enter ? at a help prompt for a list of topics available at that level of the hierarchy. Help topics can be abbreviated to uniqueness.

To display help text for fileout:

topaz 1> help fileout

To display help text for last:

topaz 1> help edit last

Press Return at a help prompt to go up a level in the hierarchy until you exit the help facility.

hierarchy [aClassName] [environmentId]

Prints the class hierarchy up to Object for the specified class, in the specified environmentId, or the current environmentId if no environmentId is specified.

If you do not specify a class, Topaz prints the hierarchy for the current class.

Example

topaz 1> hierarchy SmallFraction

Object

  Magnitude

    Number

      AbstractFraction

        SmallFraction

See Also

SUBHIERARCHY

history [anInteger]

Displays the specified number of recently executed commands, as listed in the Topaz line editor history. Has no effect if the line editor is not enabled. (Not available on Windows.)

The set history command (here) establishes the maximum number of command lines to retain in the Topaz line editor history.

Example

topaz 1> history

0 login

1 run

2 2 / 0

3 %

4 stk

5 display oops

6 stk

7 frame 3

8 history

iferr bufferNumber [aTopazCommandLine]

The iferr command works whenever an error is reported and the ErrorCount variable is incremented.

This command saves aTopazCommandLine in the post-error buffer specified by bufferNumber as an unparsed Topaz command line. There are 10 buffers; bufferNumber must be an integer between 1 and 10, inclusive.

The post-error buffer commands apply under any of the following conditions:

• an error occurs (other than one matching an expecterror command and other than one during parsing of the iferr command)
• a result fails to match an expectvalue command
• a result matches an expectbug command

Whenever any of these conditions arise, any non-empty post-error buffers are executed. Execution starts with buffer 1, and proceeds to buffer 10, executing each non-empty post-error buffer in order. This allows you to execute a number of handling commands. For example:

topaz 1> iferr 1 where

topaz 1> iferr 2 allstacks

topaz 1> iferr 3 topazwaitfordebug

If an error occurs while executing one of post-error buffers, execution proceeds to the next non-empty post-error buffer. Error and result checking implied by display resultcheck, display errorcheck, expectvalue, etc., are not performed while executing from post-error buffers.

If a post-error buffer contains a command that would terminate the topaz process, then later buffers will have no effect. If a post-error buffer contains a command that would terminate the session, execution later buffers will be attempted but they will not have a session, unless one of the contains “login”.

To remove the contents of a specific post-error buffer, enter iferr bufferNumber without a final argument. The command iferr_clear will clear all buffers.

The iferr_list command will display the contents of all post-error buffers.

The following examples demonstrate how to use expecterror to test the kind of error that is returned from Smalltalk code execution, so you can conditionally avoid triggering the iferr command.

The following reports an error, but does not perform the iferr operations:

topaz 1> iferr 1 stk

topaz 1> expecterror GemStoneError MessageNotUnderstood

topaz 1> exec 2 foo %

ERROR 2010 , a MessageNotUnderstood occurred (error 2010), a SmallInteger does not understand  #'foo'

topaz 1>

But in the following, since divide-by-zero is an unexpected error, does print the stack:

topaz 1> iferr 1 stk

topaz 1> expecterror GemStoneError MessageNotUnderstood

topaz 1> exec 2 / 0 %

ERROR 2026 , a ZeroDivide occurred (error 2026), reason:numErrIntDivisionByZero, attempt to divide 2 by zero

ERROR: WRONG CLASS of Exception, does not match expected class

topaz > exec iferr 1 : stk 

==> 1 ZeroDivide (AbstractException) >> _signalWith: @5 line 25

2 ZeroDivide (AbstractException) >> signal      @2 line 47

3 SmallInteger (Number) >> _errorDivideByZero   @6 line 7

4 SmallInteger >> /                             @6 line 7

5 Executed Code                                 @2 line 1

6 GsNMethod class >> _gsReturnToC               @1 line 11

This command cannot be abbreviated.

iferror [aTopazCommandLine]

The iferror command saves aTopazCommandLine to the post-error command buffer 1, or when used without an argument, clearing buffer 1.

The command:

topaz 1> iferror stack

has the same effect as:

topaz 1> iferr 1 stack

For details iferr and the post-error command buffers, see here.

This command cannot be abbreviated.

implementors selectorSpec

Displays a list of all classes that implement the given selectorSpec (either a String or a Symbol). For example:

topaz 1> implementors asByteArray

Collection >> asByteArray

MultiByteString >> asByteArray

String >> asByteArray

This command is equivalent to the following:

topaz 1> doit

ClassOrganizer new implementorsOfReport: aString 

%

This command may use significant temporary object memory. Depending on your repository, you may need to increase the value of the GEM_TEMPOBJ_CACHE_SIZE configuration parameter beyond its default. For details about GemStone configuration parameters, see the System Administration Guide.

input [aFileName | pop]

Controls the source from which Topaz reads input. Normally Topaz reads input from standard input (stdin). This command causes Topaz to take input from a file or device of your choice.

If you specify a host environment name such as $HOME/foo.bar as the input file, Topaz expands that name to the full filename. If you don’t provide an explicit path specification, Topaz looks for the named input file in the directory where you started Topaz.

When input commands are echoed, as they are by default, the topaz prompt indicates that the given command is located in a particular level of nested file by including a + (plus sign) for each level of file input nesting.

For example, assuming aFile contains a series of commands which include import nestedFile:

topaz 1> input aFile

topaz 1 +> <commands in aFile>

topaz 1 +> input nestedFile

topaz 1 ++> <commands in nestedFile>

topaz 1 +> <further commands in aFile>

input aFileName
Reads input from the specified file. This pushes the current input file onto a stack and starts Topaz reading from the given file. There is a limit of 20 nested input aFileName commands. If you exceed the limit, an error is displayed, and execution continues in the current file.

input pop
Pops the current input file from the stack of input files and resumes reading from the previous file. If there is no previous file, or the previous file cannot be reopened, Topaz once again takes its input from standard input.

inspect [anObjectSpec]

Sends the message describe to the designated object.

This command is equivalent to the following

topaz 1> send anObjectSpec describe%

level anIntegerLevel

Sets the Topaz display level; that is, this command tells Topaz how much information to include in the result display. A level of 1 (the default) means that the first level of instance variables within a result object will be displayed. Similarly, a level of 2 means that the variables within those variables will be displayed. Setting the level to 0 inhibits the display of objects (though object headers will still be displayed if you specify display oops). The maximum display level is 10000.

Note the following:

• The RUN command (page 147) displays results using the current display level, as set by the level command.
• The DOIT command (page 74) always displays results at level 0, regardless of the current display level.
• The PRINTIT command (page 140) always displays results at level 1, regardless of the current display level.

limit [bytes | oops | lev1bytes] anInteger

Tells Topaz how much of any individual object to display in GemStone Smalltalk results. The display can be limited by OOPs, to control the number of objects displayed (for example, the number of elements in a collection). It can also be limited by bytes, to control the number of bytes of byte objects, such as Strings, that are displayed.

For example, limit bytes 100 would tell Topaz to only display 100 bytes of any String (or other byte object).

A limit of 0 tells Topaz to not limit the size of the output. This is the default.

If the amount that would be displayed is limited by limit bytes setting, the display indicates missing text using ...(NN more bytes). If the number of objects is limited by a limit oops setting, then it prints ... NN more instVars.

Browsing Dictionaries and Classes

topaz 1> list classesIn: UserGlobals

topaz 1> list classes cert

GsX509Certificate

GsX509CertificateChain

topaz 1> set class Array

topaz 1> list sel at:p

    at:put:

    _at:put:

    _basicAt:put:

Listing Methods

list with no arguments lists the source code of the active method context. See Chapter 2, “Debugging Your GemStone Smalltalk Code”.

list @anObjectSpec
Lists the source code of the GsNMethod or ExecBlock with the specified objectId. That method, or the block’s home method, becomes the default method for subsequent list or disassem commands.

topaz 1> set class String

topaz 1> list linenumbers method: includesValue:

  1  includesValue: aCharacter

  2  

  3  "Returns true if the receiver contains aCharacter, false otherwise.

  4   The search is case-sensitive."

  5  

  6  <primitive: 94>

  7  aCharacter _validateClass: AbstractCharacter .

  8  ^ self includesValue: aCharacter asCharacter .

Listing Step Points

topaz 1> set class Stringtopaz 1> list steps method: includesValue:

	includesValue: aCharacter

 * ^1                                                *******

	"Returns true if the receiver contains aCharacter, false

	otherwise. The search is case-sensitive."

	<primitive: 94>

	aCharacter _validateClass: AbstractCharacter .

	 *            ^2                                     *******

	 ^ self includesValue: aCharacter asCharacter .

	 * ^5     ^4                        ^3               *******

Listing Breakpoints

In addition to list breaks, you can use the break list command to list all currently set breakpoints. For more information about using breakpoints, see Chapter 2, “Debugging Your GemStone Smalltalk Code”.

topaz 1> list breaks method: <

	< aCharCollection

	 "Returns true if the receiver collates before the

	argument. Returns false otherwise.

	The comparison is case-insensitive unless the receiver

	and argument are equal ignoring case, in which case

	 upper case letters collate before lower case letters.

	 The default behavior for SortedCollections and for

	the sortAscending method in UnorderedCollection is

	consistent with this method, and collates as follows:  

	#( 'c' 'MM' 'Mm' 'mb' 'mM' 'mm' 'x' ) asSortedCollection 

	 yields the following sort order:

	'c' 'mb' 'MM' 'Mm' 'mM' 'mm' 'x'

	"	

	<primitive: 28>

	aCharCollection _stringCharSize bitAnd: 16r7) ~~ 0 ifTrue:[

     ^ (DoubleByteString withAll: self) < aCharCollection .

   ].

	aCharCollection _validateClass: CharacterCollection .

	*                 ^2                                *******

	^ aCharCollection > self

listw

l

For the method implied by the current stack frame, limit the list to the number of source lines defined by the set listwindow command. The list is centered around the current insertion point for the frame.

For example:

topaz 1> stk

==> 1 ZeroDivide (AbstractException) >> _signalWith: @5 line 25

2 ZeroDivide (AbstractException) >> signal      @2 line 47

3 SmallInteger (Number) >> _errorDivideByZero   @6 line 7

4 SmallInteger >> /                             @6 line 7

5 [] in  Executed Code                          @2 line 1

6 Array (Collection) >> do:                     @5 line 10

7 Executed Code                                 @2 line 1

8 UndefinedObject (GsNMethod class) >> _gsReturnToC @1 line 1

topaz 1> frame 4

4 SmallInteger >> /                             @6 line 7

    receiver 1

    aNumber 0

topaz 1> listw

   / aNumber

   "Returns the result of dividing the receiver by aNumber."

   <primitive: 10>

   (aNumber _isInteger) ifTrue:[ 

     (aNumber == 0) ifTrue: [^ self _errorDivideByZero].

 *                                  ^6                                *******

     ^ Fraction numerator: self denominator: aNumber 

   ].

   ^ super / aNumber

The listw command cannot be abbreviated, other than by l.

literals anObject

Reports all methods in which anObject is contained as a literal reference. anObject is typically a String, Symbol, or Number.

Literals is equivalent to:

topaz 1> exec ClassOrganizer new literalsReport: anObject %

for example,

topaz 1> Literals TimeZone

TimeZone >> =

TimeZone class >> default:

TimeZone class >> fromLinux

TimeZone class >> fromSolaris

loadua aFileName

Loads the application user action library specified by aFileName. This command must be used before login.

This command cannot be abbreviated.

User action libraries contained user-defined C functions to be called from GemStone Smalltalk. See the GemBuilder for C manual for information about dynamically loading user action libraries.

lookup (meth | method | cmeth | cmethod) selector [envId]

lookup className [class] [(implementingclass)] >> selector [envId]

The lookup command to search upwards through the hierarchy of superclasses to locate the implementation of a given method selector. If no envId is specified, the current compilation environment env is used.

There are two ways to specify the class, selector, and if it is a class or instance method:

• using the set command to specify the class, and either method or classmethod to indicate a class or instance method;
• using className [class] >> to identify this information

All arguments to lookup are case sensitive.

The selector argument is string or symbol with the full method selector. The following are all acceptable selector specifications:

lookup hash

lookup 'hash'

lookup #hash

lookup #'hash'

Or you may use syntax such as:

lookup SmallInteger >> +

lookup String class >> new

The lookup command also accepts the text generated in stack frame, so you can copy and paste from a stack frame to lookup a method.

lookup String (SequenceableCollection) >> at:ifAbsent:

Using this syntax, implementingClass is used as the starting point for lookup, and the class argument is ignored.

Related commands include senders and implementors.

Finding and Listing Methods

lookup classmethod selector
Lists the source code of the specified class method for the current class, or searching the superclasses, the first superclass that implements this method. (May be abbreviated as lookup cmeth.)

lookup method selector
Lists the source code of the specified instance method for the current class, or searching the superclasses, the first superclass that implements this method. (May be abbreviated as lookup meth.)

topaz 1> set class Symbol

topaz 1> lookup meth match:

category: 'Comparing'

method: CharacterCollection

match: prefix

"Returns true if the argument prefix is a prefix of the

 receiver, and false if not.  The comparison is 

 case-sensitive."

self size == 0 ifTrue: [ ^ prefix size == 0 ].

^ self at: 1 equals: prefix

% 

lookup className >> selector
Lists the source code of the specified instance method for the given class, or searching its superclasses, the first superclass that implements this method. (The className argument may not be meth, method, cmeth, or classmethod.)

lookup className class >> selector
Lists the source code of the specified class method for the class className, or searching its superclasses, the first superclass that implements this method. (The className argument may not be meth, method, cmeth, or classmethod.)

lookup className (implementingClass) >> selector
Lists the source code of the specified instance method for the class implementingClass, or searching its superclasses, the first superclass that implements this method. (The className argument may not be meth, method, cmeth, or classmethod.)

lookup className (implementingClass) class >> selector
Lists the source code of the specified class method for the class implementingClass, or searching its superclasses, the first superclass that implements this method. (The className argument may not be meth, method, cmeth, or classmethod.)

Pasting from stack frames

When you are stepping through code or examining the call stack for an error, topaz displays stack frames containing the individual message sends. You can cut and paste the printed methods into the lookup command, to lookup the source code that was executed.

For example:

topaz 1> run

1 / 0

%

ERROR 2026 , a ZeroDivide occurred (error 2026),

reason:numErrIntDivisionByZero, attempt to divide 1 by zero (ZeroDivide)

topaz 1> where

==> 1 ZeroDivide (AbstractException) >> _signalWith: @5 line 25

2 ZeroDivide (AbstractException) >> signal      @2 line 47

3 SmallInteger (Number) >> _errorDivideByZero   @6 line 7

4 SmallInteger >> /                             @6 line 7

5 Executed Code                                 @2 line 1

6 UndefinedObject (GsNMethod class) >> _gsReturnToC @1 line 1

select the section of the line after the frame number and before the step point, and use that as an argument to lookup:

topaz 1> lookup SmallInteger (Number) >> _errorDivideByZero  

    category: 'Error Handling'

method: Number

_errorDivideByZero

"Generates a divide by 0 error."

^ ZeroDivide new _number: 2026 ; reason: 'numErrIntDivisionByZero'; 

    dividend: self ;

    signal

%

method[: aClassName]

Compiles an instance method for the class whose name is given as a parameter. The class of the method you compile will automatically be selected as the current class. If you don’t supply a class name, the method is compiled for the current class, as defined by the most recent set class:, list categoriesin:, method:, classmethod:, removeAllMethods, removeAllClassMethods, or fileout class: command.

Text of the method should follow this command on subsequent lines. The method text is terminated by the first line that contains a % character as the first character in the line. For example:

topaz 1> method: Animal

habitat

	^habitat

%

Topaz sends the method’s text to GemStone for compilation and inclusion in the current category of the specified class. If you haven’t yet selected a current category, the new method is inserted in the default category, “as yet unspecified.”

obj1anObjectSpec

obj2 anObjectSpec

Equivalent to the object command, but with the following difference: results are displayed at level 1 (if obj1) or level 2 (if obj2), with offsets of instance variables shown as one-based. After execution, previous settings for level and omit|display zerobased are restored.

These commands cannot be abbreviated.

obj1z anObjectSpec

obj2z anObjectSpec

Equivalent to the object command, but with the following difference: results are displayed at level 1 (if obj1) or level 2 (if obj2), with offsets of instance variables shown as zero-based. After execution, previous settings for level and omit|display zerobased are restored.

These commands cannot be abbreviated.

object anObjectSpec [at: anIndex [put: anObjectSpec]]

Provides structural access to GemStone objects, allowing you to peek and poke at objects without sending messages. The first anObjectSpec argument is an object specification in one of the Topaz object specification formats. All formats described in Specifying Objects are legal in object commands.

You can use local variables (created with the define command) in object commands. The local definition of a symbol always overrides any definition of the symbol in GemStone. For example, if you defined the local variable thirdvar, and your UserGlobals dictionary also defined a GemStone symbol named thirdvar, the definition of that GemStone symbol would be ignored in object commands.

object anObjectSpec at:anIndex
Returns the value of an instance variable within the designated object at the specified integer offset. You can string together at: parameters after object to descend as far as you like into the object of interest.

As far as object at: is concerned, named and indexed instance variables are both numbered, and indexed instance variables follow named instance variables when an object has both. That is, if an indexable object also had three named instance variables, the first indexed field would be addressed with object theIdxObj at:4.

Unordered collections (NSCs) are also considered indexable via object at:.

object anObjectSpec at: anIndex put: anotherObjectSpec
Lets you store values into instance variables. This command stores the second anObjectSpec object into the first anObjectSpec object at the specified integer offset.

You cannot store into an NSC with object at: put:, although you can scrutinize its elements with object at:.

CAUTION
Because object at: put: bypasses all the protections built into the GemStone Smalltalk kernel class protocol, you risk corrupting your repository whenever you permanently modify objects with this command.

The following example shows how you could use object at: put: to store a new String in MyAnimal’s habitat instance variable:

topaz 1> object MyAnimal at: 3 put: 'pond'

an Animal

	name            nil

	favoriteFood    nil

	habitat        pond

Like object at:, the object at: put: command can take a long sequence of parameters. For example:

topaz 1> object MyAnimal at: 3 at: 1 put: $l

liver

This example stores the character “l” into the first instance variable of MyAnimal’s third instance variable.

With this command you can store Characters or SmallIntegers in the range from 0—255 (inclusive) into a byte object. You can also store other byte objects such as Strings. For example:

topaz 1> object 'this' at: 5 put: ' and that'

this and that

The object at: put: command behaves differently for objects with byte-array and pointer-array implementations. You may store the following kinds of objects into byte-array type objects:

Character. This stores the character ‘9’:

topaz 1> object '123' at: 1 put: $9

SmallInteger. This stores a byte with the value 48:

topaz 1> object '123' at: 1 put: 48

Byte arrays. This stores ’b’ and ’c’ at offsets 2 and 3:

topaz 1> object '1234' at: 2 put: 'bc'

omit aDisplayFeature

The display and omit commands control the display of Gemstone Smalltalk objects and other features related to output.

The display command turns on these display attributes, and the omit command turns them off.;

For more details on these attributes and the default values, see DISPLAY.

output [push | append | pushnew | pop] aFileName [only]

Controls where Topaz output is sent. Normally Topaz sends output to standard output (stdout): generally the topaz console. This command redirects all Topaz output to a file (or device) of your choice.

If you specify a host environment name such as $HOME/foo.bar as the output file, Topaz expands that name to the full filename. If you don’t provide an explicit path specification, Topaz output is sent to the named file in the directory where you started Topaz.

Output is written with UTF-8 encoding, regardless of the current state of FILEFORMAT.

As the command names push and pop imply, Topaz can maintain a stack of up to 20 output files, with current interactions captured in each file.

output aFileName

output push aFileName
Sends output to the specified file, as well as echoing to stdout. If the file you name doesn’t yet exist, Topaz will create it. If you name an existing file, Topaz overwrites it.

To append output to an existing file, precede the file name with an ampersand (&), or use append instead of push.

If you use output without a subsequent push, pushnew, append, or pop, then push is assumed and the following token is used as the filename.

The command push must be typed in full, it cannot be abbreviated.

output append aFileName
Sends output to the specified file, as well as echoing to stdout. If the file you name doesn’t yet exist, Topaz will create it. If you name an existing file, Topaz will append to it. This behavior is the same as output push &aFileName.

The command append must be typed in full, it cannot be abbreviated.

output pushnew aFileName
Sends output to the specified file, as well as echoing to stdout. If the file you name doesn’t exist, Topaz will create it. If you name an existing file, Topaz will create a new file. For a filenames of the form foo.out, the new filename will be foo_N.out, where where N is some integer between 1 and 99 (inclusive), and where foo_N.out did not previously exist. If more than 1000 versions of the file exist, the oldest version will be overwritten.

The command push must be typed in full, it cannot be abbreviated.

pausefordebug [errorNumber]

Provided to assist internal debugging of a session.

With no argument, this command has no effect.

This command cannot be abbreviated.

pkglookup (meth | method| cmeth| cmethod) selectorSpec

pkglookup className [class] selectorSpec

Similar to the lookup command, but with one key exception: pkglookup looks first in GsPackagePolicy state, then in the persistent method dictionaries for each class up the hierarchy. The pkglookup command does not look at transient (session method) dictionaries.

For details, see the description of the lookup command here.

pollforsignal

Provided to assist debugging signal handling.

This command causes topaz to wait for out-of-band activity from the Gem processing, using GciPollForSignal. It can be interrupted by control-C.

quit [aSmallInt | anObjectSpec]

Leaves Topaz, returning to the operating system. If you are still logged in to GemStone when you type quit, this aborts your transaction and logs out all active sessions.

You can include an argument (a SmallInteger, or an object specification that resolves to a SmallInteger) to specify an explicit exitStatus for the Topaz process. Only 8 bits of the integer are returned. To get valid return values, the argument should always resolve to a value in the range 0..255. To use an object specification, including errorcount, you must be logged in when the quit command is executed.

If you do not specify an argument, the exitStatus will be either 0 (no errors occurred during Topaz execution) or 1 (there was a GCI error or the Topaz errorCount was nonzero).

quit is ignored when reading a file using input, when stdin is a tty. If topaz stdin is redirected to a file and the file does not end with a QUIT or EXIT, topaz considers EOF on stdin to be an error, and will result in a non-zero topaz exit status.

This command cannot be abbreviated.

The command has the same behavior as exit. for more information and examples, see EXIT.

remark commentText

Begins a remark (comment) line. Topaz ignores all succeeding characters on the line.

You can also use an exclamation point (!) or pound sign (#) as the first character in the line to signal the beginning of a comment.

topaz 1>      remark this is a comment

topaz 1> ! another comment

topaz 1> #       and yet another one

Comments are important in annotating Topaz batch processing files, such as test scripts.

removeallclassmethods [aClassName]

Removes all class methods from the class whose name you give as a parameter. The specified class automatically becomes the current class.

If you don’t supply a class name, the methods are removed from the current class, as defined by the most recent set class:, list categoriesin:, method:, or classmethod: command.

This command removes all methods in all compilation environments, not just env 0.

This command cannot be abbreviated.

removeallmethods [aClassName]

Removes all instance methods from the class whose name you give as a parameter. The specified class automatically becomes the current class.

If you don’t supply a class name, the methods are removed from the current class, as defined by the most recent set class:, list categoriesin:, method:, or fileout class: command.

This command removes all methods in all compilation environments, not just env 0.

This command cannot be abbreviated.

Example

topaz 1> run

  { 5 . 66 }.

%

a Array

  #1 5

  #2 66

topaz 1> runblock 'abc' **

  [:a :b |  self copy , a asString , b asString ]

%

abc566

send anObjectSpec aMessage

Sends a message to an object.

The send command’s first argument is an object specification identifying a receiver. The object specification is followed by a message expression built almost as it would be in GemStone Smalltalk, by mixing the keywords and arguments. For example:

topaz 1> level 0

topaz 1> send System myUserProfile

a UserProfile

topaz 1> send 1 + 2

3

topaz 1> send @10443 deleteEntry: @33234

There are some differences between send syntax and GemStone Smalltalk expression syntax. Only one message send can be performed at a time with send. Cascaded messages and parenthetical messages are not recognized by this command. Also, each item must be delimited by one or more spaces or tabs.

All Topaz object specification formats (as described in Specifying Objects) are legal in send commands.

If the configuration parameter GEM_NATIVE_CODE_ENABLED is set to FALSE, or if any breakpoints are set, execution defaults to interpreted mode. Otherwise, execution defaults to using native mode.

For details about GemStone configuration parameters, see the System Administration Guide.

senders selectorSpec

Displays a list of all classes that are senders of the given selectorSpec (either a String or a Symbol). For example:

topaz 1> senders asByteArray

ByteArray >> copyReplaceAll:with:

ByteArray >> copyReplaceFrom:to:with:

This command is equivalent to the following

topaz 1> doit

ClassOrganizer new sendersOfReport: aString 

%

This command may use significant temporary object memory. Depending on your repository, you may need to increase the value of the GEM_TEMPOBJ_CACHE_SIZE configuration parameter beyond its default. For details about GemStone configuration parameters, see the System Administration Guide.

set aTopazParameter [aParamValue]

The set command allows you to set session-specific values for your topaz session. This includes the GemStone login parameters, and settings that affect your topaz user interface.

You can combine two or more set items on one command line, and you can abbreviate token names to uniqueness. For example:

topaz 1> set gemstone gs64stone user DataCurator

topaz 1> set editorname: vi

topaz 1 > set envvar MyRootDir /users/gdmin/project

	!@lichen!gemnetobject

	!@lichen!gs64stone

topaz 1> set hostusername *

set netldi devhost.acme.com:54321

shell [aHostCommand]

spawn [aHostCommand]

When issued with no parameters, this command creates a child process in the host operating system, leaving you at the operating system prompt. To get back into Topaz, exit the command shell by typing Control-D (from the UNIX Bourne or Korn shells), typing logout (from the UNIX C shell), or typing exit (from a DOS shell).

For example, on Windows:

topaz 2> shell

Microsoft Windows [Version 6.1.7601]

Copyright (c) 2009 Microsoft Corporation.  All rights reserved.

C:\GS64\32> dir *.txt

 Volume in drive C is Windows7_OS

 Volume Serial Number is 9ECC-468B

 Directory of C:\GS64\32

02/11/2014  04:38 PM            54,298 open_source_licenses.txt

02/11/2014  04:38 PM             3,209 PACKING.txt

02/11/2014  04:38 PM               104 version.txt

               3 File(s)         57,611 bytes

               0 Dir(s)  135,272,591,360 bytes free

C:\GS64\32>exit

topaz 2>

On UNIX systems, a shell command issued without parameters creates a shell of whatever type is customary for the user account (C, Bourne, or Korn).

If you supply parameters on the shell command line, they pass to a subprocess as a command for execution, and the output of the command is shown.

For example:

topaz 1> shell startnetldi -v

startnetldi 3.6.0 COMMIT: 2020-10-17T17:31:08-07:00 925e19317f5ac852dd751da32230481ad24c31a7

When issued with parameters, shell always creates a shell of the system default type (either Bourne or Korn).

spawn is the same as shell, and is included for compatibility with previous versions.

stack [aSubCommand]

Topaz can maintain up to 500 simultaneous GemStone Smalltalk process call stacks that provide information about the GemStone state of execution. Each call stack consists of a linked list of contexts.

The call stack becomes active, and the stack command becomes accessible, when you execute GemStone Smalltalk code containing a breakpoint. The stack command allows you to examine and manipulate the contexts in the active call stack.

Debugging usually proceeds on the active call stack, but you may also save the active call stack before executing other code, and return to it later.

This command cannot be abbreviated.

Display the Active Call Stack

stack
Displays all of the contexts in the active call stack, starting with the active context. For each context in the stack display, the following items are displayed:

• the level number
• the class of the GsNMethod
• selector of the method
• the environmentId (not used by Smalltalk)
• the current step point (that is, assignment, message send, or method return) within the method
• the line number of the current step point within the source code of the method
• the receiver and parameters for this context.
• the method temporaries (if display oops/alloops is active)
• the OOP of the GsNMethod (if display oops/alloops is active)

The resulting display is governed by the setting of other Topaz commands such as limit, level, and display/omit subcommands.

Any further commands that execute GemStone Smalltalk code: run, printit, send, doit, step, edit last, or edit new text, discards the active call stack unless stack save is executed.

stack anInt
Displays contexts in the active call stack, starting with the active context. The argument anInt indicates how much of the stack to display. For example, if anInt is 1, this command shows only the active context. If anInt is 2, this command also shows the caller of the active context, etc.

topaz 1> run

{ 1 . 2 } do: [:x | x / 0 ]

%

ERROR 2026 , a ZeroDivide occurred (error 2026),

reason:numErrIntDivisionByZero, attempt to divide 1 by zero (ZeroDivide)

topaz 1> stack

==> 1 ZeroDivide (AbstractException) >> _signalWith: @5 line 25

    receiver a ZeroDivide occurred (error 2026),

reason:numErrIntDivisionByZero, attempt to divide 1 by zero

    handleInCextensionBool nil

    res nil

(skipped 1 evaluationTemps)

2 ZeroDivide (AbstractException) >> signal      @2 line 47

    receiver a ZeroDivide occurred (error 2026),

reason:numErrIntDivisionByZero, attempt to divide 1 by zero

3 SmallInteger (Number) >> _errorDivideByZero   @6 line 7

    receiver 1

4 SmallInteger >> /                             @6 line 7

    receiver 1

    aNumber 0

5 [] in  Executed Code                          @2 line 1

    self nil

    receiver anExecBlock1

    x 1

6 Array (Collection) >> do:                     @5 line 10

    receiver anArray

    aBlock anExecBlock1

    i 1

(skipped 4 evaluationTemps)

7 Executed Code                                 @2 line 1

    receiver nil

8 UndefinedObject (GsNMethod class) >> _gsReturnToC @1 line 1

    receiver nil

Display or Redefine the Active Context

stack scope
Displays the current context (Scope is an alternate older name for context or frame). For example:

topaz 1> stack scope

1 AbstractException >> _signalWith:  @6 line 25  

stack scope anInt
Redefines the active context within the active call stack and displays the new context. The integer 1 represents the current context, while the integer 2 represents the caller of the active context.

stack up
Moves the current context up one level toward the top of the stack and displays the new context.

stack down
Moves the current context down one level away from the top of the stack and displays the new context.

stack set aGsProcess
The argument is an object specification that resolves to a GsProcess. Make that aGsProcess the currently active stack for debugging.

stack terminate
Sends #terminate to the GsProcess of the current stack, if the stack is not owned by the scheduler.

stack trim
Trims the stack so that the current context becomes the new top of the stack. Execution resumes at the first instruction in the method at the new top of the stack. If that method has been recompiled, stack trim installs the new version of the method. The new top of the stack must not represent the context of an ExecutableBlock.

For more about this, see the method comments for
GsProcess>>_trimStackToLevel: and
GsProcess>>_localTrimStackToLevel:.

If the stack is trimmed, any resumption of execution will take place in interpreted mode.

Save the Active Call Stack During Further Execution

When you have an active call stack, and execute any of the commands run, printit, send, doit, edit last, or edit new text, it results in the current call stack being discarded.

stack save
Save the active call stack before executing any of the commands that normally clear the stack:.

stack nosave
Cancel the previous stack save.

Display All Call Stacks

stack all
Displays your list of saved call stacks. The list includes the top context of every call stack (stack 1). For example:

topaz 1> stack all

	0:  1 Animal >> habitat                   @1 line 1

	1:  1 AbstractException >> _signalWith:   @6 line 25

	*2:  1 Executed Code                       @3 line 1

The * indicates the active call stack, if one exists. If there are no saved stacks, a message to that effect is displayed.

Equivalent to threads (here)

Redefine the Active Call Stack

stack change anInt
Sets the active call stack to the call stack indicated by anInt in the stack all command output, and displays the top context of the newly selected call stack.

Equivalent to thread anInt (here).

For example:

topaz 1> stack all

 0:  1 Animal >> habitat                   @1 line 1

 1:  1 AbstractException >> _signalWith:   @6 line 25

*2:  1 Executed Code                       @3 line 1

topaz 1> stack change 1

Stack 1 , GsProcess 27447553

1 AbstractException >> _signalWith:        @6 line 25

topaz 1> stack all

 0:  1 Animal >> habitat                   @1 line 1

*1:  1 AbstractException >> _signalWith:   @6 line 25

 2:  1 Executed Code                       @3 line 1

stack set aGsProcessSpecification
The argument is an object specification that resolves to a GsProcess. This GsProcess is made the active call stack for debugging.

Remove Call Stacks

stack delete aStackInt
Removes the call stack indicated by aStackInt in the stack all command output.

Topaz maintains up to eight simultaneous call stacks. If all eight call stacks are in use, you must use this command to delete a call stack before issuing any of the following commands: run, printit, send, doit, edit last, or edit new text.

Equivalent to thread anInt clear (here)

stack delete all
Removes all call stacks.

Terminate the process

stack terminate
Sends #terminate to the GsProcess of the current stack, if the stack is not owned by the scheduler.

step (over | into | thru)

Advances execution to the next step point (assignment, message send, or method return) and halts. You can use the step command to continue execution of your GemStone Smalltalk code after an error or breakpoint has been encountered. For examples and other useful information, see Chapter 2, “Debugging Your GemStone Smalltalk Code”.

step
Equivalent to step over.

step over
Advances execution to the next step point in the current frame or its caller. The current frame is the top of the stack or the frame specified by the last frame, up, down, stack scope, stack up, or stack down command.

step into
Advances execution to the next step point in your GemStone Smalltalk code.

step thru
Advances execution to the next step point in the current frame, or its caller, or the next step point in a block for which current frame's method is the home method.

stk [aSubCommand]

Similar to stack, but does not display parameters and temporaries for each frame. All frames for the active call stack are displayed, with the current active frame indicated by an arrow.

For more information on s, see the stack command here.

This command cannot be abbreviated.

topaz 1> printit

{ 1 . 2} do: [:x | x / 0 ]

%

ERROR 2026 , a ZeroDivide occurred (error 2026),

reason:numErrIntDivisionByZero, An attempt was made to divide 1 by zero. (ZeroDivide)

topaz 1> stk

==> 1 ZeroDivide (AbstractException) >> _signalWith: @6 line 25

2 ZeroDivide (AbstractException) >> signal      @2 line 47

3 SmallInteger (Number) >> _errorDivideByZero   @6 line 7

4 SmallInteger >> /                             @6 line 7

5 [] in  Executed Code                          @2 line 1

6 Array (Collection) >> do:                     @5 line 10

7 Executed Code                                 @2 line 1

8 UndefinedObject (GsNMethod class) >> _gsReturnToC @1 line 1

strings selectorSpec

Displays a list of all methods that contain the given selectorSpec (either a String or a Symbol) in their source string, and class comments in which the text includes selectorSpec.

Search is case-sensitive; for a case-insensitive search, see stringsic. This command cannot be abbreviated.

For example:

topaz 1> strings ChangeUserId

UserProfile >> privileges

UserProfile >> userId:password:

UserProfile >> _privilegesUserProfile class >> _initPrivilegeNames

UserProfileSet >> _oldUserId:newUserId:for:

The strings command is equivalent to the following:

topaz 1> run

| org | 

org := ClassOrganizer new.

org stringsReport: aString ignoreCase: false

includeClassComments: true

%

This command may use significant temporary object memory. Depending on your repository, you may need to increase the value of the GEM_TEMPOBJ_CACHE_SIZE configuration parameter beyond its default.For details about GemStone configuration parameters, see the System Administration Guide.

stringsic selectorSpec

Displays a list of all methods that contain the given selectorSpec (either a String or a Symbol) in their source string, and class comments that include selectorSpec.

This search is case-insensitive; for a case-sensitive search, see the strings command. This command cannot be abbreviated.

The stringsic command is equivalent to the following:

topaz 1> run

| org | org := ClassOrganizer new.

org stringsReport: 'referencesToLiteral:' ignoreCase: true

includeClassComments: true

%

This command may use significant temporary object memory. Depending on your repository, you may need to increase the value of the GEM_TEMPOBJ_CACHE_SIZE configuration parameter beyond its default. For details about GemStone configuration parameters, see the System Administration Guide.

subclasses [aClassName]

Prints immediate subclasses of the specified class. If you don’t specify a class name, prints subclasses of the current class.

topaz 1> subclasses MultiByteString

DoubleByteString

QuadByteString

topaz 1> set class DoubleByteString

topaz 1> subclasses

DoubleByteSymbol

Unicode16

For command to print the complete hierarchy, see SUBHIERARCHY.

subhierarchy [aClassName]

Print print a hierarchy report for all subclasses of the specified class. If you don’t specify a class name, prints hierarchy report for the current class.

Example

topaz 1> subhierarchy MultiByteString

MultiByteString

  DoubleByteString

    DoubleByteSymbol

    Unicode16

  QuadByteString

    QuadByteSymbol

    Unicode32

See Also

HIERARCHY

temporary [aTempName[/anInt] [anObjectSpec] ]

Displays or redefines the value of one or more temporary variables in the current frame of the current stack. For examples and other useful information, see Chapter 2, “Debugging Your GemStone Smalltalk Code”.

All Topaz object specification formats (as described in Specifying Objects) are legal in temporary commands.

temporary
Displays the names and values of all temporary objects in the current frame.

temporary aTempName
Displays the value of the first temporary object with the specified name in the current frame.

topaz 1> temporary preferences

preferences       an Array

temporary aTempName anObjectSpec
Redefines the specified temporary in the current frame to have the value anObjectSpec.

temporary anInt
Displays the value of the temporary at offset n in the current frame. Use this form of the command to access a temporary with a duplicate name, because temporary aTempName always displays the first temporary with the specified name.

temporary anInt anObjectSpec
Redefines the temporary at offset n in the current frame to have the value anObjectSpec.

For example, to view the temporary variable values:

topaz 1> break classmethod String withAll:

topaz 1> run

String withAll: 'abc'

%

a Breakpoint occurred (error 6005), Method breakpoint encountered.

1 String class >> withAll:        								@1 line 1

topaz 1> stack

==> 1 String class >> withAll:                      @1 line 1

    receiver String

    aString abc

2 Executed Code                                 @2 line 1

    receiver nil

3 UndefinedObject (GsNMethod class) >> _gsReturnToC @1 line 1

    receiver nil

and to modify the value of the temporary:

topaz 1> temporary aString 'xyz'

topaz 1> stack

==> 1 String class >> withAll:                      @1 line 1

    receiver String

    aString xyz

2 Executed Code                                 @2 line 1

    receiver nil

3 UndefinedObject (GsNMethod class) >> _gsReturnToC @1 line 1

    receiver nil

the method will return the modified value:

topaz 1> continue

xyz

When the Topaz command display oops has been set, temporaries displayed as .tN are un-named temporaries private to the virtual machine. The example below displays the temporaries used in evaluation of the optimized to:do:, both as shown by the frame command and by the temporary command.

topaz 1> run

| a | 

1 to: 25 do: [:j | a := j. a pause]

%

...

topaz 1> display oops

topaz 1> frame 5

5 Executed Code                      @4 line 2   [methId 25464833]

    receiver [20 sz:0 cls: 76289 UndefinedObject] nil

    a [10 sz:0 cls: 74241 SmallInteger] 1 == 0x1

    j [10 sz:0 cls: 74241 SmallInteger] 1 == 0x1

    .t1 [10 sz:0 cls: 74241 SmallInteger] 1 == 0x1

    .t2 [202 sz:0 cls: 74241 SmallInteger] 25 == 0x19

    .t3 [10 sz:0 cls: 74241 SmallInteger] 1 == 0x1

    .t4 [10 sz:0 cls: 74241 SmallInteger] 1 == 0x1

topaz 1> temporary

    a [10 sz:0 cls: 74241 SmallInteger] 1 == 0x1

    j [10 sz:0 cls: 74241 SmallInteger] 1 == 0x1

    .t1 [10 sz:0 cls: 74241 SmallInteger] 1 == 0x1

    .t2 [202 sz:0 cls: 74241 SmallInteger] 25 == 0x19

    .t3 [10 sz:0 cls: 74241 SmallInteger] 1 == 0x1

    .t4 [10 sz:0 cls: 74241 SmallInteger] 1 == 0x1

tfile aFile

Input a tonel format class definition or class extension file. The methods within the file are all compiled.

The Class specified in the file must already exist (i.e. class definition execution is not attempted).

thread [anInt] [clear]

Displays the currently selected GemStone process from among the stack saved from the last error, or from those retrieved by the most recent threads command.

topaz 1> thread

Stack 0 , GsProcess 27462401

1 Animal >> habitat                        @1 line 1

thread anInt
Changes the currently selected GemStone process. You can specify an integer value from among those shown in the most recent threads command.

topaz 1> thread 1

Stack 1 , GsProcess 27447553

1 AbstractException >> _signalWith:        @6 line 25

thread anInt clear
Clears the selected GsProcess from the Topaz stack cache.

threads [clear]

Force any dirty instances of GsProcess cached in VM stack memory to be flushed to object memory. It then executes a message send of

ProcessorScheduler >> topazAllProcesses

and retrieves and displays the list of processes.

topaz 1> threads

	0: 27462401 debug  

=> 1: 27447553 debug (topaz current) 

	2: 27444225 debug 

threads clear
Clears the Topaz cache of all instances of GsProcess.

Example

topaz 1> time

02/06/2019 13:37:13.545 PST

CPU time:   0.035 seconds

topaz 1> run

Array allInstances size

%

23515

topaz 1> time

02/06/2019 13:37:48.459 PST

CPU time:   0.232 seconds

Elapsed Real time:   8.649 seconds

Elapsed CPU  time:   0.083 seconds

up [anInteger]

In the current stack, change the current frame to be the caller of the current frame, and display the new selected frame. The optional argument anInteger specifies how many frames to move up. If no argument is supplied, the scope will go up one frame.

The behavior is similar to stack up, except that stack up does not accept an argument, and the frame display for stack up does not includes parameters and temporaries for the frame. stack up is described here.

topaz 1> run

{ 1 . 2 } do: [:x | x / 0 ]

%

ERROR 2026 , a ZeroDivide occurred (error 2026),

reason:numErrIntDivisionByZero, attempt to divide 1 by zero (ZeroDivide)

topaz 1> where

==> 1 ZeroDivide (AbstractException) >> _signalWith: @5 line 25

2 ZeroDivide (AbstractException) >> signal      @2 line 47

3 SmallInteger (Number) >> _errorDivideByZero   @6 line 7

4 SmallInteger >> /                             @6 line 7

5 [] in  Executed Code                          @2 line 1

6 Array (Collection) >> do:                     @5 line 10

7 Executed Code                                 @2 line 1

8 UndefinedObject (GsNMethod class) >> _gsReturnToC @1 line 1

topaz 1> up 4

5 [] in  Executed Code                          @2 line 1

    self nil

    receiver anExecBlock1

    x 1

topaz 1> where

1 ZeroDivide (AbstractException) >> _signalWith: @5 line 25

2 ZeroDivide (AbstractException) >> signal      @2 line 47

3 SmallInteger (Number) >> _errorDivideByZero   @6 line 7

4 SmallInteger >> /                             @6 line 7

==> 5 [] in  Executed Code                          @2 line 1

6 Array (Collection) >> do:                     @5 line 10

7 Executed Code                                 @2 line 1

8 UndefinedObject (GsNMethod class) >> _gsReturnToC @1 line 1

where [anInteger | aString]

Displays the current call stack, with one line per frame.

where
Displays all lines of the current call stack. Equivalent to the stk command.

topaz 1> where

==> 1 ZeroDivide (AbstractException) >> _signalWith: @6 line 25

2 ZeroDivide (AbstractException) >> signal      @2 line 47

3 SmallInteger (Number) >> _errorDivideByZero   @6 line 7

4 SmallInteger >> /                             @6 line 7

5 Executed Code                                 @2 line 1

6 UndefinedObject (GsNMethod class) >> _gsReturnToC @1 line 1

where anInteger
Displays the specified number of frames of the stack, starting with the current frame.

topaz 1> where 3

==> 1 ZeroDivide (AbstractException) >> _signalWith: @6 line 25

2 ZeroDivide (AbstractException) >> signal      @2 line 47

3 SmallInteger (Number) >> _errorDivideByZero   @6 line 7

where aString
Searches all frames in the current stack, and displays only those for which the output of where for that frame matches a case-sensitive search for aString anywhere in that frame's output (not including the frame number or ==> marker at the start of the frame's line). The current frame is set to the first frame matched by the search.

The string must not begin with a decimal digit, whitespace, or any of the three characters (' + -), and must not contain whitespace. To specify a string that contains digits or whitespace characters, enclose it in single-quotes. For example:

topaz 1> where error

==> 3 SmallInteger (Number) >> _errorDivideByZero   @6 line 7