4. Command Dictionary

Previous chapter

Next chapter

This chapter provides descriptions of each Topaz command, in alphabetical order.

Command Syntax

Most Topaz commands can be abbreviated to uniqueness. For example, set password: can be shortened to set pass. Exceptions to this rule are a few commands whose actions can affect the success or failure of your current transaction and, thus, the integrity of your data: abort, begin, commit, exit, and so on. Commands that cannot be abbreviated are described in the individual command documentation.

If a command abbreviation is ambiguous, it is not executed. Note however that if a command’s first letters are abbreviated and this matches another command, the other command is executed; for example, the l form of listw, and the c form of continue.

Topaz commands are case-insensitive. Time, TIME, and time are understood by Topaz as the same command. However, arguments you supply to Topaz commands may be subject to case-sensitivity constraints. For example, the commands category: animal and category: Animal specify two different categories, since GemStone Smalltalk is case-sensitive. The same is true of UNIX path names, user names, and passwords.

Objects passed as arguments to Topaz commands can usually be specified using the formats described in Specifying Objects.

Command lines can have as many as 511 characters. You can stop a command at any time by typing Ctrl-C. Topaz may take a moment or two before responding.

ABORT

Aborts the current GemStone transaction. Your local variables (created with the define command) may no longer have valid definitions after you abort.

If your session is outside a transaction, use abort to give you a new snapshot view of the repository data.

This command cannot be abbreviated.

ALLSTACKS

Print the stacks of all instances of GsProcess that are known to the ProcessorScheduler instance in the VM and stacks associated with previous topaz stack save commands.

See also THREADS.

BEGIN

Begins a GemStone transaction. If the session is already in a transaction, this has the effect of an abort. The begin command is only useful if your session is not in automatic transaction mode, i.e., in manual or transactionless transaction mode.

You can change transaction mode using the method System class >> transactionMode: with an argument of #autoBegin, #manualBegin, or #transactionless, or by using the topaz set transactionmode command (page 175).

This command cannot be abbreviated.

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

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 3, “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 methodD methodSpecification [ @ stepPoint ]

break classmethod methodSpecification [ @ stepPoint ]

break @ stepPoint

classSpecification can be defined in these ways:

className

The name of the class that implements methodName.

@integer

An unsigned 64-bit decimal OOP value that denotes the class.

**

The class that was the result of the last execution.

^

The current class, as defined by the most recent set class (or other command that sets the current class)

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.

Examples

The following expressions set breaks in the same method, the KeyValueDictionary instance method at:put:. The same patterns apply for class methods.

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

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

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

COMMIT

Ends the current GemStone transaction and stores your changes in the repository.

This command cannot be abbreviated.

CONTINUE/C

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 3, “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

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 or System class >> waitForDebug.

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.

It is recommended that an error handler invoke System class >> waitForDebug to wait for topaz to attach with debuggem.

In a topaz session created with debuggem,

  • kill will execute kill -TERM against the topaz -l or gem being debugged.
  • continueexecutes System cancelWaitForDebug and stays attached, where it can handle other errors or breakpoints.
  • detach and logout both execute GciLogout and leave the gem in waitForDebug; you can execute debuggem again to reconnect.
  • resume executes System cancelWaitForDebug and GciLogout.
  • step executes System cancelWaitForDebug before performing the single step.

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.

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

For more information, see Debugging from a different session.

The following commands are disallowed when attached using debuggem:

debuggem

define

exitifnoerror

expectvalue

expecterror

expectbug

fileout

fileformat

gcitrace

iferr

iferr_clear

iferr_list

login

loadua

logoutifloggedin

nbrun

nbstep

nbresult

pausefordebug

pollforsignal

protectmethods

unprotectmethods

removeallclassmethods

removeallmethods

shell

stackwaitfordebug

topazwaitfordebug

topazpausefordebug

 

DEBUGRUN

Like run, but sets flags so that execution will stop at the first step point within the source text. The text following the debugrun, and up to the first line that contains a % as the first character in the line, is sent to GemStone for execution as GemStone Smalltalk code.

Execution stops at the first step point within this code, and you may use the STEP command (page 182) to step through execution.

For example:

topaz 1> debugrun
Time now
%
a Breakpoint occurred (error 6002), Single-step breakpoint encountered.
1 1 Executed Code                                 @1 line 1
topaz 1> step 
a Breakpoint occurred (error 6002), Single-step breakpoint encountered.
1 1 Executed Code                                 @2 line 1
topaz 1> step into
a Breakpoint occurred (error 6002), Single-step breakpoint encountered.
1 1 Time class >> now                             @2 line 1
topaz 1> step into
a Breakpoint occurred (error 6002), Single-step breakpoint encountered.
1 1 Time class >> now                             @3 line 9
topaz 1> step into
a Breakpoint occurred (error 6002), Single-step breakpoint encountered.
1 1 DateAndTime class (DateAndTimeANSI class) >> now @2 line 1
... 

See Chapter 3, “Debugging Your GemStone Smalltalk Code”, for more information on breakpoints and debugging code.

debugrun cannot be abbreviated, it must be typed in full

 

DEFINE

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.

DETACH

For use when debugging a second process from another topaz session, using the DEBUGGEM command (page 78).

In the debugging topaz session (the session created by DEBUGGEM), the detach command disconnects from the executing gem or linked process (the session being debugged), executes the equivalent of

System cancelWaitForDebug

and logs out. The GsProcess being debugged will be continued after the logout, and System class >> waitForDebug will return to the caller.

DISASSEM

disassem [ aClassParameter ] aParamValue

The disassem command allows you to disassemble the specified GsNMethod, displaying the bytecode details. This command is intended for use in linked (topaz -L or topaz -l). With an RPC session, output goes to 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.

topaz 1> set class System
topaz 1> disassem classmethod: gemEnvironmentVariable:
System class >> gemEnvironmentVariable:  method:10029057
, literals at IP 88
Step/Source IP    Opcode         Description  (IP in bytes from &obj.hdr)
 ---/------ ---   -------------- -----------
  1/     1    56    CHKInt
              58    PUSH_LITERAL_oldGen_u1 u1=1e flag=0 zlitIdx:8
literal:Oop 135169 aClass:  GsFile
              64    PUSH_STK_s1 s1=16 bytes(2 words)
              68    PUSH_SPECIAL_OOP_s1 s1=12 val=Oop 12 Class:
Boolean
  2/   536    72    SEND_u1_u32 sel=Symbol(oop 5768961)
#'_expandEnvVariable:isClient:' env:0, 2 args, sendCache.u2=24 
  3/   527    80    RETURN_TOS_u1 u1=24 bytes(3 words)

DISPLAY

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

alloops

display alloops
If display alloops is set, enables the display of OOPs of classes along with class names in object display, and displaying the oops of primitive specials. Also causes the OOPs of classes to be printed by stack display and method lookup commands, and enables the printing of evaluation temporary objects in stack frame printouts from the frame command.

Default: omit alloops

bytes

display bytes
When displaying byte-format objects such as Strings and ByteArrays, include the hexadecimal value of each byte.

Default: omit bytes

for example,

topaz 1> exec #[ 97 98 99 ] %
  1 'abc'                      61 62 63

classoops

display classoops
Legacy; equivalent to display alloops.

decimalbytes

display decimalbytes
When displaying byte-format objects such as Strings and ByteArrays, include the decimal value of each byte.

Default: omit decimalbytes

for example,

topaz 1> exec #[ 97 98 99 ] %
 1 'abc'                       97  98  99

deprecated

display deprecated
For topaz commands such as strings and senders, which return lists of methods, display deprecated causes those results to include methods which contain sends of deprecated, deprecated:, or deprecatedNotification:.

Default: display deprecated

Deprecated methods are those that send one of the following messages:

deprecated
deprecated: 
deprecatedNotification:

For example, the method concurrencyMode is deprecated:

topaz 1> implementors concurrencyMode
System class >> concurrencyMode
topaz 1> omit deprecated
topaz 1> implementors concurrencyMode
(Omitted 1 deprecated methods)

flushoutput

display flushoutput
enables immediate flushing of topaz output files other than stdout. display flushoutput causes an fflush() call to be made to each active topaz log file (files specified by output push) other than stdout, after each line of topaz output is written. This allows a tail -f to have a more up-to-date view of a topaz output file.

Default: omit flushoutput

errorcheck

display errorcheck
Allows Topaz programs to automatically record the results of error checking. Using this command creates the ./topazerrors.log file or opens the file to append to it, if it already exists.

As long as display errorcheck is set, every time ErrorCount is incremented, a summary of the error is added to topazerrors.log. The summary includes the line number in the Topaz output file, if possible. If the only output file open is stdout, then line numbers are not available. To close the topazerrors.log file, use the omit errorcheck command. Subsequent results are not recorded.

Default: omit errorcheck

lineeditor

display lineeditor
Enables the use of the Topaz line editor, using the open source linenoise library. This is not available on Windows.

The number of lines of history kept for the lineeditor is controlled using the set history command (page 171).

The status command includes one of the followings lines to indicate if the lineeditor is in use:

using line editor
not using line editor

Default: display lineeditor

oops

display oops
For each object, displays a header containing the object’s OOP (a 64-bit unsigned integer), the object’s size (the sum of its named, indexed, and unordered instance variable fields), and the OOP of the object’s class.

The oops of certain primitive special objects, such as Characters, SmallIntegers, Booleans, and nil, do not display their oops. To enable display of their oops, use display alloops.

Default: display oops

names

display names
For each of an object’s named instance variables, displays the instance variable name along with its value.

When instance variable name display is off, named instance variables appear as i1, i2, i3, and so on.

Default: display names

pauseonerror

display pauseonerror
When an error occurs, if Topaz is receiving input from a terminal, displays the message:

Execution has been suspended by a "pause" message.
Topaz pausing after error, type <return> to continue, ctl-C to quit ? 

and waits for the user to press the Return key to continue execution. Pressing Ctrl-C ends the pause and stops the processing of input files altogether.

If display resultCheck is also set, then Topaz only pauses when the result or error is contrary to the current resultCheck, expectvalue, and expecterror settings.

The status command includes one of the followings lines to indicate status of this attribute:

display interactive pause on errors
omit interactive pause on errors

Default: omit pauseonerror

pauseonwarning

display pauseonwarning
When a compiler warning occurs, and if the topaz stdin is from a terminal, then write a message "Pausing after warning ..." to stdout, and wait for an end of line on stdin before continuing topaz execution. A ctl-C on stdin will terminate the pause and terminate further processing of input files.

The status command includes one of the followings lines to indicate status:

display interactive pause on warnings
omit interactive pause on warnings

Default: omit pauseonwarning

pushonly

display pushonly
Enables the effect of the only keyword in an output push command. Does not effect output to stdout within a topaz -S script. To disable this effect, use the omit pushonly command.

Default: display pushonly

resultcheck

display resultCheck
Allows Topaz programs to check input values and record the results. This command creates the ./topazerrors.log file or opens the file to append to it, if it already exists. Specifying display resultCheck is equivalent to setting expectvalue true, except that it affects the behavior of all run and printit commands, not only the next one.

As long as display resultCheck is set, every time ErrorCount is incremented, a summary of the error is added to topazerrors.log. This includes the line number in the Topaz output file, if possible. If the only output file open is stdout, then line numbers are not available. To close the file, use the omit resultCheck command. Then the results of a successful run or printit command will no longer be checked, unless an expectvalue command precedes the printit command.

Default: omit resultcheck

singlecolumn

display singlecolumn
rather than displaying large numbers (more than eight) of method and temporary variable definitions with a debugger stack frame in columns, display in a single column.

Default: omit singlecolumn

stacktemps

display stacktemps
enables the display of stack frames to include un-named evaluation temps which have been allocated by bytecodes within the method.

Default: omit stacktemps

versionedclassnames

When display versionedclassnames is set, which is the default, topaz includes [verionNumber] following the class name, for instances of classes that are not the last one in the classHistory of that class. This is limited to when display oops is also set.

zerobased

display zerobased
Shows offsets of instance variables as zero-based when displaying objects. With display zerobased, offsets are zero-based, with omit zerobased, offsets are one-based.

Default: omit zerobased (offsets are one-based, as in Smalltalk) .

DOIT

Sends the text following the doit command to the object server for execution and displays the OOP of the resulting object. If there is an error in your code, Topaz displays an error message instead of a legitimate result. GemStone Smalltalk text is terminated by the first line that contains a % as the first character in the line. For example:

topaz 1> doit
2 + 1
%
result oop is 26

The text executed between the doit and the terminating % can be any legal GemStone Smalltalk code, and follows all the behavior documented in the Programming Guide for GemStone/S 64 Bit.

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.

Note that doit always displays results at level 0, regardless of the current display level setting (here). The doit command does not alter the current level setting.

DOWN

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 GsNMethod class >> _gsReturnToC               @1 line 11
 
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 GsNMethod class >> _gsReturnToC               @1 line 11
 

DUMPOBJ

dumpobj anObjectSpecification

This command does a low-level dump of an object, the node of a large object, or the node of an IdentityBag. For a byte format object, it displays the integer values of the bytes. This command cannot be abbreviated

For example

topaz 1> dumpobj Globals
aSymbolDictionary
  #1 657
  #2 112
  #3 20260
  #4 1013
  #5 nil
  #6 anIdentityCollisionBucket
  #7 ReadWriteStreamPortable
  #8 aSymbolAssociation
  #9 nil
  #10 anIdentityCollisionBucket
  #11 PositionableStreamPortable
  #12 aSymbolAssociation
  #13 nil
  #14 anIdentityCollisionBucket
  #15 ReadStreamLegacy
  #16 aSymbolAssociation
   ...

EDIT

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 className >> selectorSpec

edit className class >> selectorSpec
Allows you to edit the source code of an existing instance or class method. For example:

topaz 1> edit Animal >> habitat
topaz 1> edit Animal class >> name:species:habitat:

edit method: selectorSpec
Edit the source code of an existing instance method. Before you can use this subcommand, 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

edit classmethod: selectorSpec
Edit the source code of an existing class method. Before you can use this subcommand, 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.

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

ENV

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

ERRORCOUNT

Displays the Topaz errorCount variable, which stores the number of errors made in all sessions since you started Topaz. This includes GemStone Smalltalk errors generated by compiling or a run or printit command, as well as errors in Topaz command processing.

If expecterror is specified immediately before a compile or execute command (run, printit, doit, method:, classmethod:, send, or commit) and the expected error occurs during the compile or execute, the ErrorCount is not incremented. The ErrorCount is not reset by login, commit, abort, or logout.

You can use the errorCount command at the topaz> prompt before you log in, as well as after login.

topaz> errorcount
0

It is equivalent to

topaz 1> object ErrorCount

except that errorcount does not require a valid session.

This command cannot be abbreviated.

EXEC

Sends the text following the exec command to GemStone for execution as GemStone Smalltalk code, and displays the result.

The exec command, unlike related commands such as run and printit, accept text on the same line as the exec command itself, up to a % character on that line. If there is no % on the exec command line, subsequent lines are included as part of the Smalltalk code to be executed, up to a % character appearing as the first character in a line.

For example:

topaz 1> exec 2 + 2 %
4

The text executed between the exec and the terminating % can be any legal GemStone Smalltalk code, and follows the behavior documented in the Programming Guide for GemStone/S 64 Bit.

If there is an error in your code, Topaz displays an error message instead of a legitimate result.

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.

Like run, exec uses the current display level setting (here).

EXIT

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/2023 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/2023 15:21:17.137 PDT Logging out

 

EXITIFNOERROR

If there have been no errors — either GemStone Smalltalk errors or Topaz command processing errors — in any session since you started Topaz, this command has the same effect as exit 0 (described here). Otherwise, this command has no effect.

This command cannot be abbreviated.

EXPECTBUG

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

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 GsNMethod class >> _gsReturnToC               @1 line 11
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

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

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:

utf8

fileformat utf8
Sets the fileformat to UTF-8. Code that is filed out using fileout is encoded in UTF-8, and files read using input are interpreted as being UTF-8 and are decoded accordingly.

8bit

fileformat 8bit
Sets the fileformat to 8-bit, for compatibility with older releases. Code that is filed out using fileout are written as bytes, not encoded as UTF-8. Fileout of code containing Characters with codePoints over 255 will error.

The default at topaz startup is utf8. If you are filing in code from an older release, verify that the header includes the fileformat 8bit, or explictly set this in your topaz session.

Input from stdin that is a tty is always interpreted as UTF-8; changing the fileformat of a tty stdin to 8bit is not allowed.

 

FILEOUT

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

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

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

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 GsNMethod class >> _gsReturnToC              @1 line 11
 
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 GsNMethod class >> _gsReturnToC              @1 line 11
 
topaz 1> frame 7
7 Executed Code                                 @2 line 1
    receiver nil

GCITRACE

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

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

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

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

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.

IFERR_CLEAR

The iferr_clear command clears all the post-error command buffers.

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

This command cannot be abbreviated.

IFERR_LIST

The iferr_list command prints all the non-empty post-error command buffers.

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

This command cannot be abbreviated.

IFERROR

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

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

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

inspect [anObjectSpec]

Sends the message describe to the designated object.

This command is equivalent to the following

topaz 1> send anObjectSpec describe%

INTERP

Sends the text following the interp command to GemStone for execution as GemStone Smalltalk code, and displays the result.

This command is identical to the RUN command (page 163), except that the interp command does not use native code, the Smalltalk code execution is interpreted.

GemStone Smalltalk text is terminated by the first line that contains a % as the first character in the line. For example:

topaz 1> interp
2 + 2 
% 
4

The text executed between the interp and the terminating % can be any legal GemStone Smalltalk code, and follows the behavior documented in the Programming Guide for GemStone/S 64 Bit.

This command cannot be abbreviated.

KILL

For use when debugging a second process from another topaz session, using DEBUGGEM command (page 78).

In a topaz session that was created by debuggem , the kill command executes kill -TERM against the gem or linked process being debugged.

 

LEVEL

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:

LIMIT

limit [bytes | oops | lev1bytes | lev2oops ] 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.

bytes

limit anInteger

limit bytes anInteger
Tells Topaz how much of any byte object (instance of String or one of String’s subclasses) to display in GemStone Smalltalk results.

If anInteger is non-zero, then when displaying frame temporaries, or when displaying an object with a display level of 1 or greater, any byte-valued instance variable with a byte object value will be limited to one line (about 80 characters) of output. To display the full contents of that byte object (up to the limit set by anInteger), use the object command.

For debugging source code, we suggest limit bytes 5000.

oops

limit oops anInteger
Tells Topaz how much of any pointer or nonsequenceable collection to display in GemStone Smalltalk results.

lev1bytes

limit lev1bytes anInteger
When the topaz level is set to 1 or greater, this limit controls how many bytes to display of instVar values and frame temporaries. Default is 100. If lev1bytes is set to zero, then the value of "limit bytes" is used for instVar values and frame temporaries.

lev2oops

limit lev2oops anInteger
When the topaz level is set to 2or greater, this limit controls how many oops to display of instVar values.

LIST

The list command is used in conjunction with the set and edit commands to browse through dictionaries, classes, and methods in the repository. The list command is also useful in debugging.

When no arguments are included on the command line, the list command lists the source code for the currently selected stack frame, as selected by the most recent lookup, up, down, or frame command.

Browsing Dictionaries and Classes

dictionaries

list dictionaries
Lists the SymbolDictionaries in your GemStone symbol list. This executes the GemStone Smalltalk method UserProfile>>dictionaryNames.

classesIn:

list classesIn: aDictionary
Lists the classes in aDictionary. For example,

topaz 1> list classesIn: UserGlobals

lists all of the classes in your UserGlobals dictionary.

classes

list classes [subStringPattern]
Lists all of the classes in all of the dictionaries in your symbol list.

To limit the displayed classes, you can include an argument subStringPattern. Only results that match, case insensitive, some portion of the subStringPattern are displayed. For example,

topaz 1> list classes cert
GsX509Certificate
GsX509CertificateChain

categoriesIn:

list categoriesIn: [aClass]
Lists all of the instance and class method selectors for class aClass, by category, and establishes aClass as the current class for further browsing.

If you omit the class name parameter, method selectors are listed by category for the current class.

icategories

list icategories [className]
Lists all of the instance method selectors for the named class, by category. If you specify a class name, that class becomes the current class for subsequent Topaz commands. If you omit the class name parameter, lists the categories of the current class.

ccategories:

list ccategories: [className]
Lists all of the class method selectors for the named class, by category. If you specify a class name, that class becomes the current class for subsequent Topaz commands. If you omit the class name parameter, lists the categories of the current class.

selectors

list selectors [token]
Lists selectors of all instance methods in the current class, for which the argument token is a case-insensitive substring of the selector. If token is omited, list all instance method selectors in the current class. May be abbreviated as list sel.

For example,

topaz 1> set class Array
topaz 1> list sel at:p
    at:put:
    _at:put:
    _basicAt:put:

cselectors

list cselectors [token]
Lists selectors of all class methods in the current class, for which the argument token is a case-insensitive substring of the selector. . If token is omited, list all class method selectors in the current class. May be abbreviated as list csel.

primitives

list primitives [token]
Lists selectors of all class methods in the current class that invoke primitives. If token is specified, only return the selectors that contain a case-insenstive substring matching the given token string. May be abbreviated as list prim.

cprimitives

list cprimitives [token]
Lists selectors of all instance methods in the current class that invoke primitives. If token is specified, only return the selectors that contain a case-insenstive substring matching the given token string. May be abbreviated as list cprim.

Listing Methods

list with no arguments lists the source code of the active method context. See Chapter 3, “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.

method:

list method: selectorSpec
Lists the category and source code of the specified instance method selector for the current class. You can also enter this command as list imethod.

classmethod:

list classmethod: selectorSpec
Lists the category and source of the given class method selector for the current class. You can also enter this command as list cmethod: or list cmethod.

imethod:

list imethod: is the equivalent to list method:.

linenumbers

list linenumbers
This is an additional option to one of the above commands, preceeding the method specification. When this is used, the line number is included in the listing. For example:

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

step

list step
Lists the source code of the current frame, and display only the step point corresponding to the step point of the current frame.

steps

list steps
Lists the source code of the current frame, and displays step points in that source code.

list steps method: selectorSpec
Lists the source code of the specified instance method for the current class, and displays all step points (allowable breakpoints) in that method. For example:

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

You can use the break command to set method breakpoints before assignments, message sends, or method returns. As shown here, the position of each method step point is marked with a caret and a number. Each line of step point information is indicated by asterisks (*).

For more information about method step points, see Chapter 3, “Debugging Your GemStone Smalltalk Code”.

list steps classmethod: selectorSpec
Lists the source code of the specified class method for the current class, and displays all step points in that method.

stepips

list stepips

list stepips, list stepips method:, and list stepips classmethod: list source code and display the IPs (instructions pointers) of the step points. These commands are intended for low-level debugging and not normally useful for customer development debugging.

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 3, “Debugging Your GemStone Smalltalk Code”.

breaks

list breaks
Lists the source code of the current frame, and displays the step points for the method breakpoints currently set in that method. Disabled breakpoints are displayed with negative step point numbers.

list breaks method: selectorSpec
Lists the source code of the specified instance method for the current class, and displays the method breakpoints currently set in that method. For example:

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

list breaks classmethod: selectorSpec
Lists the source code of the specified class method for the current class, and displays the method breakpoints currently set in that method.

LISTW / L

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 GsNMethod class >> _gsReturnToC              @1 line 11
 
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

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
 

LOADUA

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.

LOGIN

Lets you log in to a GemStone repository. Before you attempt to log in to GemStone, you’ll need to use the set command—either interactively or in your Topaz initialization file—to establish certain required login parameters. The required parameters for network communications are:

set gemnetid:
name of the GemStone service on the host computer (defaults to gemnetobject for the RPC version (topaz command) or gcilnkobj for the linked version (topaz  command)

set gemstone:
name of the Stone (repository monitor) process, if necessary including node and protocol information in the form of a network resource string (NRS). See the System Administration Guide for more on NRS syntax and usage.

set username:
your GemStone user ID.

set password:
your GemStone password.

set hostusername:
your user account on the host computer. Required for the RPC version of Topaz or for RPC sessions spawned by the linked version.

set hostpassword:
your password on the host computer. Required for the RPC version of Topaz or for RPC sessions spawned by the linked version of Topaz.

Topaz allows you to run your Gem (GemStone session), Stone (repository monitor), and Topaz processes on separate network nodes. For more information about this, see the discussion of set gemnetid and set gemstone.

If you are using linked Topaz (topaz -L), also note the following:

For more information about logging in to GemStone, read the section Logging In to GemStone. The set command is described here.

LOGOUT

Logs out the current GemStone session. This command aborts your current transaction. Your local variables (created with the define command) will no longer have valid definitions when you log in again.

This command cannot be abbreviated.

LOGOUTIFLOGGEDIN

If logged in, logs out the current GemStone session. If there is no current session, does not increment the Topaz error count.

As with the LOGOUT command (page 134), this command aborts your current transaction. Your local variables (created with the define command) will no longer have valid definitions when you log in again.

This command cannot be abbreviated.

LOOKUP

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 GsNMethod class >> _gsReturnToC              @1 line 11

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

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

NBRESULT

Wait for and display the result of a previous nbrun call. This call may be preceded by a set session to switch to the session of an outstanding nbrun; otherwise, the current Topaz session is used.

May be immediately preceded by expectvalue or expectbug, provided that the expect commands contain only Integers or numerically coded OOPS (i.e. @NNN), so that no GemStone code is executed before the nbresult.

If the nbrun has compilation errors, those will be displayed by the nbresult. If there is no outstanding nbrun for the session the result is:

   [276 sz:0 cls: 76289 UndefinedObject] remoteNil

Note that nonblocking operations do block in linked sessions, and in a linked session the result with no outstanding nbrun is nil, not remoteNil.

This command is the equivalent of calling the GemBuilder for C function GciNbEnd.

NBRUN

Similar to run, but execution is nonblocking, so the application can proceed with non-GemStone tasks while the expression is executed. To get the results of the execution, use nbresult.

In a linked session, nbrun is blocking (necessarily). In this case a warning message is displayed. For example:

topaz 1> nbrun
Time now
%
Current session not remote, nbrun executing synchronously
topaz 1> nbresult
09:48:17

nbrun should not be immediately preceded by expect commands, since this command has no result. May be followed by a set session and another nbrun to start an execution in another session.

The text of this command is not accessible from edit last.

This command is the equivalent of calling the GemBuilder for C function GciNbExecute.

NBSTEP

Similar to step, but execution is nonblocking. To get the results of the execution, use nbresult.

In a linked session, nbstep is blocking (necessarily). In this case a warning message is displayed.

Should not be immediately preceded by expect commands, since this command has no result. May be followed by a set session and another nbrun or nbstep to start an execution in another session.

This command is the equivalent of calling the GemBuilder for C function GciNbStep.

OBJ1 / OBJ2

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 / OBJ2Z

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

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

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.

alloops

omit alloops
Disables the display of OOPs of classes along with class names in object display and of the oops of primitive specials, stopping the effect of display alloops.

bytes

omit bytes
When displaying byte-format objects, do not include the decimal or hexadecimal value of each byte.

classoops

omit classoops
Legacy; equivalent to omit alloops.

decimalbytes

omit bytes
When displaying byte-format objects, do not include the decimal or hexadecimal value of each byte.

deprecated

omit deprecated
For topaz commands such as strings and senders, which return lists of methods, omit deprecated causes those results to omit methods which contain sends of deprecated, deprecated:, or deprecatedNotification:.

errorcheck

omit errorcheck
Disables automatic result recording, stopping the effect of display errorcheck. Closes the ./topazerrors.log file.

flushoutput

omit flushoutput
displays the immediate flushing of topaz output files other than stdout.

lineeditor

omit lineeditor
Disables the use of the Topaz line editor, stopping the effect of display lineeditor. Always disabled on Windows.

names

omit names
For each of an object’s named instance variables, do not display the instance variable’s name along with its value. When you have issued omit names, named instance variables appear as i1, i2, i3, etc.

oops

omit oops
Do not display OOP values with displayed results.

pauseonerror

omit pauseonerror
Disables pauses in Topaz execution after errors, stopping the effect of display pauseonerror.

pauseonwarning

omit pauseonwarning
Disables pause in Topaz execution after a compiler warning occurs.

pushonly

omit pushonly
Disables the effect of the only keyword in an object push command, stopping the effect of display pushonly.

resultcheck

omit resultCheck
Disables automatic result checking, stopping the effect of display resultCheck. Closes the ./topazerrors.log file and stops checking the results of successful run, printit, etc. commands. You can still check the result of an individual run command by entering an expectvalue command just before it.

singlecolumn

omit singlecolumn
Disables effect of display singlecolumn.

stacktemps

omit stacktemps
Disables effect of display stacktemps.

versionedclassnames

omit versionedclassnames
Disable the display of the class version for instances of classes that are not the last one in the classHistory of that class.

zerobased

omit zerobased
Shows offsets of instance variables as one-based when displaying objects.To show offsets as zero-based, use the display zerobased command.

OUTPUT

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.

only

The above output commands will send output to both stdout and the each file on the stack. Using the only command both limits output to only go to the specific named file, and turns off the echo of results to stdout.

output aFileName only

output push aFileName only

output append aFileName only

output pushnew aFileName only
Sends output to the specified file, but does not echo that output to stdout.

pop

output pop
Stops output to the current output file (that is, the file most recently named in an output push command). The file is closed, and output is again sent to the previously named output file.

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

PAUSEFORDEBUG

pausefordebug [errorNumber]

Provided to assist internal debugging of a session.

With no argument, this command has no effect.

This command cannot be abbreviated.

PKGLOOKUP

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

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.

 

PRINTIT

Sends the text following the printit command to GemStone for execution as GemStone Smalltalk code, and displays the result. If there is an error in your code, Topaz displays an error message instead of a legitimate result. GemStone Smalltalk text is terminated by the first line that contains a % as the first character in the line. For example:

topaz 1> printit 
2 + 2 
% 
4

The text executed between the printit and the terminating % can be any legal GemStone Smalltalk code, and follows all the behavior documented in the GemStone/S Programming Guide.

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.

Note that printit always displays results at level 1, regardless of the current display level setting (here). The printit command does not alter the current level setting. The RUN command (page 163) displays according to the current level setting, and the DOIT command (page 88) displays results at level 0.

PROTECTMETHODS

After this command, all subsequent method compilations during the current session must contain either a <protected> or <unprotected> directive.

Used for consistency checking in filein scripts.

This command cannot be abbreviated.

QUIT

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.

RELEASEALL

Empty Topaz's internal buffer of object identifiers (the export set). Objects are placed in the export set as a result of object creation and certain other object operations. releaseall is performed automatically prior to each run, doit, printit, or send.

For more information, see the GemBuilder for C Manual. releaseall is equivalent to the GemBuilder for C call GciReleaseOops.

REMARK

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

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

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.

RESUME

resume

In a topaz session created by debuggem, executes System cancelWaitForDebug in the Gem or topaz -l being debugged and then does a GciLogout from that gem. The GsProcess being debugged will be continued after the logout and System class >> waitForDebug will return to the caller.

RUN

Sends the text following the run command to GemStone for execution as GemStone Smalltalk code, and displays the result.

If there is an error in your code, Topaz displays an error message instead of a legitimate result.

GemStone Smalltalk text is terminated by the first line that contains a % as the first character in the line. For example:

topaz 1> printit 
2 + 2 
% 
4

The text executed between the run and the terminating % can be any legal GemStone Smalltalk code, and follows all the behavior documented in the GemStone/S Programming Guide.

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.

The run command is similar to printit, with one significant difference. The run command uses the current display level setting (here), whereas printit always displays the result as if level 1 were the most recent level command.

RUNBLOCK

The topaz command runblock is primarily intended to support internal debugging.

runblock takes two arguments on the command line, and the following lines up to the next % must be the source for a block with between 0 and 10 block variables. The arguments are both objects per object specification format, see Specifying Objects.

The first argument is used for self in the block, and can be anything that can be specified on the command line.

The second argument must specify an Array of size N, N <= 10, where N is the number of argument variables. This second argument can be specified using ** or @OOP, or named in UserGlobals.

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

RUNENV envId

Similar to run, but takes one integer argument >= 0 and <= 255, specifying compilation environment for the code to execute in. The argument takes precedence over the value set by env or set compile_env.

If GEM_NATIVE_CODE_ENABLED=FALSE in the gem configuration file, or if any breakpoints are set, execution defaults to interpreted mode, otherwise execution defaults to using native code.

SEND

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

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

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

cacert

set cacert: aCaCertFilePath
Sets the path to the trusted X509 certificate authority (CA) certificate to be used to validate certificates presented by peers. The certificate must be in PEM format.

This setting is used only by X509 logins and is cleared if traditional login parameters are set (username, password, hostusername, hostpassword, gemstone, gemnetid, or solologin).

cachename

set cachename: aString
Sets the current cachename, which applies to subsequent logins for all sessions. This cache name is recorded in the cache statistics collected by statmonitor for viewing in VSD. The name must be 31 characters or less, and is truncated if too long. The cachename can also be set using the command line -u argument. The colon is not required.

Using set cachename or the -u option has advantages over the programmatic assignment using System class >> cacheName:. Setting the name prior to login allows statistics to be collected and displayed under a single meaningful name, rather than being split between the initial default name and a later meaningful name.

category

set category: aCategory
Sets the current category, the category for subsequent method compilations. You must be logged in to use this command. If you try to compile a method without first selecting a category, the new method is inserted in the default category “as yet unspecified.” The set category: command has the same effect as the category: command.

If the specified category does not already exist, Topaz will create it when you first compile a method.

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.

cert

set cert: aCertFilePath
Sets the path to the X509 certificate to be used for login. The certificate must be in PEM format. The file may contain multiple certificates which comprise a certificate chain. The user certificate must be the first certificate in the file and may be followed by certificate authority (CA) certificates. All certificates must be ordered within the file such that the a given certificate is signed by the certificate which follows it.

This setting is used only by X509 logins and is cleared if traditional login parameters are set (username, password, hostusername, hostpassword, gemstone, gemnetid, or solologin).

class

set class: aClassName
Sets the current class. You must be logged in to use this command. After setting the current class, you can list its categories and methods with the list categories command. You can select a category to work with through either the set category: or category: command.

The current class may also be redefined by the list categoriesin:, method:, classmethod:, removeAllMethods, removeAllClassMethods, and fileout class: commands.

The current class is cleared by the logout, login, and set session commands, or by executing set class nil.

To display the name of the current class, issue the set class command without a class name.

compile_env

set compile_env: anInteger
Sets the compilation environmentId used for method compiliations and run, printit, etc. anInteger must be between 0 and 255 and is 0 by default. The compilation environment may also be set using the commend env.

directory

set directory: directoryPath
Set the name of the working directory for the RPC gem created by an X509 login.

This setting is used only by X509 logins and is cleared if traditional login parameters are set (username, password, hostusername, hostpassword, gemstone, gemnetid, or solologin).

editorname

set editorname: aHostEditorName
Sets the name of the editor you want to use in conjunction with the edit command. For example:

topaz 1> set editorname: vi

The default is set from your $EDITOR environment variable, if it is defined.

enableremoveall

set enableremoveall onOrOff
When set enableremoveall is set to ON, it enables the commands removeallmethods and removeallclassmethods. When it set to OFF, these commands have no effect. The default is ON.

envvar

set envvar: varName varValue
Set an enviroment variable value in the topaz process. For example,

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

The word ENVVAR cannot be abbreviated.

extragemargs

set extragemargs: aStringOfArgs
Sets a list of extra command line arguments to be used when starting an RPC gem for an X509 login.

This setting is used only by X509 logins and is cleared if traditional login parameters are set (username, password, hostusername, hostpassword, gemstone, or gemnetid).

gemnetid

set gemnetid: aServiceName
aServiceName
is a network resource string specifying the name of the GemStone service (that is, the host process to which your Topaz session will be connected) and its host computer.

For the RPC version of Topaz the default gemnetid parameter is gemnetobject. You may also use gemnetdebug or your own custom gem service. RPC versions of Topaz cannot start linked sessions.

For linked Topaz (started with topaz -L or -l), the default gemnetid is gcilnkobj. Use the status command to verify that this parameter is gcilnkobj. This makes the first session to log in a linked session. It is only possible to have one linked session per topaz process.

This command, like other set options, can be used in a .topazini initialization file that is executed when topaz starts up. When using topaz -L, any option to gemnetid within a .topazini file is ignored

When using linked topaz, if gemnetid is explicitly set to a gem service such as gemnetobject, login starts RPC sessions. Note that when you login an RPC session that way, the configuration parameters reported for the linked session do not apply; the rules governing configuration parameters for RPC sessions take effect.

You can run your GemStone session (Gem), repository monitor (Stone) process, and your Topaz processes on separate nodes in your network. The one exception is the linked Topaz session, when Topaz and the Gem run as a single process. Network resource strings allow you to designate the nodes on which the Gem and Stone processes run. For example, a Gem process called gemnetobject on node lichen could be described in network resource string syntax as:

	!@lichen!gemnetobject

To specify a Gem running on the current node, omit the node portion of the string, and specify only the Gem name: gemnetobject. See the System Administration Guide for more on NRS syntax and usage.

This setting is used only by traditional logins and is cleared if any X509 login parameters are set. (cert, cacert, key, netldi, logfile, directory, or extragemargs)

gemstone

set gemstone: aGemStoneName
Specifies the name of the GemStone you want to log in to, in NRS syntax.

You can run your GemStone session (Gem), repository monitor (Stone) process, and your Topaz processes on separate nodes in your network. The one exception is the linked Topaz session, when Topaz and the Gem run as a single process. Network resource strings allow you to designate the nodes on which the Gem and Stone processes run. For example, a Stone process called gs64stone on node lichen could be described in network resource string syntax as:

	!@lichen!gs64stone

If the Stone is running on the same node as the Gem, the node portion of the string is optional; you only need to specify the Stone name: gs64stone. See the System Administration Guide for more on NRS syntax and usage.

This setting is used by traditional logins and is cleared if any X509 login parameters are set. (cert, cacert, key, netldi, logfile, directory, or extragemargs)

history

set history: anInt
Sets the history size of the Topaz line editor. The argument anInt may be between 0 and 1000, inclusive. Not available on Windows.

hostpassword

set hostpassword: aPassword
Sets the host password to be used when you next log in. If you don’t include the host password argument on the command line, Topaz prompts you for it. Prompted input taken from the terminal is not echoed. This lets you put a set hostpassword: command in your Topaz initialization file so that Topaz automatically prompts you for your password. Note, however, that this command must follow the set hostusername: command.

For a linked Topaz session, set hostpassword has no effect, because no separate Gem process is created on the host computer. The password is required, however, if you spawn new sessions while you are running linked Topaz, because the additional sessions are always RPC Topaz.

This setting is used only by traditional logins and is cleared if any X509 login parameters are set. (cert, cacert, key, netldi, logfile, directory, or extragemargs)

hostusername

set hostusername: aUsername
Sets the account name you use when you log in to the host computer. When you run Topaz, a Gem (GemStone session) process is started on the host computer specified by the set gemnetid: command. The set hostusername: command tells Topaz which account you want that process to run under.

To clear the hostusername field, enter:

topaz 1> set hostusername *

For a linked Topaz session, set hostusername has no effect, since no separate Gem process is created on the host computer.)

This setting is used only by traditional logins and is cleared if any X509 login parameters are set. (cert, cacert, key, netldi, logfile, directory, or extragemargs)

inconversion

set inconversion
For use only by repository upgrade scripts in $GEMSTONE/upgrade. Sets the interal variable GciSupDbInConversion to TRUE.

inputpauseonerror

set inputpauseonerror: onOrOff
The argument must be a case-insensitive string, ON or OFF. If ON, and stdin is a tty, then the first input command issued interactively will transition topaz to DISPLAY PAUSEONERROR. This remains in effect until topaz input returns to stdin, at which point the previous state of DISPLAY PAUSEONERROR is restored.

The default is OFF

May not be abbreviated.

key

set key: privateKeyPath
For an X509 login, sets the path to the private key for the certificate specified by the SET CERT: command. The key must be in PEM format and must not be protected by a passphrase.

This setting is used only by X509 logins and is cleared if traditional login parameters are set (username, password, hostusername, hostpassword, gemstone, gemnetid, or solologin).

limit

set limit: anInt
Sets the limit on the number of bytes to display. The equivalent of limit bytes anInt

listwindow

set listwindow: anInt
Defines the maximum number of source lines to be listed by the LISTW / L command (page 130).

logfile

set logfile: pathAndFilename
For an X509 login, sets the name of the RPC gem's log file.

This setting is used only by X509 logins and is cleared if traditional login parameters are set (username, password, hostusername, hostpassword, gemstone, gemnetid, or solologin).

onetimepassword

set onetimepassword onOrOff
Determines if the password supplied via set password (or queried for interactively) is a normal GemStone password or a special one-time password. When OFF, the default, the password field is interpreted as a normal GemStone password.When ON, the password field is interpreted as a onetime password.

A one-time password is a temporary password valid for a single login for a specific user ID within a specific timeout. See the System Administration Guide for more details.

netldi

set netldi: hostOrIp:portOrServiceName
Sets the host and port for the netldi to be used for X509 certificate login. The argument format must include the hostName or the IP of the NetLDI host, and the listening port number of NetLDI service name, separated by a colon character. For example,

set netldi devhost.acme.com:54321

This setting is used only by X509 logins and is cleared if traditional login parameters are set (username, password, hostusername, hostpassword, gemstone, or gemnetid).

nrsdefaults

set nrsdefaults: aNRSheader
Sets the default components to be used in network resource string specifications. The parameter aNRSheader is a network resource string header that may specify any NRS modifiers’ default values. The initial value of nrsdefaults is the value of the GEMSTONE_NRS_ALL environment variable. The Topaz status command shows the value of nrsdefaults unless it is the empty string.

password

set password: aGemStonePassword
Sets the GemStone password to be used when you next log in. If you don’t include the password argument on the command line, Topaz prompts you for it. Prompted input is taken from the terminal and not echoed. This lets you put a set password: command in your Topaz initialization file so that Topaz will automatically prompt you for your password. Note, however, that this command must follow the set username: command.

This setting is used only by traditional logins and is cleared if any X509 login parameters are set. (cert, cacert, key, netldi, logfile, directory, or extragemargs)

session

set session: aSessionNumber
Connects Topaz to the session whose ID is aSessionNumber. When you log in to GemStone, Topaz displays the session ID number for that connection. This command allows you to switch among multiple sessions. (The Topaz prompt always shows the number of the current session.)

If you specify an invalid session number, an error message is displayed, and the current session is retained.

This command clears the current class and category. After you switch sessions with set session, your local variables (created with the define command) no longer have valid definitions.

sessioninit

set sessionInit ONorOFF
Provided to allow the execution of GsCurrentSession >> initialize to be skipped during login, in the case of upgrade or other special cases in which code invoked by GsCurrentSession cannot be executed and logins cannot complete. This requies that the Stone configuration parameter STN_ALLOW_NO_SESSION_INIT be enabled, which can be done at runtime by SystemUser.

This should be left at the default, ON, except for such exceptional cases.

singlecolumn

set singlecolumn: onOrOff
When stacks are printed, methods that have more than eight method arguments and temporary variables print their variables in four columns. The default is off. After executing set solologin: on, each variable will be displayed on a single line.

solologin

set solologin: onOrOff
The argument must be a case-insensitive string, ON or OFF. When ON, subsequent logins will be Solo, using the extent0.dbf specified by the GEM_SOLO_EXTENT config item. The default is OFF.

Setting solo login to on clears the X509 parameters; only traditional logins with SET USER and SET PASSWORD settings are legal for solo login.

May be abbreviated as SOLO.

sourcestringclass

set sourcestringclass: ClassRangeSpecifier
Sets the class of strings used to instantiate Smalltalk source strings generated by the run, printit, doit, edit, method, and classmethod commands. This includes any literal strings in the evaluated code.

This command expects one argument, which must be String orUnicode16. The options are:

set sourcestringclass String
New instances of literal strings are created as instances of String, DoubleByteString, or QuadByteString.

set sourcestringclass Unicode16
New instances of literal strings are created as instances of Unicode7, Unicode16, or Unicode32.

The Topaz status command shows the current setting.

On topaz startup, sourcestringclass is set to String. On login, the setting will be updated from the setting for #StringConfiguration in the GemStone Globals SymbolDictionary. If #StringConfiguration resolves to Unicode16, then sourcestringclass will be set to Unicode16.

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

stackpad

set stackpad: anInt
Defines the minimum size used when formatting lines in a stack display. The argument anInt may be between 0 and 256, inclusive. (Default: 45)

Stackpad cannot be abbreviated.

tab

set tab: anInt
Defines the number of spaces to insert when translating a tab (CTRL-I) character when printing method source strings. The argument anInt may be between 1 and 16, inclusive. (Default: 8)

transactionmode

set transactionmode aMode
Set the current session’s transaction mode, and set the transaction mode to this mode after each subsequent login. Must be one of (case-insensitive) autoBegin, manualBegin, or transactionless.

This command does an abort. If in a transaction, any uncommitted changes in the transaction will be lost. If the new mode is autoBegin, then a new transaction will be started.

username

set username: aGemStoneUsername
Establishes a GemStone user ID for the next login attempt.

This setting is used only by traditional logins and is cleared if any X509 login parameters are set. (cert, cacert, key, netldi, logfile, directory, or extragemargs)

SHELL

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.7.0 COMMIT: 2023-07-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

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.

Example 4.1 Example of stack display

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 GsNMethod class >> _gsReturnToC              @1 line 11
    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.

 

STATUS

Displays your current login settings and other information about your Topaz session. These settings are set to default values when Topaz starts, and may be modified using the SET command, DISPLAY and OMIT, and using individual commands such as LEVEL , LIMIT, and FILEFORMAT.

For example:

topaz 1> status
 
Current settings are:
 display level: 0
 byte limit: 0 lev1bytes: 100
 omit bytes
 include deprecated methods in lists of methods
 display instance variable names
 display oops   omit alloops   omit stacktemps 
 oop limit: 0
 omit automatic result checks
 omit interactive pause on errors
 omit interactive pause on warnings
 listwindow: 20
 stackpad: 45 singlecolumn: Off  tab (ctl-H) equals 8 spaces when listing method source
 transactionmode  autoBegin
 using line editor
   line editor history: 100
   topaz input is from a tty on stdin
EditorName________ vi
CompilationEnv____ 0
Source String Class String
fileformat          utf8
SessionInit         On
EnableRemoveAll     On
CacheName_________ 'TopazR'
 
Connection Information:
UserName___________ 'Isaac_Newton'
Password __________ (set)
HostUserName_______ 'newtoni'
HostPassword_______ (set)
NRSdefaults________ '#netldi:gs64ldi'
GemStone___________ 'gs64stone'
GemStone NRS_______ '!#encrypted:newtoni@password#server!gs64stone'
GemNetId___________ 'gemnetobject'
GemNetId NRS_______ '!#encrypted:newtoni@password!gemnetobject'
 
Browsing Information:
Class_____________
Category__________ (as yet unclassified)

STEP

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 3, “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

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 GsNMethod class >> _gsReturnToC              @1 line 11

STRINGS

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

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

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

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

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 3, “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 GsNMethod class >> _gsReturnToC              @1 line 11
    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 GsNMethod class >> _gsReturnToC              @1 line 11
    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

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

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

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.

TIME

The first execution of time during the life of a topaz process displays current date and time from the operating system clock, total CPU time used by the topaz process.

Subsequent execution of time will display in addition elapsed time since the previous time command, CPU time used by the topaz process since the previous time command.

The time command can be executed when not logged in as well as after login.

Example

topaz 1> time
02/06/2023 13:37:13.545 PST
CPU time:   0.035 seconds
topaz 1> printit
Array allInstances size
%
23515
topaz 1> time
02/06/2023 13:37:48.459 PST
CPU time:   0.232 seconds
Elapsed Real time:   8.649 seconds
Elapsed CPU  time:   0.083 seconds

TMETHOD

Compile a method from tonel format used by the Rowan open source project. This is intended for interactive use.

topaz 1 > tmethod
{ #category : 'test' }
TestClass >> version[
	^5
]

This compiles the method using the class from the tonel method definition (in the example, TestClass), and using the current compilation environment. It does not affect topaz's current class.

The closing ] must be the first character on a line.

TOPAZWAITFORDEBUG

Waits forever in a sleep loop until a debugger is attached to continue execution.

This can be a C debugger (gdb, etc.), or (if configured appropriately), another topaz session attaching via debuggem.

This command should be used with caution; it may require an OS-level kill to terminate the process. Intended for use in debugging; see Debugging from a different session and the DEBUGGEM and IFERR commands.

UNPROTECTMETHODS

Cancels the effect of protectmethods, which is used for consistency checking in filein scripts.

This command cannot be abbreviated.

UP

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 GsNMethod class >> _gsReturnToC              @1 line 11
 
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 GsNMethod class >> _gsReturnToC              @1 line 11

WHERE

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 GsNMethod class >> _gsReturnToC              @1 line 11

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
 
 

Previous chapter

Next chapter