!========================================================================
! Copyright (C) GemTalk Systems 1986-2025.  All Rights Reserved.
!
! Name - topaz.hlp
!
! Description:
!  Help file for the Topaz program.  It is formatted to be processed by
!  the helputil module.
!
!        ****> WARNING
!        ****> Text lines in Help messages must be limited to 78 characters
!        ****> The Help run-times add a 2 character space preceding each line
!        ****> of text when the help message is output.
!
!        ****> Do Not use TAB characters.
!
!========================================================================

  TOPAZ - a programmer's interface to the GemStone system

  For an overview of Topaz, see the "Overview" help topic.

1 ABORT
    Equivalent to    System abortTransaction
    Executes in environment 0 .
    Aborts the current GemStone transaction.

    If your session is outside a transaction, use ABORT to obtain a new
    view of the database.
    See also SET TRANSACTIONMODE.

    Although you can abbreviate most other Topaz commands and
    parameter names, ABORT must be typed in full.

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

    Use THREAD <N> to select one of the stacks for detailed examination
    with commands such as UP , FRAME , etc .

    See also THREADS

1 BEGIN
    Equivalent to    System beginTransaction .
    Calls the abort primitive within the VM without doing any message sends.
    Begins a GemStone transaction when your session is outside a
    transaction.
    See also SET TRANSACTIONMODE.

    Although you can abbreviate most other Topaz commands and
    parameter names, BEGIN must be typed in full.

1 BREAK
    Establishes (or displays) a method breakpoint within GemStone Smalltalk
    code. For more information about breakpoints, see the Topaz manual.

    Methods can be specified using any of
       BREAK CLASSMETHOD <Class_Specification_Format> <selectorName>
       BREAK METHOD <Class_Specification_Format> <selectorName>
       BREAK CLASSMETHOD @OopOfMethod
       BREAK METHOD @OopOfMethod
       BREAK <classname> >> <selectorName>
       BREAK <classname>  class >> <selectorName>
       BREAK <classname> (Implementation CLASS) >> <selectorName>
       BREAK <classname> class (Implementation CLASS) >> <selectorName>
       BREAK @stepPoint

    These commands have an optional final @ stepPoint argument to specify
    a particular step point within the method, otherwise the break is at
    the start of the method.
    In the forms with  (Implementation CLASS) the Implementation CLASS takes
    precedence over <classname>.
    <classname> can be a name such as Dictionary or an oop such as @66817 .

    CLASSMETHOD and METHOD words cannot be abbreviated.

2 @NNN
    Example
      BREAK @6

    Set breakpoint at specified step point of the method for the frame
    selected by previous LOOKUP or LIST command in the current stack .


2 METHOD
    Establishes a method breakpoint in an instance method.
    You may set method breakpoints before "step points": assignments,
    message sends, or method returns. If you don't explicitly specify
    a step point, the breakpoint is established at step 1 of the method.
    The method is looked up using current compilation environment (see ENV).

        break method GsFile nextLine

        break GsFile >> nextLine
            Both forms of the command
            establish a breakpoint at step point 1 of the
            instance method "nextLine:" for class GsFile .

        set class String
        break method ^ < @ 2
            Establishes a breakpoint at step point 2 of the
            instance method "<" for the current class (String).

        break method @nnnn nextLine
            Establishes a breakpoint at step point 1 of the
            instance method "nextLine:" for class with objectId nnnn

        break method @nnnn
            Establishes a breakpoint at step point 1 of the
            GsNMethod with objectId nnnn

    See BREAK CLASSMETHOD for setting breakpoints on class methods.

2 CLASSMETHOD
    Establishes a method breakpoint in a class method.
    You may set method breakpoints before "step points": assignments,
    message sends, or method returns. If you don't explicitly specify
    a step point, the breakpoint is established at step 1 of the method.
    The method is looked up using current compilation environment (see ENV).

        break GsFile class >> openRead:
           Establishes a breakpoint at the start of
           class method "openRead:" for class GsFile .

        break classmethod GsFile openRead: @ 2

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

    See BREAK METHOD for setting breakpoints on instance methods.

3 Class_Specification_Formats

    You may use any of the following formats to specify the className
    parameter in the BREAK METHOD command line:

       @<integer>     an unsigned 64-bit decimal OOP value of the class
       text           the GemStone class with the specified name (either
                      a Smalltalk variable name or a local variable created
                      with the DEFINE command)
       **             the OOP of the result of the last execution
       ^              the current class

2 LIST
    Lists all currently set method breakpoints.
    For example:

        break list

        1  Method System class | performOnServer: @ 1
        2  Message PipeStream | nextPut:
        3  Method String | < @ 2      <DISABLED>

2 DISABLE

    Disables the breakpoint identified by the given index in the BREAK
    DISPLAY listing. For example:

        break list
          1     Method Object | at: @ 1
          2     Message PipeStream | nextPut:
          3     Method System class | performOnServer: @ 3

        break disable 2
          Removing break message PipeStream | nextPut:

3 ALL

    Disables all method breakpoints that are currently set.

2 ENABLE

    Reenables the breakpoint identified by the given index in the BREAK
    DISPLAY listing.

3 ALL

    Reenables all disabled method breakpoints.

2 DELETE
    Deletes the breakpoint identified by the given index in the BREAK
    DISPLAY listing. For example:

        break list display
          1     Method Object | at: @ 1
          2     Message PipeStream | nextPut:
          3     Method System class | performOnServer: @ 3

        break delete 2

        break list
          1     Method Object | at: @ 1
          2     Method System class | performOnServer: @ 3


3 ALL
    Deletes all currently set breakpoints. For example:

       break delete all

1 C
    Equivalent to CONTINUE

1 CATEGORY:
    Sets the "current category" for subsequent method compilations.
    For example:

       Category: Accessing

    To include spaces in a category name, enclose the category name
    in single quotes:

       cat 'Public Methods'

    If you compile a method without first selecting a category,
    the new method is inserted in the default category "as yet unspecified".

    If the category you name doesn't already exist, Topaz will create
    it the first time you compile a method.

    Specifying a new class with SET CLASS clears the current category.
    When you EDIT or FILEOUT a method, that method's category becomes
    the current category.

    Before you can set CATEGORY, you must be logged in to GemStone.
    The current category is cleared by the LOGOUT, LOGIN, SET CLASS,
    and SET SESSION commands.

1 CLASSMETHOD:
    Compiles a class method for the class whose name you give as a parameter.
    The class of the new method will automatically become the current class.
    If you don't supply a class name, the new method is compiled for the
    current class (as set with the SET CLASS:, FILEOUT CLASS:, METHOD:,
    or LIST CATEGORIESIN: command).

    Text of the method should follow the CLASSMETHOD: command on subsequent
    lines. The method text is terminated by the first line that starts
    with the '%' character. For example:

           CLASSMETHOD: Animal
           returnAString
              ^ String new
           %

1 COMMIT
    Equivalent to    System commitTransaction .
    Executes in environment 0 .
    Commits the current GemStone transaction.
    Although you can abbreviate most other Topaz commands and
    parameter names, COMMIT must be typed in full.
    See also SET TRANSACTIONMODE.

1 CONTINUE
    Attempts to continue GemStone Smalltalk execution on the current call stack
    after encountering a breakpoint, a "pause" message,
    or a user-defined error.

    CONTINUE
       with no arguments will attempt to continue execution using GciContinue().

    CONTINUE anObjectSpecification
       will attempt to continue execution using GciContinueWith. The
       object specified by anObjectSpecification will be used as the
       replaceTopOfStack argument to GciContinueWith.

    In a topaz session created by DEBUGGEM, CONTINUE sets waitForDebug state to 
    resume (using System __sessionStateAt: 26 put: 2) and that topaz -r stays 
    attached. 
    System class >> waitForDebug will exit and execution will continue .

    For more information about breakpoints, see the Help information
    for the BREAK command.

    For information about Object's "pause" method, see the protocol for
    Object in the image.

    For information about user-defined errors, see the chapter/s on error
    handling in the "GemStone Programming Guide".

    See also Object_Specification_Formats

1 DEBUGRUN

    Like RUN , but sets the GCI_PERFORM_FLAG_SINGLE_STEP flag for the
    GciExecuteDbg_ used to start the execution of the source text.
    Execution will stop at the first step point within the source text.
    DEBUGRUN cannot be abbreviated .

1 DEFINE
    Defines local variables for use in SEND, OBJECT, and other commands.

    DEFINE aVar anObjSpec aSelectorOrArg ...
       sends a message to the object "anObjSpec", and saves the result
       as a local variable with the name "aVar". For example:
          DEFINE UserProfile System myUserProfile
       The message send is done in the current compilation environment.

    DEFINE aVar anObjSpec
       define a local variable whose value is result of an object specification
       example: define UG UserGlobals

    DEFINE aVar    deletes the definition of the variable "aVar".

    DEFINE         lists all current local variable definitions.

    If you abort your transaction, or if you switch sessions with SET
    SESSION, your local variables may no longer have valid definitions.

    The variable name "aVar" must begin with a letter (a...z) or an
    underscore, can be up to 255 characters in length, and cannot contain
    white space.
    See also Object_Specification_Formats

2 Examples
      DEFINE var1 **      saves the last result in local variable "var1".

      DEFINE var2 var1 entryAt: 4
        sends "entryAt:" to the object named "var1" (in this case
        a local variable defined on the previous line) and saves the
        result in the local variable "var2".

      DEFINE var3 1.444 * 47e32
        sends "*" to the float object "1.444" with arg "47e32"
        and saves the result in the local variable "var3".

      DEFINE              displays all current local variable definitions.

      DEFINE var3         removes the definition of "var3".

1 DETACH

   In a topaz session created by DEBUGGEM, does a GciLogout .
   The gem or topaz -l being debugged remains waiting in
     System class >> waitForDebug
   and can be attached to again with a subsequent DEBUGGEM .

1 DISPLAY

    The DISPLAY and OMIT commands control the display and behavior of
    a number of topaz commands. Individual features default to either OMIT
    or DISPLAY; each one can be explicitly turned on using DISPLAY or turned
    off using OMIT.

    Display subcommends controls how instance variable names, hexadecimal
    byte values, and OOPs are displayed.

2 ALLOOPS

    DISPLAY ALLOOPS sets DISPLAY OOPS and also enables oops of classes
    to be printed in object display, along with the class names.
    Also prints oops of certain special objects (SmallIntegers, Characters,
    true/false/nil), that normally do not display their oops.

    DISPLAY ALLOOPS also causes oops of methods to be printed by stack
    display and  method lookup commands, and enables printing of the
    evaluation temps in stack frame printouts from FRAME command.

2 BYTES
    After you issue the DISPLAY BYTES command, the display for each byte format
    object will include the hexadecimal value of each byte.
    DISPLAY BYTEVALUES is equivalent to DISPLAY BYTES .

2 CLASSOOPS

    Legacy; equivalent to DISPLAY ALLOOPS

2 DECIMALBYTES
   The display for each byte format object will include decimal value of each byte.

2 ERRORCHECK

    Same as RESULTCHECK, except that there is no implied
      expectvalue true
    prior to "run" or "doit" commands.

2 DEPRECATED

    For topaz commands such as STRINGS, SENDERS,  which return lists of
    methods  DISPLAY DEPRECATED causes those results to include
    methods which contain sends of any methods
    implemented in Object in  category 'Deprecated Notification' .

2 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.
    The default is equivalent to OMIT FLUSHOUTPUT.

2 LINEEDITOR
    enables use of the built-in line editor . Not available on Windows .
    The built-in line editor is enabled by default on Unix.
    On Windows if topaz is run in a Command Prompt window, that
    window provides a line editor in front of the topaz stdin.
    On Windows, in a Cygwin shell, line editor is not available.

2 NAMES
    For each of an object's named instance variables, displays the instance
    variable name along with its value. (This is the default condition.)
    To turn off this display, use the OMIT NAMES command.

    When instance variable name display is off, named instance
    variables appear as 'i1', 'i2', 'i3', etc.

2 OOPS
    DISPLAY OOPS causes the OOPS of objects to be displayed, with the
    exception of certain special objects (SmallIntegers, Characters,
    true/false/nil).

    For each object (other than the specified specials) a header is displayed
    containing the object's OOP (a 64-bit unsigned integer), the object's size
    (the sum of its named, indexable, and anonymous instance variable fields),
    and the name (but not the OOP) of the object's class.

    See also DISPLAY ALLOOPS, which enables display of the OOPs of all specials
    and the OOPs of classes.

2 ORIGIN
    DISPLAY ORIGIN causes the origin of a method to be displayed after the 
    method source. The origins of a method may be the CLASS, a TRAIT, or 
    ROWAN. No additional information is displayed if the origin of the 
    method is a CLASS. If the origin is a TRAIT, the name of the TRAIT is
    displayed. If the origin is ROWAN, the name of the Rowan project and 
    Rowan package are displayed.

2 PAUSEONERROR,

    DISPLAY PAUSEONERROR causes the following behavior:

    When an error occurs, and if the topaz stdin is from a terminal,
    then write a message "Pausing after error ..."
    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.

    If DISPLAY RESULTCHECK is also active, then
       "When an error occurs"
    is interpreted as
       "When a result or error is contrary to the
        current RESULTCHECK, EXPECTVALUE, and EXPECTERROR settings"

    DISPLAY PAUSEONERROR has no effect if stdin is not a terminal.
    Use OMIT PAUSEONERROR to cancel this pause-on-error mode.

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

    DISPLAY PAUSEONWARNING has no effect if stdin is not a terminal.

2 PUSHONLY
    Enables the effect of the 'ONLY' keyword in an OUTPUT PUSH command.
    Has no effect on output to stdout from within a topaz -S script.
    Default state is DISPLAY PUSHONLY.

2 RESULTCHECK

    The topaz command DISPLAY RESULTCHECK will cause a file
    ./topazerrors.log to be created. If the file already exists, it
    will be opened for append.

    When DISPLAY RESULTCHECK has been specified,
       a) The default behavior of all "run" commands will be equivalent to
            expectvalue true
            run
            %

       b) Every time ErrorCount is incremented, a log record will be
       appended to  topazerrors.log , giving a summary of the error, and
       the line number in the topaz output file, if possible. If the
       only output file open is stdout, then line numbers are not available.

    The OMIT RESULTCHECK command will close the file  topazerrors.log.
    If OMIT RESULTCHECK has been specified, then only an explicit
    EXPECTVALUE or EXPECTBUG command will cause non-error results of
    a run command to be checked.

    If the environment variable GS_TOPAZ_AUTO_RESULTCHECK is defined in topaz's
    environment,  then after reading any .topazini file , and after each INPUT
    statement,   DISPLAY RESULTCHECK is automatically executed , and 
    when the end of an input file opened by INPUT is reached, the 
    state of RESULTCHECK and ERRORCHECK reverts to the states from before that INPUT.
    The value of GS_TOPAZ_AUTO_RESULTCHECK is read from the environment after 
    reading .topazini, and at each INPUT statement.

    hostagent and topaz processes running the various hostagent processes ignore
    GS_TOPAZ_AUTO_RESULTCHECK .

    If -P was on the topaz command line and GS_TOPAZ_ERROR_LOG_WITH_PID is defined in the environment
    topazerrors.<pid>log is used for the name of the error file, where pid is processId of the topaz.

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

2 VERSIONEDCLASSNAMES
    Use  Object >> describe for names of classes when printing objects.

2 ZEROBASED
    Show offsets of instVars zero-based instead of the default one-based
    when displaying objects with structrual access, using the OBJECT command.

1 DISASSEM

    Disassemble the specified GsNMethod, printing bytecodes of the method.
    Intended for use in a linked  (topaz -l) session only.
    In a remote (topaz -r) session output goes to the gem log file.

    DISASSEM with no arguments will disassemble the currently selected
    stack frame, as selected by a previous UP, DOWN, or FRAME command .

       DISASSEM @<integer>
         Disassemble the method or code object with specified oop.

       DISASSEM METHOD: <selectorSpec>
         Disassemble the specified instance method for the class previously
         set by the SET CLASS command.
         Method lookup uses current compilation environment (see ENV).

       DISASSEM CLASSMETHOD: <selectorSpec>
         Disassemble the specified class method for the class previously
         set by the SET CLASS command.
         Method lookup uses current compilation environment (see ENV).

    See <selectorSpec> in Object_Specification_Formats

1 DOIT

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

    doit
     2 + 1
     %
     3

    The result is displayed as if LEVEL 0 were the last LEVEL command,
    but without altering the display level used by other commands.

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

1 DOWN

    DOWN -- In the current stack, change the current frame
    to be the callee of the current frame, and display the
    frame thus selected.

    DOWN <anInteger> -- Go down anInteger frames and display
    the frame thus selected.

1 DUMPOBJ

    DUMPOBJ <anObjectSpecification>
    Low-level dump of an object
    or node of a large object or node of an IdentityBag.
    For a byte format object displays the integer values of the bytes.
    See also  Object_Specification_Formats . cannot be abbreviated

1 EDIT
    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 interactively or in your Topaz initialization
    file with the Topaz SET EDITORNAME command. Method text is stored in
    a temporary file while you are editing.

    Do not use the EDIT command for batch processing.
    Use the METHOD: and CLASSMETHOD: commands to create methods, and the RUN,
    PRINTIT or DOIT commands for executing blocks of code in batch processes.

    Edit has several forms
      EDIT <classname> >> <selectorSpec>
      EDIT <classname> class >> <selectorSpec>
      EDIT LAST

    Legacy forms are
      SET CLASS <className>; EDIT NEW
      SET CLASS <className>; EDIT <selector>
      SET CLASS <className>; EDIT METH <selector>
      SET CLASS <className>; EDIT CLASSMETH <selector>

2 LAST
    Tells Topaz that you want 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.

    When you exit the editor, Topaz will ask whether to compile and
    execute the altered code. If you tell Topaz to execute the code,
    it will effectively reissue your RUN command with the new text.

2 NEW
    Tells Topaz that you want to create either a new method or a chunk
    of GemStone Smalltalk code for execution. Before you can create new
    methods, you must first use SET CLASS to select a current class. If you
    haven't yet selected a current category, the new method is inserted in
    the default category "(as yet unspecified)".

    Any of the following subcommands are valid. If you simply type
    EDIT NEW (with no additional keywords), Topaz will assume that you
    want to create a new instance method for the current class.

3 METHOD
    Allows you to create a new instance method for
    the selected class and category.

3 CLASSMETHOD
    Allows you to create a new class method for the
    selected class and category.

3 TEXT
    Allows you to create a new chunk of GemStone Smalltalk code for
    compilation and execution as a DOIT

2 CLASSMETHOD:
    Allows you to edit the source code of an existing class method. The
    selector of the method is a <selectorSpec> parameter.
    Method lookup uses current compilation environment (see ENV).

    For example to edit  OfsDirectory(class)>>new

        topaz> set class OfsDirectory
        topaz> edit classmethod new

    Before you can use this command, you must first use SET CLASS
    to select the "current" class. The category of the method you edit
    will automatically be selected as the current category.
    See <selectorSpec> in Object_Specification_Formats

2 METHOD:
    Allows you to edit the source code of an existing instance method.
    The selector of the method is a <selectorSpec> parameter.
    Method lookup uses current compilation environment (see ENV).

    Before you can use this command, you must first use SET CLASS
    to select a "current" class. The category of the method you edit
    will automatically be selected as the "current" category.
    See <selectorSpec> in Object_Specification_Formats

1 ENV
    With one argument, an integer >= 0 and <= 255,
    sets the compilation environmentId for subsequent compilations,
    executions (RUN, DOIT, SEND), and ClassOrganizer operations
    (SENDERS, STRINGS, STRINGSIC, SUBCLASSES   SUBHIERARCHY,
     HIERARCHY, IMPLEMENTORS , LOOKUP)
    With one argument, equivalent to  SET COMPILE_ENV: .

    With zero arguments, prints the current compilation environmentId.

1 ERRORCOUNT
    Displays the topaz ErrorCount variable.

    Equivalent to
        OBJECT ErrorCount
    except that ERRORCOUNT does not require a valid session.

    The C function TpAuxIncErr() is called each time ErrorCount
    is incremented. Set a C debugger breakpoint in TpAuxIncErr()
    if you want to stop an any error other than those expected via
    EXPECTERROR .

1 EXEC
    Similar to RUN except for handling of remainder of command line.

    Text after 'EXEC ' up to the first % on the command line
    is taken as execution source without regard to any quotes.
    The text after the % is parsed as additional commands.

    If there is no % on the command line,
    subsequent lines are appended to execution source and
    execution source is terminated by a line containing % as the
    first character.
    Execution semantics and result display are the same as RUN.
    Uses current compilation environment (see ENV).

1 EXIT
    Terminates Topaz, returning to the parent process or operating system.
    If you are still logged in to GemStone when you type EXIT, this will
    abort your transaction and log out all active sessions.
    Although you can abbreviate most other Topaz commands and
    parameter names, EXIT must be typed in full.

    If an EXIT is encountered in a input file when stdin is interactive 
    (that is, is a tty), EXIT does not exit topaz. If topaz was invoked 
    with -P , and the EXIT is in an input file other than the one specifed 
    as the argument to -P (such as nested input files), then a topaz error 
    is signalled; otherwise, a warning is printed. In both cases, input 
    processing continues.

    If this command has a argument and it is an integer, then
    the integer is used as the exitStatus. If the status argument is an
    object specification that resolves to an integer, then that value
    is used as the exitStatus. Only 8 bits of the integer are returned,
    exitStatus should be 0..255. If it is not an integer then an error
    is returned and the process does not exit.

    If the command does not have an argument, the exitStatus will
    be either 1 if there were GCI errors or the topaz errorcount is not zero,
    or 0 if no errors had occurred.

    If topaz stdin is redirected to a file and the file does not end with
    a QUIT or EXIT command, topaz considers EOF on stdin to be an error,
    that contributes to non-zero exit status of topaz.

    In a topaz session created by DEBUGGEM, equivalent to DETACH .

    See also QUIT.

1 EXITIFNOERROR
    if ERRORCOUNT would return 0 , same as EXIT 0
    else has no effect.

1 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) and that
       it is a known bug. <bugNumber> is the bug number assigned to
       this bug. A result value is specified as in the expectvalue
       command and a result error is specified as in the expecterror
       command.

       The topaz variable ErrorCount is incremented.

  This command is normally used immediately prior to commands
     printit, doit,  method, classmethod, commit, send

  See also   Object_Specification_Formats
             EXPECTVALUE
             EXPECTERROR

1 EXPECTERROR
    expecterror <errCategory> <errNumCls> [ <resultSpec> [ <resultSpec>]..]

    This command specifies that the result of the following compilation
    or execution must be the specified error.

      <errCategory> must be a legal topaz object specification which
         evaluates to  the object identifier of an error category.

      <errNumCls> must be a legal topaz object specification
         which evaluates to a SmallInteger , or to a subclass of AbstractException

      <resultSpec> specify the required error arguments using the same
      rules as described for <resultSpec> under "expectvalue" command

    If the result of the compilation or execution is not the expected
    error, the topaz variable ErrorCount will be incremented.

    Limitations of  expecterror:
    There is no checkint for argument values for fatal errors.

    Checking for number of arguments is limited. If you care about the
    number of arguments, then you should give that many <resultSpec> tokens
    in the expecterror command. If you don't care at all about the class
    of the arguments then specify "%Object"  for each argument.
    ErrorCount will be incremented if the actual error contains fewer
    arguments than were specified in the "expecterror" command.
    ErrorCount will NOT be incremented if the actual error contains more
    arguments than were specified in the "expecterror" command.

    This command is only meaningful immediately prior to commands
    printit, doit,  method, classmethod, commit, send

    Up to 5 "expecterror" or "expectvalue" commands may precede an execution
    command. If the result of execution satisfies any one of them, the ErrorCount
    variable will not be incremented.

    See also Object_Specification_Formats

1 EXPECTVALUE
    expectvalue <resultSpec> [ <integer> ]

    If <resultSpec> is <objInstanceOfSpec> then the result of the following
    execution must be an instance of <objInstanceOfSpec>.
    If <resultSpec> is <literalObjectSpec> then the result of the
    following execution must be = <literalObjectSpec>. This = test is done
    by using GciPerform to send #=  to the result.
    Otherwise, the result of the following execution
    must be == <resultSpec>.

       <integer>, if present, specifies the required result of sending
       the method #size to the object satisfying <objDesc>

       If the result does not satisfy the expected result, the topaz
       variable ErrorCount is incremented.

    This command is normally used immediately prior to commands
    printit, doit,  method, classmethod, commit, send

    The commit command has an internal result of  true  for success and
    false for failure.

    The set session command has an internal result of  true  for success,
    and the error encountered for failures.

    The object command has an internal result of true unless immediately
    preceded by explicit expectvalue or expecterror commands, in which case
    the internal result is the object displayed or the error encountered.

    All other topaz commands will have an internal result of true for
    success or @0 for failure

    Up to 5 "expecterror" or "expectvalue" commands may precede an execution
    command. If the result of execution satisfies any one of them, the
    ErrorCount variable will not be incremented.

    See also Object_Specification_Formats

1 FILEFORMAT

    Expects one string argument which must be UTF8 or 8BIT .
    8BIT means that topaz input is interpreted
    as 8 bit Ascii.
    UTF8 means that topaz input is interpreted as UTF8 encoded data.

    The default at topaz startup is 8BIT ,

    Input from stdin that is a tty is always interpreted as UTF8.
    Attempts to change the FILEFORMAT of a tty stdin to 8BIT are ignored.

    A FILEFORMAT command read while topaz is processing its initialization file
    (.topazini on Unix,  topaz.ini on Windows) is remembered and becomes the
    default for input files read after the initialization file is completed,
    and is also used as the mode for the remainder of the file which contained that
    FILEFORMAT command.

    A FILEFORMAT command within a file not read during the "initialization file"
    only has effect within that file and any nested files.

    If topaz is still using the built-in default of
      set sourcestringclass String
    then a topaz login which detects StringConfiguration == Unicode16 in the
    repository will change  fileformat to UTF8 and sourcestringclass to Unicode16 .
    If initialization file contains  FILEFORMAT UTF8 then
    a login which detects StringConfiguration==String will not change
    the topaz fileformat .

    Note that files written by topaz OUTPUT PUSH" are always UTF8,
    so if you edit an output file to make it into a file for INPUT ,
    you may need to add a FILEFORMAT UTF8 command at the start of the input file.

1 FILEOUT
    Writes class definitions and/or methods to a named file in a format
    that can be fed back into Topaz with the INPUT command.

    If the current compilation environment(see ENV) is 0 ,
    fileout of a class will include the definition of the class
    and methods in environment 0 .
    If the compilation environment is non zero, fileout of a class
    will include the alternate superclass for that environment, if any,
    and methods defined in that environment.

    If you supply a parameter that does not match one of the FILEOUT
    sub-commands, Topaz will assume it is a method selector for the
    selected class and will attempt to file it out.

    Examples:
      fileout class: Object tofile: object.gs format: 8bit

      set class Unicode16
      fileout category: 'Instance Creation' tofile: u16.gs format: utf8

    Keyword arguments must be provided in this order
       exactly one of     CLASS: CATEGORY: CLASSCATEGORY: METHOD: CLASSMETHOD:
       optional           TOFILE:
    If TOFILE: was given, then it may be followed by an optional  FORMAT:

    If the format: is omitted output it is controlled by the last FILEFORMAT.
    A FILEFORMAT command reflecting the way output was generated
    is written as the first line of the output file.

2 TOFILE:
    The output of the FILEOUT command is sent to the file that you name
    following the TOFILE: keyword. For example:

        fileout class: Object tofile: object.opl

    If you specify a host environment name such as $HOME/foo.bar in UNIX
    as the output file, Topaz will expand that name to the full filename.

    If the output file does not contain an explicit path specification, Topaz
    writes to the named file in the directory in which you started Topaz.

    If the filename begins with '&' , the '&' is discarded and output
    is appended to the specified file, otherwise the specified file
    is overwritten.

2 FORMAT:
    Overrides the current FILEFORMAT setting . Argument must be
    a string, either UTF8 or 8BIT . The FORMAT: keyword must
    be after a TOFILE: keyword.
    Example:
      fileout class: Object tofile: object.gs format: 8bit

2 CLASS:
    Writes out the class definition and all the method categories
    and their methods. The class that you file out will be selected
    as the current class for use with other Topaz commands.
    Example:
      fileout class: Object tofile: object.gs

    To write out the definition of the current class, type:

        fileout class: ^

2 CATEGORY:
    Writes out all the methods contained in the named category
    for the current class.
    Example
      set class Unicode16
      fileout category: 'Comparing' tofile: u16.gs format: utf8

2 CLASSCATEGORY:
    Writes out all the class methods contained in the named category
    for the current class.
    Example:
      set class Unicode16
      fileout classcategory: 'Instance Creation' tofile: u16.gs format: utf8

2 CLASSMETHOD:
    Writes out the specified class method (as defined for the current
    class). The category of that method is automatically selected
    as the current category for use with other Topaz commands.
    Method lookup uses current compilation environment (see ENV).
    Example:
      set class Unicode16
      fileout classmethod: _unicodeCompareEnabled

2 METHOD:
    Writes out the specified method (as defined for the current class).
    The category of that method is automatically selected as the current
    category for use with other Topaz commands.
    Method lookup uses current compilation environment (see ENV).
    Example:
        set class Unicode16
        fileout method: speciesForPrint

    You may omit the "METHOD:" keyword if the method selector does not
    conflict with any of FILEOUT's subcommands. For example, to file
    out a method named "category:", you'd need to explicitly include the
    METHOD: keyword as shown here:

        fileout method: category:

1 FR_CLS
    like FRAME, but turns on DISPLAY ALLOOPS for display of
    the specified stack frames

1 FR_1
    like FRAME, but displays stack temps one per line in the frame

1 FRAME
    FRAME  displays current frame of current stack, with temps

    FRAME  <anInteger> goto specified frame in current stack,
    and make the specified frame the current frame and
    display that frame with temps. Similar to "STACK SCOPE <anInteger>".

1 GCITRACE
     GCITRACE 'filename'

     Turns GCI tracing on. If filename is '' then turns it off.
     If it is already off then '' turns it on to stdout.

1 HELP
    Displays help about the commands Topaz recognizes.
    Enter ? at a help prompt for a list of topics available
    at that level of the hierarchy. Help topics can be
    abbreviated to uniqueness.

     Examples:
        help edit last      displays help text for 'last'.
        help fileout        displays help text for 'fileout'.

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

1 HIERARCHY
      HIERARCHY [ envIdInteger ]
        prints the class hierarchy up to Object for the current class,
        and specified environment. If envIdInteger argument is not present,
        uses current compilation environment.

      HIERARCHY <className> [ envIdInteger ]
        prints the class hierarchy up to Object for the specified class.
        If envIdInteger argument is not present, uses current
        compilation environment.

    The result is obtained from  Class>>hierarchy .

1 HISTORY
      HISTORY [ anInteger ]

    Print the last <anInteger> entries in the topaz line editor
    history. Has no effect if the line editor is not enabled.
    See also DISPLAY LINEEDITOR, OMIT LINEEDITOR .
    Not available on Windows .

1 IFERR
    There are 10 post-error command buffers accessible by the IFERR command.

     IFERR N <remainder of line>
       The remainder of the command line following the integer N token
       is saved as an unparsed command line in the specified
       post-error buffer.

     IFERR N
       If integer N is the last token on the line clears the specified
       post-error buffer.

    Whenever an error occurs (other than one matching an "expecterror"
    command and other than one during parsing of the IFERR command),
    or, whenever a result fails to match an "expectvalue" command,
    or, whenever a result matches an "expectbug" command, 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.

    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,  such as
         iferr 3 exit
    Then buffers 4..10 will have no effect.

    If a post-error buffer contains a command that would terminate
    the session, such as
        iferr 2 logout
    then execution of buffers 3..10 will be attempted but they
    will not have a session (unless buffer 3 contains "login").

    One of the most useful forms of this command is
        iferr 1 where
        iferr 2 stack

    See also IFERR_LIST, IFERR_CLEAR .

1 IFERR_CLEAR
    Clears all of the post-error command buffers.

1 IFERR_LIST
    Prints all of the non-empty post-error command buffers.
    See also IFERR .

1 IFERROR
     IFERROR <remander of line>
       Equivalent to IFERR 1 <remainder of line> ,
       saves remainder of line> in post-error buffer 1 .

     IFERROR
       with no non-blank characters after IFERROR ,
       Equivalent to IFERR 1 , clears post-error buffer 1 .

     See help for IFERR for more information

1 IMPLEMENTORS
    Expects one argument, an selectorSpec, the value of which
    is either a String or Symbol .

    Equivalent to a DOIT of
      (ClassOrganizer newForEnvironment: <current env>) implementorsOfReport: aString
    which reports implementors of (aString asSymbol)
    for the current compilation environment  (See ENV) .
    May require larger than default GEM_TEMPOBJ_CACHE_SIZE configuration.
    See <selectorSpec> in Object_Specification_Formats
    DEFINE CurrentClassOrganizer  will override the class organizer used.

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

    Reads input from the named file. (The current input file is pushed
    onto a stack.)  There is a limit of 20 nested INPUTs. When that limit
    is exceeded, an error will be displayed, and execution will
    proceed in the current file. With each level of input, the topaz
    cursor adds + to indicate the current nesting level.

    If the fileName includes a host environment name, it is expanded to
    the full filename before the INPUT command is carried out.

    If you don't provide an explicit path specification, Topaz looks for
    the named input file in the directory in which you started Topaz.

    The file will be interpreted as 8Bit or UTF-8 per an explicit
    FILEFORMAT command in the file, or the current FILEFORMAT setting
    in topaz.

2 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 will once
    again take its input from stdin.

1 INSPECT
    Return a displayable respresentation of the argument, which must be
    an object specification.
    Equivalent to
        SEND <object> describe
    using current compilation environment.

1 INTERP

    Same as RUN, but do the execution in intepreted mode always.
    RUN defaults to using native code, unless GEM_NATIVE_CODE_ENABLED=FALSE,
    or unless any breakpoints are set .
    Uses current compilation environment (see ENV).

1 INTERPENV
    Same as RUNENV, but do the execution in intepreted mode always.
    Takes one integer argument >= 0 and <= 255 ,
    specifying compilation environment for the code to execute in.

1 KILL
    In a topaz session created by DEBUGGEM , causes the gem or topaz -l  
    being debugged to exit by signalling a ExitClientError
    and does a kill of the gem being debugged

1 L
    Allowed as abbreviation for LISTW, if topaz has a valid session.

1 LEVEL
    Sets the Topaz display level; that is, this command tells Topaz how
    much information to include in the result display. A level of 1
    means that the first level of instance variables within
    a result object will be displayed. Similarly, a level of 2 means
    that Topaz will display the variables within each of those variables.
    Setting the level to 0 (the default) will inhibit the display of
    objects. (However, object headers will still be displayed if you
    specify DISPLAY OOPS.)
    The maximum display level is 10000, default is 0 .
    Attempting to set the level to less than 0 generates an error.
    Level also controls display of method args and temps in the WHERE
    and ALLSTACKS commands, level 1 displays method args and temps,
    level 2 will also display instVars of each method arg and temp .

1 LIMIT
    Tells Topaz how much of any individual object to display.

    For example, a limit of 80 tells Topaz to display no more than 80 bytes
    (or OOPs) of any object. The default limit of 0 tells Topaz not to
    limit the size of output.

       limit oops 100
           Tells Topaz to display no more than 100 OOPs of any oop or
           NSC format object.

       limit bytes 40
           Tells Topaz to display no more than 40 bytes of any byte
           format object  .

       limit 40
           Equivalent to    limit bytes 40

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

       limit lev2oops 5
           When LEVEL is set to 2 or greater, or OBJ2 is used, this limit controls
           how many oops to display of instVar values .

1 lineeditor
   see DISPLAY LINEEDITOR

1 LIST
     This command is used in conjunction with the SET and EDIT commands
     to browse through dictionaries, classes, and methods in the database.

     The LIST command is also useful in debugging your Smalltalk code.
     LIST with no arguments will list the source code for the currently selected
     stack frame, as selected by a previous LOOKUP, UP, DOWN, or FRAME command.
     See also LISTW.

     If the "origin" of the method for the currently selected stack frame is a
     trait, the name of the trait will be listed along with the method source.

     If the "origin" of the method for the currently selected stack frame is a 
     Rowan Loaded Method, the package name of the loaded method will be 
     displayed.

2 @NNN
    list source code of the GsNMethod or ExecBlock with specified objectId .

2 DICTIONARIES
    Lists the SymbolDictionaries in your GemStone symbol list. This command
    executes the GemStone Smalltalk expression
        GsSession currentSession symbolList namesReport

2 CLASSES
    Lists all of the dictionaries in your symbol list and all of the classes
    they contain.

    Takes an optional argument aString, if given, limit the result to
    those classes for which  (aClass name includesString: aString)==true.
      example  LIST CLASSES Err


2 CLASSESIN:
    Lists the classes in a specific dictionary. For example:

       list classesin: UserGlobals

    LIST CLASSES is the form for all dictionaries.

2 CATEGORIESIN:
    Lists all of the instance and class method selectors for the named
    class, by category, in the current compilation environment(see ENV).
    If you do not specify a class name, the categories
    of the current class will be listed. If you do specify a class name,
    that class becomes the current class for subsequent Topaz commands.
    (The current class is also set with the SET CLASS:, FILEOUT CLASS:,
    or METHOD: command.)

2 CCATEGORIES:
    Lists all of the class method selectors for the named
    class, by category, in the current compilation environment(see ENV).
    If you do not specify a class name, the categories
    of the current class will be listed. If you do specify a class name,
    that class becomes the current class for subsequent Topaz commands.

2 CLASSMETHOD:
    With an argument that is a <selectorSpec> ,
    lists the category and source of the given classmethod selector for
    the current class in the current compilation environment(see ENV).
    (The current class is set with the SET CLASS:,
    FILEOUT CLASS:, METHOD:, or LIST CATEGORIESIN: command) .
    See <selectorSpec> in Object_Specification_Formats

2 CMETHOD:
    LIST CMETHOD: is equivalent to LIST CLASSMETHOD:
    Uses current compilation environment(see ENV).

2 CSELECTORS
    List selectors of all class methods in the current compilation
    environment(see ENV). May be abbreviated as CSEL .
    Accepts an optional string token, example:   LIST CSEL policy
    lists only selectors which contain 'policy' using case-insensitive match.

2 CPRIMITIVES
    List selectors of all class methods in the current compilation
    environment(see ENV) which are primitives, May be abbreviated as CPRIM .
    Accepts an optional string token, example:   LIST CPRIM at
    lists only selectors which contain 'at' using case-insensitive match.

2 ICATEGORIES:
    Lists all of the instance method selectors for the named
    class, by category, in the current compilation environment(see ENV).
    If you do not specify a class name, the categories
    of the current class will be listed. If you do specify a class name,
    that class becomes the current class for subsequent Topaz commands.

2 IMETHOD:
    LIST IMETHOD: is equivalent to LIST METHOD:
    Uses current compilation environment(see ENV).

2 LINENUMBERS
    List the current method with line numbers prefixed to the source lines.
    The current method is the method of the last frame selected in the
    current stack (last UP, DOWN or FRAME),
    or the method specified by the last LOOKUP command .

2 METHOD:
    With an argument that is a selector, lists the category and source of
    the given instance method selector in the current class and current
    compilation environment (see ENV).
    (The current class is set with the SET CLASS:,
    FILEOUT CLASS:, METHOD:, or LIST CATEGORIESIN: command.)

    Example 2
       set class Object
       list method doesNotUnderstand:

    If the "origin" of the method is a Trait, the name of the trait will be
    displayed.

    If the "origin" of the method is a Rowan Loaded Method, the package name 
    of the loaded method will be displayed.

2 PRIMITIVES
    List selectors of all instance methods in the current class and
    compilation environment(see ENV)  which are primitives.
    May be abbreviated as PRIM .
    Accepts an optional string token, example:   LIST PRIM at
    lists only selectors which contain 'at' using case-insensitive match.

2 SELECTORS
    List selectors of all instance methods in the current class and
    compilation environment(see ENV). May be abbreviated as SEL .
    Accepts an optional string token, example:   LIST SEL policy
    lists only selectors which contain 'policy' using case-insensitive match.

2 STEP
    Lists the source code of the current frame within the current stack and
    displays just the step point corresponding to the step point of the
    selected frame.

    See FRAME to select a frame within a stack

3 METHOD:
    Lists the source code of the specified instance method for the current
    class, and displays all step points (allowable breakpoints) in that
    method. The token after METHOD: is a <selectorSpec>,
    current compilation environment (see ENV) is used to lookup the method.
    You can use the BREAK METHOD command to set method breakpoints
    at any step point.
    See <selectorSpec> in Object_Specification_Formats

3 CLASSMETHOD:
    Lists the source code of the specified class method for the current
    class, and displays all step points (allowable breakpoints) in that
    method. The token after CLASSMETHOD: is a <selectorSpec> ,
    current compilation environment (see ENV) is used to lookup the method.
    You can use the BREAK METHOD command to set method breakpoints
    at any step point.
    See <selectorSpec> in Object_Specification_Formats

2 STEPIPS
    Lists the source code of the current frame within
    the current stack and displays IPs of all step points in that source code.

    See STACK SCOPE or FRAME to select a frame within a stack.

3 METHOD:
    Lists the source code of the specified instance method for the current
    class, and displays the IPs of all step points in that
    method. The token after METHOD: is a <selectorSpec>,
    current compilation environment (see ENV) is used to lookup the method.
    You can use the BREAK METHOD command to set method breakpoints
    at any step point.
    See <selectorSpec> in Object_Specification_Formats

3 CLASSMETHOD:
    Lists the source code of the specified class method for the current
    class, and displays the IPs of all step points in that
    method. The token after CLASSMETHOD: is a <selectorSpec> ,
    current compilation environment (see ENV) is used to lookup the method.
    You can use the BREAK METHOD command to set method breakpoints
    at any step point.
    See <selectorSpec> in Object_Specification_Formats

2 STEPS
    Lists the source code of the current frame within
    the current stack and displays all step points in that source code.

    See FRAME to select a frame within a stack.

3 METHOD:
    Lists the source code of the specified instance method for the current
    class, and displays all step points (allowable breakpoints) in that
    method. The token after METHOD: is a <selectorSpec>,
    current compilation environment (see ENV) is used to lookup the method.
    For example:

         list steps method: habitat

    You can use the BREAK METHOD command to set method breakpoints
    at any step point.
    See <selectorSpec> in Object_Specification_Formats

3 CLASSMETHOD:
    Lists the source code of the specified class method for the current
    class, and displays all step points (allowable breakpoints) in that
    method. The token after CLASSMETHOD: is a <selectorSpec> ,
    current compilation environment (see ENV) is used to lookup the method.

    You can use the BREAK METHOD command to set method breakpoints
    at any step point.
    See <selectorSpec> in Object_Specification_Formats

2 STEPIPS
    Lists the source code of the current frame within
    the current stack and displays IPs of all step points in that source code.
    If there is no current frame, lists source code of the last method
    selected with LOOKUP

    (See FRAME to select a frame within a stack).

2 BREAKS
    Lists the source code of the current frame,
    and displays step points for method breakpoints currently set in
    that method. Disabled breakpoints are displayed with their respective
    step point number negated.

    You can use the BREAK LIST command to list all currently set
    breakpoints. For more information about using breakpoints,
    see the Help information for BREAK, or the discussion of debugging
    in Chapter 2 of the Topaz manual.

3 METHOD:
    Lists the source code of the specified instance method for the current
    class, and displays the method breakpoints currently set in that method.
    The token after METHOD: is a <selectorSpec> ,
    current compilation environment (see ENV) is used to lookup the method.
    See <selectorSpec> in Object_Specification_Formats

3 CLASSMETHOD:
    Lists the source code of the specified class method for the current
    class, and displays the method breakpoints currently set in that method.
    The token after CLASSMETHOD: is a <selectorSpec> ,
    current compilation environment (see ENV) is used to lookup the method.
    See <selectorSpec> in Object_Specification_Formats

1 LISTW
    For the method implied by the current stack frame
    list a maximum of WindowSize lines centered around current IP for the frame.
    WindowSize is set by SET LISTWINDOW .
    If topaz has a valid session, then LISTW is abbreviatable as L .

1 LITERALS
    Expects one argument, an Object, typically a String, Symbol, or Number.
    Equivalent to a DOIT of
       (ClassOrganizer newForEnvironment: <current env>) literalsReport: anObject
    which reports methods in the current compilation environment (see ENV)
    containing anObject as a literal reference in their source string  .

    May require larger than default GEM_TEMPOBJ_CACHE_SIZE configuration.
    See <selectorSpec> in Object_Specification_Formats
    DEFINE CurrentClassOrganizer  will override the class organizer used.

1 LOADUA
    LOADUA filename

    Loads the application user action library specified by 'filename'.
    Must be used before LOGIN.

1 LOGIN
    Lets you log in to a GemStone database. Before you issue the LOGIN
    command, 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 classic userId/password login
    are:

        SET HOSTUSERNAME:   Your user account on the host computer
        SET HOSTPASSWORD:   Your password on the host computer
        SET GEMNETID:       Name of the GemStone service on the host computer
                               (defaults to gemnetobject)
        SET GEMSTONE:       Name of the Stone (database monitor) process
        SET USERNAME:       Your GemStone user ID
    (For a linked session, only the last two values are required.)
    Optional parameter is
        SET NETLDI:         netldi name or port number (no host prefix)

    The required parameters for X509 certificate login (RPC only) are:
        SET CERT:           Path to your X509 certificate file
        SET CACERT:         Path to your X509 CA certificate file
        SET KEY:            Path to your private key file
        SET NETLDI:         Location of the netldi in H:P format where
                              H is either a hostname or IP address and
                              P is either a port number of netldi service
                              name.

    For more information about these parameters, see the Help information
    on SET. Also, see Chapter 1 of the Topaz manual.

    For a classic login, after you issue the LOGIN command, Topaz will prompt
    you for your GemStone password. (Your response will not be echoed.)
    Alternatively, you can use the SET PASSWORD: command to establish your
    GemStone password before you log in.

    Topaz allows you to run your Gem, Stone, and Topaz processes on separate
    network nodes. For more information about this, see the Help information
    for SET GEMNETID and SET GEMSTONE.

    If you're using linked Topaz, note the following:

      o  Topaz can only be linked with a single GemStone session
         process. If you issue the login command to create multiple
         sessions, the new sessions are RPC rather than linked.

      o  If the gemnetid is set to anything other than '' (null) or
         gcilinkobj, Topaz starts an RPC session instead of a linked one.

      o  You cannot use the SET command to run Gem and Topaz on separate
         nodes. (However, you may still run the Stone process on a separate
         node.)

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

    Although you can abbreviate most other Topaz commands and
    parameter names, LOGOUT must be typed in full.

    In scripts, to expect an error at logout , such as session already
    invalid, use  EXPECTVALUE @1 . To expect a successful logout,
    use  EXPECTVALUE true .

    In a session created with DEBUGGEM, equivalent to DETACH .

1 LOGOUTIFLOGGEDIN
    If logged in, logs out the current GemStone session.
    Does not increment topaz error count if there is no current session.

1 LOOKUP
    LOOKUP meth <selectorSpec> [envIdInteger]
    LOOKUP method <selectorSpec> [envIdInteger]
    LOOKUP cmeth <selectorSpec> [envIdInteger]
    LOOKUP classmethod <selectorSpec> [envIdInteger]

    The arguments after 'LOOKUP' are case sensitive.
    Using the current class , search for specified instance or class method
    method going up the class hierarchy. Print the class in which
    method found, and list the category and source code .
    Looks in transient method dicts, then persistent method dicts for each class
    up the hierarchy.
    If no envIdInteger specified, uses current compiliation environment (see ENV) .
    See <selectorSpec> in Object_Specification_Formats .

    LOOKUP <classname> >> <selectorSpec> [envIdInteger]

    Make the specified class the current class,
    and do a lookup for the specified instance method
    A <classname> may not be one of 'meth', 'method', 'cmeth', 'classmethod'

    LOOKUP <classname> class >> <selectorSpec> [envIdInteger]

    Make the specified class the current class,
    and do a lookup for the specified class method.
    A <classname> may not be one of 'meth', 'method', 'cmeth', 'classmethod'

    The following forms
       LOOKUP <classname> (Implementation CLASS) >> <selectorSpec> [envIdInteger]
       LOOKUP <classname> class (Implementation CLASS) >> <selectorSpec> [envIdInteger]
    are also allowed, Thus given lines from a topaz stack report such as
      4 SmallInteger (Object) >> doesNotUnderstand:        (envId...
      5 SmallInteger (Object) >> _doesNotUnderstand:args:envId:reason: (envId...
      6 GsNMethod class  >> _gsReturnToC  (envId...
    you may copy/paste extracts from the stack report for LOOKUP commands like this:
      look SmallInteger (Object) >> doesNotUnderstand:

1 METHOD:
    Compiles an instance method for the class whose name you give as a
    parameter. The class of the new method will automatically become the
    "current" class. If you don't supply a class name, the new method is
    compiled for the current class (as set with the SET CLASS:, FILEOUT
    CLASS:, METHOD:, or LIST CATEGORIESIN: command).
    Compiles in the current compilation environment (see ENV).

    Text of the method should follow the METHOD: command on subsequent
    lines. The method text is terminated by the first line that starts
    with the '%' character. For example:

         METHOD: Employee
         name
            ^ name
         %

1 NBRUN
    Similar to PRINTIT. If current session is remote,
    execution is non-blocking, using GciNbExecute().
    Compiles in current compilation environment (see ENV).
    To get the result , always use NBRESULT which calls GciNbEnd() .
    The text of NBRUN is not accessible from EDIT LAST.
    NBRUN should not be immediately preceeded by EXPECT commands , since
    NBRUN has no result. NBRUN may be followed by a SET SESSION and
    another NBRUN to start a non-blocking execution in another session .

1 NBSTEP
    Similar to STEP. If current session is remote,
    execution is non-blocking, using GciNbStep().
    To get the result , always use NBRESULT which calls GciNbEnd() .
    NBSTEP should not be immediately preceeded by EXPECT commands , since
    NBSTEP has no result. NBSTEP may be followed by a SET SESSION and
    another NBRUN or NBSTEP to start an execution in another session .

1 NBRESULT
    Wait for and display result of a previous NBRUN, by calling GciNbEnd().
    May be preceeded by a SET SESSION to switch to the session
    of an outstanding NBRUN, otherwise the topaz current session is used.
    May be immediately preceeded by EXPECTVALUE , EXPECTBUG, etc,
    provided that the EXPECT commands contain only ints or numerically
    coded objIds (i.e. @NNN ) , to avoid having the EXPECT commands
    execute GciResolveSymbol before the call to GciNbEnd() .
    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  "[84 sz:0 cls: 597 UndefinedObject] _remoteNil"

1 OBJ1
     OBJ1 X
   is equivalent to
     level 1
     omit zerobased
     OBJECT X
     level <previous level>
     <display zerobased  <if previously set>>

1 OBJ1Z
     OBJ1Z X
   is equivalent to
     level 1
     display zerobased
     OBJECT X
     level <previous level>
     <omit zerobased  <if not previously set>>

1 OBJ2
     OBJ1 X
   is equivalent to
     level 2
     omit zerobased
     OBJECT X
     level <previous level>
     <display zerobased  <if previously set>>

1 OBJ2Z
     OBJ1Z X
   is equivalent to
     level 2
     display zerobased
     OBJECT X
     level <previous level>
     <omit zerobased  <if not previously set>>

1 OBJECT
    Provides structural access to GemStone objects. You can use the OBJECT
    command to "peek" and "poke" at objects without sending messages.

    The first parameter to this command must be a valid object
    specification. Following that, you may supply a sequence of
    AT: and AT:PUT: commands.

2 AT:
    The AT: command takes an integer offset into the given object and
    retrieves the instance variable at that offset. For example,

        Object Tool at: 1

    fetches and displays the first instance variable of the GemStone
    object named "Tool".

    When an indexable object also has named instance variables, the
    indexable instance variables FOLLOW the named instance variables.
    That is, if an indexable object also had three named instance variables,
    the first indexable field would be addressed with

        Object anIndexableObj at: 4

    You may use AT: with NSCs (instances of Bag and its subclasses).

2 AT:PUT:
    The AT:PUT: command lets you store values into instance variables.
    This command takes an integer offset and a second object specification,
    and stores the second object into the first object at the given offset.

    You may not use AT:PUT: with NSC objects.

                                  WARNING
        Because OBJECT AT:PUT: bypasses all the protections built into
        the GemStone Smalltalk kernel class protocol, you risk corrupting your
        database if you permanently modify objects with this command.

3 Examples
    Object '12345' at: 3 put: $x

        creates the string "12345", puts the character "x" at its
        third position, and displays the modified string.

    Object Tool at: 1  at: 4 put: Widget  at: 5 put: ToolBox

        (1) finds the object contained in Tool's first instance variable;
        (2) stores the object named Widget at that object's 4th location;
        (3) stores the object named ToolBox at that object's 5th location;
        (4) displays the modified object.

3 Byte_Array_Objects
    OBJECT AT:PUT: 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
         obj '123' at: 1 put: $9      stores the character '9'

       SmallInteger
         obj '123' at: 1 put: 48      stores a byte with value 48

       Byte Arrays
         obj '1234' at: 2 put: 'bc'   stores 'b' and 'c' at offsets 2 and 3

1 OMIT
    The DISPLAY and OMIT commands control the display and behavior of
    a number of topaz commands. Individual features default to either OMIT
    or DISPLAY; each one can be explicitly turned on using DISPLAY or turned
    off using OMIT.

2 ALLOOPS
    Disables DISPLAY ALLOOPS.

    If DISPLAY OOPS or DISPLAY ALLOOPS was previously set, the result of
    OMIT ALLOOPS returns state to DISPLAY OOPS; only the names of Classes
    and not the oops of classes to be printed in objects, the printing of
    certain primitive specials do not include the oops, and stack
    temporaries are not printed.

2 BYTES
   Shutoff display of decimal or hexadecimal values of bytes of byte format objects.

2 CLASSOOPS

    Legacy; equivalent to OMIT ALLOOPS

2 DECIMALBYTES
   Shutoff display of decimal or hexadecimal values of bytes of byte format objects.

2 DEPRECATED

    For topaz commands such as STRINGS, SENDERS,  which return lists of
    methods  OMIT DEPRECATED causes those results to omit
    methods which contain sends of any methods
    implemented in Object in  category 'Deprecated Notification' .

2 ERRORCHECK
    same as  omit RESULTCHECK

2 FLUSHOUTPUT

    Disables immediate flushing of topaz output files
    See DISPLAY FLUSHOUTPUT for details.

2 LINEEDITOR
    Disables use of the built-in line editor. Has no effect on Windows .

2 NAMES
    Controls the display of instance variable names. Normally, the name
    of each instance variable is displayed along with its value. When
    you OMIT NAMES, only the values are displayed;  instance variable
    names appear as 'i1', 'i2', 'i3', etc. You can use DISPLAY NAMES
    to turn the display back on.

2 OOPS
    Disables the display of the OOP values of objects. This is the default.

2 ORIGIN
    Disables the display of method ORIGIN for listed methods

2 PAUSEONERROR

    Disables pause-on-error (see DISPLAY PAUSEONERROR for details)

2 PAUSEONWARNING

    Disables pause-on-warning (see DISPLAY PAUSEONERROR for details)

2 PUSHONLY
    Disables the effect of the 'ONLY' keyword in an OUTPUT PUSH command.
    Within a topaz -S script,  turns on echoing of script input and topaz
    printing of results to stdout.

2 RESULTCHECK
    Disables automatic error and result checking.
    See DISPLAY RESULTCHECK for details.

2 STACKTEMPS
    Disables effect of DISPLAY STACKTEMPS .

2 VERSIONEDCLASSNAMES
    Use  Class >> versionedName for names of classes when printing objects.
    This is the default.

2 ZEROBASED
    Show offsets of instVars one-based , canceling any previous
    DISPLAY ZEROBASED .

1 OUTPUT
    Controls where Topaz output is sent. Normally Topaz sends output
    to stdout (standard output). This command will redirect all Topaz
    output to a file (or device) of your choice.

2 PUSH
    Tells Topaz to send output to the file following the PUSH token.
    The keyword PUSH must be typed in full.
    Topaz always writes to output files using Utf8 .

    Topaz can maintain a stack of up to 20 output files. Current
    interactions written to all files on the stack. If you
    attempt to exceed the stack limit, Topaz will display an error
    message and continue to send its output to the current output stream.

    If the word following OUTPUT on the topaz command is none of
       PUSH, POP, PUSHNEW, or APPEND
    then PUSH is assumed, i.e.
        OUTPUT foo.out
    and
        OUTPUT PUSH foo.out
    are equivalent.

3 fileName
    If you use a host environment name such as $HOME/foo.bar in UNIX
    in the filename, Topaz will expand that name to the full filename.

    If your filename does not contain an explicit path specification, Topaz
    writes to the named file in the directory in which you started Topaz.

    If you name a file that doesn't yet exist, Topaz will create it.
    In UNIX, if you name an existing file, Topaz will overwrite the file.

    If you name a file that is already being written to by a previous
    OUTPUT PUSH command, the file will be opened for writing again,
    and the resulting file may be garbled.

    To append to an existing file, precede the filename with an ampersand (&):
         output push &disney$log$files:flubber.log
    If your operating system allows ampersands in filenames, Topaz
    may misinterpret any filename with an ampersand as its first character.

3 ONLY
    Tells Topaz to echo output only to the named file, and not to echo
    output to standard output (usually, your screen). Ordinarily, all
    output is also echoed on the screen. For example:
          OUTPUT PUSH filename ONLY

    The ONLY attribute in the "OUTPUT PUSH filename ONLY" will be ignored
    if "OMIT PUSHONLY" is executed, and the behavior restored on DISPLAY
    PUSHONLY. This allows control over which topaz output is echoed to the
    screen.

2 APPEND
    Tells Topaz to send output to the file following the APPEND token.
    (The keyword APPEND must be typed in full.)

3 fileName
    If you use a host environment name such as $HOME/foo.bar in UNIX
    in the filename, Topaz will expand that name to the full filename.

    If your filename does not contain an explicit path specification, Topaz
    appends to the named file in the directory in which you started Topaz.

    If you name a file that doesn't yet exist, Topaz will create it.

    If the first character of the file name is ampersand (&), the & character
    is ignored.

3 ONLY
    Tells Topaz to echo output only to the named file, and not to echo
    output to standard output (usually, your screen). (Ordinarily, all
    output is also echoed on the screen.)   For example:

                OUTPUT APPEND filename ONLY

    "OMIT PUSHONLY" causes  the ONLY attribute
    to all "OUTPUT APPEND filename ONLY" to be ignored.

2 PUSHNEW
    Tells Topaz to send output to the file following the PUSHNEW token.
    The OUTPUT PUSHNEW command will create a new version of the file,
    if the specified file already exists.
    For a filename of the form foo.out , the new version will be foo_N.out
    where N is some integer >= 1 and <= 999 such that foo_N.out did
    not previously exist . If all 1000 versions of the file exist,
    then OUTPUT PUSHNEW will attempt to overwrite the version with the oldest
    modification time; if that oldest files is not writable, the
    OUTPUT PUSHNEW will fail with an error.

3 fileName
    If you use a host environment name such as $HOME/foo.bar in UNIX
    in the filename, Topaz will expand that name to the full filename.

    If you name a file that doesn't yet exist, Topaz will create it.

    If the first character of the file name is ampersand (&), the & character
    is ignored.

3 ONLY
    Tells Topaz to echo output only to the named file, and not to echo
    output to standard output (usually, your screen). (Ordinarily, all
    output is also echoed on the screen.)   For example:

         OUTPUT PUSHNEW filename ONLY

    "OMIT PUSHONLY" causes  the ONLY attribute
    to all "OUTPUT PUSHNEW filename ONLY" to be ignored.


2 POP
    Stops output to the current output file (that is, the file most
    recently named in an OUTPUT PUSH , OUTPUT , or OUTPUT PUSHNEW command).
    Topaz closes that file and resumes sending output to the previously
    named output file.
    If there is no previous output file, an error message is issued
    and Topaz once again sends its output to standard output only.

    Although you can abbreviate most other Topaz commands and
    parameter names, the keyword POP must be typed in full.

1 PAUSEFORDEBUG
    PAUSEFORDEBUG [errorNumber]

    Provided to assist internal debugging of a session
    With no argument, this is equivalent to REMARK

    The C function void TpPauseForDebug(void), which has no effect,
    is called once. You can set a C debugger breakpoint on TpPauseForDebug
    if desired.

    After calling TpPauseForDebug,
       errorNumber > 0  :  the topaz -l or gem process of the session
         should halt and wait for a C debugger to attach (or dump core)
         on the next ocurrence of that GemStone error in the current session,
         and any sessions created by subsequent logins .
         The halt is at the point in the gem code where the error is generated.
       errorNumber = 0 :  clear the gem halt-on-error number in current session,
         if any, and use halt-on-error == 0 in subsequent logins.
       errorNumber < 0  : has no effect.

    See also TOPAZPAUSEFORDEBUG

1 PKGLOOKUP
    PKGLOOKUP meth <selectorSpec>
    PKGLOOKUP method <selectorSpec>
    PKGLOOKUP cmeth <selectorSpec>
    PKGLOOKUP classmethod <selectorSpec>

    The arguments after 'PKGLOOKUP' are case sensitive.
    Using the current class, search in current compilation environment (see ENV)
    for specified instance or class method method going up the class hierarchy.
    Print the class in which method found, and list the category and
    source code.

    Looks in GsPackagePolicy state, then persistent method dicts for each class
    up the hierarchy. Does not look at transient method dicts.
    See <selectorSpec> in Object_Specification_Formats

    PKGLOOKUP classname >> selectorSpec

    Make the specified class the current class,
    and do the specified lookup for a instance method

    PKGLOOKUP classname class >> selectorSpec

    Make the specified class the current class,
    and do the specified lookup for a class method

1 POLLFORSIGNAL

    Waits forever for OOB activity from the GEM, using GciPollForSignal.
    Use ctl-C to interrupt.
    For interative testing of GciPollForSignal .

1 PRINTIT
    Sends the text following the PRINTIT command to GemStone for execution as
    GemStone Smalltalk code and displays the result.
    Uses current compilation environment (see ENV).

    (If there is an error in your code, Topaz will display an error message
    instead of a legitimate result.)

    Smalltalk text is terminated by the first line in which '%' is the first
    character. For example:

        printit
        { 2 . 3 }
        %
        an Array
          #1 2
          #2 3

    The result is displayed as if LEVEL 1 were the last LEVEL command,
    but without altering the display level used by other commands.

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

1 PROTECTMETHODS
    All subsequent method compilations during the current session
    must contain either a <protected> or <unprotected> directive.
    Used for consistency checking in filein scripts.

1 QUIT
    Terminates Topaz, returning to the parent process or operating system.
    If you are still logged in to GemStone when you type QUIT, this will
    abort your transaction and log out all active sessions.
    Although you can abbreviate most other Topaz commands and
    parameter names, QUIT must be typed in full.

    If an QUIT is encountered in a input file when stdin is interactive 
    (that is, is a tty), QUIT does not exit topaz. If topaz was invoked 
    with -P , and the QUIT is in an input file other than the one specifed 
    as the argument to -P (such a nested input file), then a topaz error 
    is signalled; otherwise, a warning is printed. In both cases, input 
    processing continues.

    If this command has an argument and it is an integer, then
    the integer is used as the exitStatus. If the status argument is an
    object specification that resolves to an integer, then that value
    is used as the exitStatus. Only 8 bits of the integer are returned,
    exitStatus should be 0..255. If it is not an integer then an error
    is returned and the process does not exit.

    If the command does not have an argument, the exitStatus will
    be either 1 if there were GCI errors or the topaz errorcount is not zero,
    or 0 if no errors had occurred.

    In a topaz session created by DEBUGGEM, equivalent to DETACH .

    See also EXIT .

    To exit from topaz help back to topaz command prompt, type <Enter>.

1 RELEASEALL
    Empty topaz's internal buffer of object identifiers which
    need to be released via GciRelease calls . RELEASEALL
    is performed automatically prior to each RUN, DOIT, PRINIT,
    or SEND .

1 REMARK
    Begins a remark (comment) line. Topaz will ignore all
    succeeding characters on the line. You can also use an
    exclamation point ("!") in column 1 of a line to signal
    the beginning of a comment. Comments are often useful
    in annotating Topaz test scripts and the like.

1 REMOVEALLCLASSMETHODS
    Removes all class methods in all enviornments
    from the class whose name you give as a parameter.
    The specified class will automatically become the "current" class.

    Example:    removeallclassmethods Array

    This command may not be abbreviated.

1 REMOVEALLMETHODS
    Removes all methods in all environments
    from the class whose name you give as a parameter.
    The specified class will automatically become the "current" class.

    Example:    removeallmethods Array

    This command may not be abbreviated.

1 RESUME
   In a topaz session created by DEBUGGEM, sets waitForDebug state to resume
   (using System __sessionStateAt: 26 put: 2) 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.

1 RUN
    Same as PRINTIT, but the display level for the result is determined
    by the last  LEVEL command .
    If GEM_NATIVE_CODE_ENABLED=FALSE in the gem config file, or if
    any breakpoints are set, execution defaults to interpreted mode,
    otherwise execution defaults to using native code .
    Uses current compilation environment (see ENV).

1 RUNBLOCK
    Takes two arguments on the command line, and the following lines up to
    the next % must be the source for a block with betweeen 0 and 10 block
    arguments.

    The first command line argument is used for self in the block,
    and can be any object (see Object_Specification_Formats)

    The second argument must be an Array of size N, where N is the
    number of block arguments . This second argument can be specified
    using ** or @OOP, or named in UserGlobals.

    The execution of the source code lines following the command line is
    performed by using the ExecuteBlock variant of GciStoreTravDoTravRefs_() .
    Example:
      run
      { 5 . 66 }.
      %
      runblock 'abc' **
      [:a :b |  self copy , a asString , b asString ]
      %
    Returns a String
      abc566
    Uses current compilation environment (see ENV).

1 RUNENV
    Same as RUN, but takes one integer argument >= 0 and <= 255 ,
    specifying compilation environment for the code to execute in.
    Argument takes precedence over the value set by   SET COMPILE_ENV: .

    Example:
       runenv 6
       (3.0 + 4.5) myFormatting
       %

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

1 SEND
    Sends a message to an object in current compilation environment(see ENV).
    The message is built almost as it
    would be in Smalltalk, by mixing the keywords and arguments. The
    first argument is an object specification identifying a receiver.
    For example:

         SEND System myUserProfile
         Send 1 + 2
         send @10443 deleteEntry: @33234

    Only one message send can be performed at a time with SEND.
    Cascaded messages or parenthetical messages are not supported
    by this command. Also note that each item must be delimited by
    one or more spaces or tabs. A maximum of 20 keyword/argument pairs
    is allowed on the SEND command.

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

1 SENDENV
    Sends a message to an object.
    The first argument is an integer in the range 0..255 specifying
    environmentId for the initial message send,
    and takes precedence over the value set by  ENV or  SET COMPILE_ENV: .
    Remaining arguments are same as for SEND , for example:
        SENDENV 5 System myUserProfile

    See also  SEND,  SET COMPILE_ENV:  .

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

1 SENDERS
    Expects one argument, an objectSpecification, the value of which
    is either a String or Symbol .

    Equivalent to a DOIT of
      (ClassOrganizer newForEnvironment: <current env>) sendersOfReport: aString
    which reports senders of (aString asSymbol) for the current
    compliation environment (see ENV) .
    May require larger than default GEM_TEMPOBJ_CACHE_SIZE configuration.
    See <selectorSpec> in Object_Specification_Formats
    DEFINE CurrentClassOrganizer  will override the class organizer used.

1 SET
    The SET command is used (in conjunction with LIST and EDIT) to browse
    through GemStone dictionaries, classes, traits, and methods. You can 
    use SET to select a current CLASS, CATEGORY, and TRAIT.

    You also use this command to SET certain login parameters: GEMSTONE (the
    Stone process), your GemStone USERNAME and PASSWORD, your host
    HOSTUSERNAME and HOSTPASSWORD, and GEMNETID (name of GemStone
    service). (You can also set these parameters in a Topaz initialization
    file.)

    The special idioms,
        "SET HOSTUSERNAME *"
        "SET PASSWORD *"
        "SET HOSTPASSWORD *"

    will clear the respective fields.

    You can combine two or more SET items on a Topaz command line, and you
    can abbreviate token names (so long as they remain unique). For example:

        SET GEMSTONE multiuser USER DataCurator

2 AUTOSTACKSAVE
   Requires one argument,  OFF or ON .
   If on, STACK SAVE is executed automatically for each error returned to topaz
   from an execution (doit , send, or run).

   Default is ON if the topaz stdin is a terminal (GsFile stdin isTerminal == true),
   otherwise default is OFF.

2 CACHENAME
    Sets the name of the session in the shared page cache. The name takes
    effect for subsequent logins of all sessions in the current
    topaz process.  The cache name is the name that appears in VSD for the process.
    The value is truncated to 31 characters in the shared cache.
    The value is stored in the shared cache on the host where the gem or topaz -l
    process is running. Overrides any -u value passed on topaz command line.

    To set the cache name to be "MySession":
         SET CACHENAME MySession

2 CATEGORY:
    Sets the "current category" for subsequent method compilations.
    For example:

       set category: Accessing

    To include spaces in a category name, enclose the category name
    in single quotes:

       set cat 'Public Methods'

    If you compile a method without first selecting a category,
    the new method is inserted in the default category "as yet unspecified".

    If the category you name doesn't already exist, Topaz will create
    it the first time you compile a method.

    Specifying a new class with SET CLASS clears the current category.
    When you EDIT or FILEOUT a method, that method's category becomes
    the current category.

    Before you can SET CATEGORY, you must be logged in to GemStone.
    The current category is cleared by the LOGOUT, LOGIN, SET CLASS,
    and SET SESSION commands.

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

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

2 CLASS:
    Sets the current class. After you issue SET CLASS, you can list
    the class's categories and methods with the LIST CATEGORIES command.
    You can select a category to work with through either the SET CATEGORY:
    or the CATEGORY: command.

    The current class may also be redefined by the LIST CATEGORIESIN:,
    METHOD:, CLASSMETHOD:, and FILEOUT CLASS: commands. The current
    class is cleared by the ABORT, LOGOUT, LOGIN, and SET SESSION
    commands.

    Before you can SET CLASS, you must be logged in to GemStone.
    Example
       set class Integer

    "SET CLASS" with no subsequent class name
     will display the name of the current class.

     "SET CLASS nil" will clear the current class.

2 COMPILE_ENV:
    Sets the compilation environmentId for method compilations and
    for executions (RUN, DOIT, etc). Argument must be an integer >= 0
    and <= 255 . The default is zero .

2 DIRECTORY:
    Set the name of the working directory for the RPC gem created by
    a certificate login.

2 ENVVAR
    Set an enviroment variable value in the topaz process.
    Example   SET ENVVAR myEnvVar myEnvValue
    Requires two arguments which will be treated as strings.
    The word ENVVAR cannot be abbreviated .

2 ENVPASSWORD
    May be abbreviated as ENVP .
    The argument must be a case-insensitive string, ON or OFF .
    When ON, the password field is interpreted as the name of an
    environment variable which contains the password. When OFF, 
    the password field is not interpreted as an environment
    variable. The env var may also reference a onetime password
    or JWT if one of those options has been enabled.

2 EDITORNAME:
    Sets the name of the editor you want to use in conjunction
    with the EDIT command. The default is set from the value of your
    $EDITOR environment variable, if it is defined.

2 ENABLEREMOVEALL
    Requires one argument,  OFF or ON .
    ON enables the topaz REMOVEALLMETHODS, REMOVEALLCLASSMETHOD, 
    TRREMOVEALLMETHODS and TRREMOVEALLCLASSMETHOD commands .
    OFF caused the topaz REMOVEALLMETHODS, REMOVEALLCLASSMETHOD, 
    TRREMOVEALLMETHODS and TRREMOVEALLCLASSMETHOD commands commands to have 
    no effect.
    Default is ON.

2 EXTRAGEMARGS:
    Sets a list of extra command line arguments to be used when
    starting an RPC gem for a certificate login.

2 FILEPASSWORD:
    May be abbreviated as FILEP .
    The argument must be a case-insensitive string, ON or OFF .
    When ON, the password field is interpreted as a file name 
    containing the actual password. When OFF, the password field
    is not interpreted as a file name. The file may also contain any
    type of valid password such as a GemStone password, JWT or onetime
    password.

2 GEMNETID:
    Establishes the name of the GemStone service on the host computer
    (that is, the host process to which Topaz will be connected).
    If topaz was started as  topaz -l , the default value is "gcilnkobj"
    which means to do a linked login using the VM in the topaz process.
    A value other than "gcilnkobj" in a topaz -l process specifies a remote
    login.

    For topaz -r  or topaz with no arguments, the default name is "gemnetobject"
    for a remote login.

    For a remote login the following applys:
    You can specify the Gem network node as part of the GEMNETID argument.
    Topaz will examine that argument for information about the desired Gem
    node.

    You can tell Topaz to find the GemStone service and run your GemStone
    session on a node other than the local node by using a command of the
    form:

         set gemnetid: !@node!aServiceName

    Example using an alternate netldi, other than the default gs64ldi,
      assumming mynetldi is in the Unix services :
          set gemnet !@node#netldi:mynetldi!gemnetobject
      alternative using the netldi's listening port:
          set gemnet !@node#netldi:10027!gemnetobject

2 GEMSTONE:
    Example:

         SET GemStone: GemServer

    see SET STONE

2 HISTORY:
    Expects an integer argument in range 1 .. 1000 .
    Sets the history size of the line editor.
        example SET HISTORY 50
    Not available on Windows.

2 HOSTPASSWORD:
    Sets the host password to be used when you next log in. If you
    don't include the password on the command line, Topaz will prompt
    you for it. Prompted input will be taken from the terminal and
    not echoed. This allows you to put a SET HOSTPASSWORD: command in
    your Topaz initialization file so that Topaz will automatically prompt
    you for your host password.

    This command must follow the SET HOSTUSERNAME: command.

    The command "SET HOSTPASSWORD *" will clear the host password.

    If you are using linked Topaz, SET HOSTPASSWORD has no effect.

2 INCONVERSION
    For use only by repository upgrade scripts in $GEMSTONE/upgrade .
    Sets the internal variable GciSupDbInConversion to TRUE for a subsequent login.
    Must be used prior to each login for which it is desired that GciSupDbInConversion
    be set to TRUE .
    INCONVERSION is not supported in remote topaz (topaz -r).
    You must use linked Topaz (topaz -l) for repository upgrade.

2 INPUTPAUSEONERROR
    May not be abbreviated.
    The argument must be a case-insensitive string ,  ON or OFF ;
    ON has no effect if stdin is not a terminal.
    If ON is specifed, and stdin is a terminal, then the next INPUT
    command processed will transition topaz to
       DISPLAY PAUSEONERROR  being active
    and the PAUSEONERROR remains in effect until topaz input
    returns to stdin, at which point the previous state of
    DISPLAY PAUSEONERROR is restored.

2 HOSTUSERNAME:
    Sets the account name that you use to 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.

    If you don't use the SET HOSTUSERNAME and SET HOSTPASSWORD commands
    to supply the needed account information, and no default account
    information exists for you, you will be unable to log in.

    If you're using linked Topaz (gemnetid "gcilnkobj"), SET HOSTUSERNAME has
    no effect.

    Because SET HOSTUSERNAME: clears your host password, you should
    issue this command before issuing SET HOSTPASSWORD:.

3 TCP_Network_Initialization
    With TCP/IP, if you don't explicitly supply a host username and password,
    Topaz will try to find a username for the designated node in a file in
    your home directory. Under UNIX, that file is $HOME/.netrc and
    should contain lines of the form
               MACHINE aNode LOGIN aUsername PASSWORD aPassword

    For example:
       machine alf login joe password mypassword    ($HOME/.netrc -- UNIX)

    Because the network initialization file contains your password, make
    sure that others (group or world) do not have authorization to read it.

2 JWTJSONFILENAME
    May be abbreviated as JWTJ .
    This command takes 2 arguments:
      1) Name of a JSON file.
      2) Key within that JSON file which references a JSON Web Token (JWT)
         to be used as the password for login.
    Executing this command makes topaz parse the JSON file and set the
    password to be the JWT. It also sets JWTPASSWORD to ON.

2 JWTPASSWORD
    May be abbreviated as JWTP .
    The argument must be a case-insensitive string, ON or OFF .
    When ON, the password field is interpreted as a JSON Web Token
    (JWT) password. When OFF, the password field is not interpreted as a
    JWT. A JWT password is valid for a specific user for a period of
    time until the JWT expires. The stone and user profile must
    also be configured for JWT usage. Consult the GemStone System
    Administrator's Guide for additional information regarding JWT 
    passwords.

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

2 LIMIT:
   Example   SET LIMIT: 50
   Equivalent to  LIMIT BYTES 50

2 LISTWINDOW
    Controls the number of source lines listed by the LISTW command

2 LOGFILE:
    Set the name of the RPC gem's log file for certificate logins.

2 NETLDI:
    Sets netldi info for subseqent logins.
    For X509 logins the syntax is
       SET NETLDI: H:P
    where H is a hostname or IP address and P is a port number or netldi
    service name. 
    The host portion specifies the host on which the specified netldi is running,
    the gem process will run on that host.

    For non X509 login syntax is
       SET NETLDI:  P
    and any host info should be specified in gemnet or stone NRS, such as
       set gemnet !@hostx!gemnetobject
       set stone  !@hostx!mystone
    If the netldi name or port number specified disagrees with the value of
    GEMSTONE_NRS_ALL environment variable, a topaz error is signalled.

2 NRSDEFAULTS:
    Sets the default components to be used in network resource string specifications 
    Modifies the the value of the GEMSTONE_NRS_ALL environment variable in the topaz process.
    The parameter 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 inherited by the topaz process. 
    The STATUS command shows the value of NRSDEFAULTS unless it is the empty string.

2 ONETIMEPASSWORD
    May be abbreviated as ONETIME .
    The argument must be a case-insensitive string , ON or OFF .
    When ON, the password field is interpreted as a onetime password.
    When OFF, the password field is interpreted as a normal GemStone
    password. A onetime password is a temporary password valid for
    a single login for a specific user ID. Onetime passwords may be
    created by any session with sufficient privileges and are
    valid for a limited duration specified when created. Onetime
    passwords are encoded in base-64 string format. Consult the
    GemStone System Administrator's Guide for additional information
    regarding onetime passwords.

2 PASSWORD:
    Specifies the GemStone password to be used in subsequent LOGIN
    commands. If you don't include the password on the command line,
    Topaz will prompt you for it. (Your input will not be echoed.)

    You can put a SET PASSWORD: command in your Topaz initialization file
    so that Topaz will automatically prompt you for your password.

    This command must follow the SET USERNAME: command.

    The command "SET PASSWORD *" will clear the GemStone password.

2 SESSION:
    Connects Topaz to the session whose ID you supply as a parameter. When
    you log in to GemStone, Topaz displays the session ID number for that
    connection. You can use SET SESSION: 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
    will be displayed, and the current session will be retained.

    This command clears the current class and category. After you
    switch sessions with SET SESSION:, your local variables (created with
    DEFINE) no longer have valid definitions.

2 SESSIONINIT
    Cannot be abbreviated. Default is  ON .
    Has no effect if stone is configured with STN_ALLOW_NO_SESSION_INIT=FALSE .

    The topaz LOGIN command always calls GciLoginEx_
    with the flag GCI_CLIENT_DOES_SESSION_INIT set.
    If stone is configured with STN_ALLOW_NO_SESSION_INIT=TRUE
    and with SET SESSIONINIT ON in effect,  topaz executes the equivalent of
        SEND GsCurrentSession initialize
    after the GciLogin, and errors from that SEND will be debuggable
    at the topaz prompt.
    If stone is configured with STN_ALLOW_NO_SESSION_INIT=TRUE
    and with SET SESSIONINIT OFF in effect,
    a topaz LOGIN omits the  GsCurrentSession initialize

    In a repository upgrade situation , STN_ALLOW_NO_SESSION_INIT=TRUE
    combined with SET SESSIONINIT OFF allows
    a subsequent topaz LOGIN to skip loading of session methods if
    configured in GsPackagePolicy,  to faciliate recompile or reload
    of session methods, or to facilicate executing
        GsCurrentSession initialize
    interactively to debug it.

2 SINGLECOLUMN

    Cannot be abbreviated. Default is  OFF .
    OFF causes stack frame display to print multiple args and temps per line
    if possible.
    ON causes display of method args and temps in stack frame display
    to use one line per arg or temp.

    See also FR_1

2 SOLOLOGIN
    May be abbreviated as SOLO .
    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.
    After ON, the X509 login settings are ignored an only
    the SET USER and SET PASSWORD settings are used with login.
    After ON to OFF transition, X509 login settings must be set again.
    If previous login settings were for X509, then after OFF to ON
    transitsion,  SET USER and SET PASSWORD must be specified.
    See HELP SoloSession  for more details.

2 STONE
    Specifies the name of the GemStone database that you want to log in to.
    Example:

         set stone GemServer

    You can run your Gem (GemStone session), Stone (database monitor),
    and Topaz processes on separate nodes in your network. Ordinarily,
    your GemStone session will look for the Stone process whose name 
    you supply on the same node on which the GemStone session is running.
    You can tell Topaz to find the Stone process on a different node by
    using a command of the form:

          set stone !@theNode!theGemStoneName

    Example using an alternate netldi, other than the default gs64ldi,
      assumming mynetldi is in the Unix services :
          set stone !@theNode#netldi:mynetldi!theGemStoneName

2 SOURCESTRINGCLASS

    Specify the  class for creation of method source strings for doit and method
    compiles, which may be created as legacy or ICU strings.

    Expects one string argument, which must be String or Unicode16.
    set sourcestringclass String
        will create String, DoubleByteString or QuadByteStrings for doits and
        methods.
    set sourcestringclass Unicode16
        will create Unicode7, Unicode16, or Unicode 32 instances for doits and
        methods.

    The topaz default is String. If it is set using the topaz command
    SET SOURCESTRINGCLASS, this setting is global in topaz and affects all
    subsequent input.

    If it is at the default and not specifically set, and a topaz login
    determines that the repository is in Unicode Comparison Mode:
          (Globals at: #StringConfiguration) == Unicode16,
    then sourcestringclass is automatically set to Unicode16. This also sets
    fileformat to UTF8. If SET SOURCESTRINGCLASS has been previous executed, no
    automatic updates are done.

    Repositories that are not in UnicodeComparisonMode should use caution with
    sourcestringclass Unicode16, since Legacy and ICU strings can not be mixed
    or compared.

2 STACKPAD
    Sets a minimum size used formatting stack display lines. The
    (implementation class ,selector) portion of each frame's line
    in output for WHERE is padded to this size. min value 0, max 256 .
    Default STACKPAD value is 45 . STACKPAD cannot be abbreviated.

2 TAB
    Set number of spaces to which to tranlate a tab (ctrl-I) character
    when printing method source strings. Default is 8 .
    Expects one arg, an integer  >= 1 and <= 16 .
    Example
        set tab 2

2 TRAIT:
    Sets the current trait. After you issue SET TRAIT, you can list
    the trait's categories and methods with the TRLIST CATEGORIESIN: command.
    You can select a category to work with through either the SET CATEGORY:
    or the CATEGORY: command.

    The current trait may also be redefined by the TRLIST CATEGORIESIN:,
    TRMETHOD:, TRCLASSMETHOD:, and TRFILEOUT TRAIT: commands. The current
    trait is cleared by the ABORT, LOGOUT, LOGIN, and SET SESSION
    commands.

    Before you can SET TRAIT, you must be logged in to GemStone.
    Example
       set trait TInteger

    "SET TRAIT" with no subsequent trait name
     will display the name of the current TRAIT.

     "SET TRAIT nil" will clear the current trait.

2 TRANSACTIONMODE

    The argument must be a string that is a case-insensitive exact match to one of
      autoBegin  manualBegin  transactionless
    The default value is autoBegin .
    If the value is not autoBegin, and there is a valid topaz session
    at the time SET TRANSACTIONMODE is executed,
    then the transaction mode of the current session is by topaz using
       System transactionMode:  <value> asSymbol
    This will abort the current transaction.

    If the value is not autoBegin, then after each subsequent topaz login
    topaz executes
       System transactionMode:  <value> asSymbol


2 USERNAME:
    Establishes the GemStone user ID to use for your next LOGIN
    command. (Your GemStone data curator can tell you your user name.)
    Because SET USERNAME: clears your GemStone password, you should
    issue this command before issuing SET PASSWORD:.

1 SHELL
    When issued with no parameters, SHELL spawns a child process,
    leaving you at the operating system prompt. To get back into
    Topaz, type Ctrl-D or "exit" from the UNIX shell .

    If you supply parameters on the SHELL command line, they are passed
    to a subprocess as a command for execution.
    For example:

        topaz 1> SHELL ls -l /user1/newtoni.topaz

1 SoloSession
    A Solo session supports read-only access to a Repository
    and Smalltalk execution using temporary object memory.
    Commits to the repository are not allowed. A Solo login can be
    done without having a stone running. In topaz -l process,
    the login does not require a netldi.

    Use SET SOLOLOGIN ON preceeding LOGIN to start a Solo session.

    The repository must be a single extent repository.
    The extent is specified by the GEM_SOLO_EXTENT config item
    (default is $GEMSTONE/bin/extent0.dbf) and must have been last written
    by a clean shutdown of a stone of the same version as the topaz .
    If the extent on the filesystem has either write or execute permission
    for any of user,group,world  then session will open the extent with an
    exclusive file lock, to prevent opening an extent that is also open
    by a stone. Set the extent to read-only permission on the filesystem
    to allow sharing by multiple Solo sessions. The amount of internal
    free space in the extent does not affect the Solo sessions.

    Each Solo gem or topaz -l process also opens a read-write 10MB
    /tmp/gemRO_<pid>_extent1.dbf which is deleted on logout
    or process exit.

    The following options to SET are not allowed in a topaz
    when SET SOLOLOGIN ON is in effect.
      CACERT CERT DIRECTORY GEMSTONE KEY LOGFILE NETLDI

    Object creation in a Solo session is all in temporary object memory.
    Use -T on the topaz -l command line or in the gemnet NRS to specify
    appropriate temp obj memory config, or use appropriate config file
    options in the -C argument or in a gem config file.

    A Solo login in a topaz process needs this sequence.
      set user
      set password
      set solologin on
      login

    The session will then be logged in to the specified UserProfile.
    If the user profile is configured for LDAP or other OS based validation,
    then that validation will be executed as part of login .

    In a Solo session,
      A large number of classmethods in System
      will signal an ImproperOperation (number 2050)
      if the operation would require connection to a stone.

      Many methods in Repository are disallowed, including
        markForCollection, reclaimAll, fullBackup*, restoreFromBackup*

1 sourcestringclass
    See SET SOURCESTRINGCLASS

1 SPAWN
    Same as SHELL

    When issued with no parameters, SPAWN spawns a child process,
    leaving you at the operating system prompt. To get back into
    Topaz, type Ctrl-D or "exit" from the UNIX shell .

    If you supply parameters on the SPAWN command line, they are passed
    to a subprocess as a command for execution.
    For example:

        topaz 1> SPAWN ls -l /user1/newtoni.topaz

1 STACK
    Legacy command for displaying stack of a Smalltalk process.
    See also WHERE.

    Topaz can maintain up to 500 simultaneous GemStone Smalltalk processes
    that provide information about the GemStone state of execution.
    Each processes call stack is made up of frames representing
    method or block activations.

    When you type "STACK", Topaz displays all frames in
    the current call stack, starting with the current frame.
    ("STACK 1" displays only the current frame;
    "STACK 2" displays the current frame and its caller.)

    For each frame, the display includes the receiver's
    class, the class of the CompiledMethod, the method selector, the level
    number (as used in FRAME), the current step point within the method
    (an integer, as in LIST STEPS), parameters and temporaries for this
    frame.

    The resulting display is governed by the setting of other Topaz commands
    such as LIMIT, LEVEL, and DISPLAY or OMIT.

2 ALL
    STACK ALL displays your list of saved call stacks. The list includes
       the top frame of every call stack ("STACK 1"):
            *0  Lion (Object) | doesNotUnderstand: @ 9
             1  Lion (Animal) | habitat @ 3
             2  Executed Code
       The "*" indicates the current call stack, if one exists.
       If there are no saved stacks, a message to that effect is displayed.

    STACK ALL is superceded by THREADS

2 CHANGE
    STACK CHANGE anInt

    Sets the current call stack to the call stack indicated by "anInt" in
    the STACK ALL display, and displays one frame of the newly
    selected call stack.

    equivalent to THREAD anInt

2 DELETE
    STACK DELETE anInt

    Removes the call stack indicated by "anInt" in the STACK ALL display.
    equivalent to THREAD anInt CLEAR

    STACK DELETE ALL removes all call stacks.

2 NOSAVE
    STACK NOSAVE causes your current call stack to be terminated before
    executing any of the following commands:  PRINTIT, SEND, DOIT,
    RUN, EDIT LAST, or EDIT NEW TEXT. This is the default condition.

    See also STACK SAVE .

2 SAVE
    STACK SAVE prevents the current call stack from being terminated as
    a side effect of any subsequent topaz execution commands.
    See also STACK NOSAVE.

2 SCOPE
    STACK SCOPE
    Displays the current frame within the current stack.

    STACK SCOPE <anInteger>
    Sets the frame at the specified position within
    the current stack to be the current frame within that stack,
    and displays that frame.

    STACK SCOPE 1
    Sets the frame at the *top* of the current stack to be the
    current frame. A subsequent STACK command will then display
    the complete stack. This is the default current frame of
    a stack that has not been previously accessed with STACK SCOPE <n> .

    STACK
    Display the current stack from the current frame to the *bottom*
    of the stack. After an error during execution, the default
    current frame of a stack is the top of that stack.

2 SET <aGsProcess>

    Takes one argument an object specification that resolves to a GsProcess .
    Make that aGsProcess the currently active stack for debugging.
    Also does the equivalent of STACK SAVE for the specified GsProcess .

    Intended for use after DEBUGGEM when execution in the target gem
    is not active, but you have an oop of a GsProcess from an error
    what was returned to the gem's controlling GCI . STACK SET
    will let you reexamine that stack using the topaz in which you
    did DEBUGGEM .

    If you have done ALLSTACKS , use THREAD <N> to select one of those
    stacks for subsequent  UP, FRAME, etc .

2 TERMINATE
    Sends #terminate to the GsProcess of the current stack ,
    if the stack is not owned by the scheduler.
    Overides a previous STACK SAVE or STACK SET of that GsProcess .

2 UP
    Move the current frame one up the stack (towards top of stack),
    and displays the current frame within the current stack.

    equivalent to FRAME <current frame + 1>

2 DOWN
    Move the current frame one down the stack (away from top of stack),
    and displays the current frame within the current stack.

    equivalent to FRAME <current frame - 1>

2 TRIM
    Trim the stack so that the current frame becomes the new top of stack,
    and that execution will resume at the first instruction in the method
    at new top of stack. The new top of stack must not represent the
    frame of an ExecutableBlock.
    If the method at new top of stack has been recompiled, installs the
    new version of that method at the top of the stack.
    See GsProcess>>_trimStackToLevel: .
    If the stack is trimmed , any resumption of execution will
    be in interpreted mode.

1 STACKWAITFORDEBUG
    Displays the current call stack,
    Then waits for a debugger to attach as defined for TOPAZWAITFORDEBUG.
    STACKWAITFORDEBUG takes no arguments.

1 STATUS
    Displays your current login settings and other information about
    your Topaz session.

1 STEP
    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 the
    discussion of debugging in Chapter 2 of the Topaz manual.

    STEP OVER
         Advances execution to the next step point in the current frame
         or its caller. "Current frame " is defined as
         the frame by the last STACK SCOPE, STACK UP,
         or STACK DOWN command, or is the top of stack of no
         STACK {SCOPE|UP|DOWN} has been issued for the current stack.

    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 .

    STEP THROUGH
         Same as STEP THRU

    STEP
         Equivalent to STEP OVER

    When the next step point is hit, topaz prints a message about the
    kind of step point hit, and a one line description of the top of the
    stack.

    In a topaz session created by DEBUGGEM,  STEP sets waitForDebug state to  
    resume (using System __sessionStateAt: 26 put: 2), 
    before attempting the single step, so that System class >> waitForDebug
    will exit and you can step in application code that is further up the stack.

1 STK
    Similar to STACK except that parameters and temporaries for each
    frame are not displayed, thus STK produces one line of output
    per stack frame.  STK with no arguments  will always display the
    full stack, prefixing the current frame (as set by last FRAME, STACK SCOPE,
    STACK UP, or STACK DOWN)  with '==>'  .

1 STRINGS
    Reports methods that contain the argument in their source string, and
    class comments that include the argument. The comparison is case-sensitive.

    Expects one argument, an objectSpecification, the value of which
    may be a String or Symbol. The search is in the current complication
    environment (see ENV).

    Equivalent to:
      run
      | org | org := ClassOrganizer new.
      org stringsReport: (aString) ignoreCase: false includeClassComments: true
      %

    May require larger than default GEM_TEMPOBJ_CACHE_SIZE configuration.
    Cannot be abbreviated.
    DEFINE CurrentClassOrganizer  will override the class organizer used.

1 STRINGSIC
    Reports methods that contain the argument in their source string, and
    class comments that include the argument. The comparison is case-insensitive.

    Expects one argument, an objectSpecification, the value of which
    may be a String or Symbol. The search is in the current complication
    environment (see ENV).

    Equivalent to:
      run
      | org | org := ClassOrganizer new.
      org stringsReport: (aString) ignoreCase: true includeClassComments: true
      %

    May require larger than default GEM_TEMPOBJ_CACHE_SIZE configuration.
    Cannot be abbreviated.
    DEFINE CurrentClassOrganizer  will override the class organizer used.

1 SUBCLASSES
    SUBCLASSES
        prints subclasses of the current class
        using current compilation environment( see ENV)

    SUBCLASSES <className>
        prints subclasses of the specified class
        using current compilation environment( see ENV)

    The result is obtained from  Class>>hierarchy .

1 SUBHIERARCHY
    SUBHIERARCHY
      print a hierarchy report for all subclasses of the current class
    SUBHIERARCHY <classname>
      print a hierarchy report for all subclasses of the specified class

    Uses current compilation environment( see ENV)

1 TEMPORARY
    Displays or redefines the value of one or more temporaries
    in the current frame of the current stack .

    TEMPORARY Displays the names and values of all temporaries in the
       current frame.

    TEMPORARY preferences
       Displays the temporary named "preferences" in the current frame

    TEMPORARY preferences 'bouzouki'
       Redefines the value of the temporary named
       "preferences" in the current frame to have the value
       'bouzouki'. The new value (here, 'bouzouki') may be any Topaz object
       specification.

    TEMPORARY 3
       Displays the temporary at offset 3 in the current frame.
       Use this form to access a temporary with a duplicate name, since
       the displaying a temporary by name will always display the first
       temporary with the given name.

    TEMPORARY 3  'abc'
       Modifies the temporary at offset 3 in the current frame.

1 THREAD
    May be abbreviated as THR .
    THREAD     displays currently selected GsProcess  from among the stack
    saved from the last error, or those retrieved by last THREADS command.

    THREAD <n>  changes the currently selected GsProcess. Valid <n> are
    those shown in the most recent THREADS command .

    THREAD <n> CLEAR clears the selected GsProcess from topaz stack cache.

1 THREADS
    With no parameters,
    forces any dirty instances of GsProcess in cached in VM stack memory
    to be flushed to object memory. Then executes a message send of
       ProcessorScheduler>>topazAllProcesses
    and retrieves and displays the list of GsProcesses .
    The resulting list will also include any GsProcesses which have
    been saved via STACK SAVE commands.
    Cannot be abbreviated.

    Use THREAD <N> to select one of the stacks for detailed examination
    with commands such as UP , FRAME , etc .

    THREADS  CLEAR
      clears the topaz cache of intances of GsProcess

    See also ALLSTACKS.

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

1 TFILE
    input a tonel format class definition or class extension file.
    The methods within the file are all compiled.
    When reading a class.st file , class creation will be attempted if the
    class does not exist. If a new version of the class would be created, 
    an Error is signalled. For details, see
       exec RowanKernel_tonel at: #RwTopazTonelReader %
       set class **
       list method createClassFrom:

1 TMETHOD
    Compile a method from tonel format.
    Intended for interactive use
      TMETHOD
      <paste a tonel format method defintion into topaz input>

    The tonel method definition must end with ']' on the beginning of a line.

    Compiles the method using class from the tonel method definition
    and using the current compilation environment (see ENV).
    Does not change topaz's current class .

1 TOPAZPAUSEFORDEBUG
    TOPAZPAUSEFORDEBUG [errorNumber]
    Provided to assist internal debugging of a session

    The C function void TpPauseForDebug(void), which has no effect,
    is called once. You can set a C debugger breakpoint on TpPauseForDebug.

    After calling TpPauseForDebug,
      errorNumber > 0  : topaz should halt and wait for a C debugger
        to attach (or dump core)
        on the next ocurrence of that GemStone error , after the error
        has been returned to topaz via a topaz call to GciErr() .
        The halt is in the topaz code after the error is returned.
       errorNumber = 0 :  clear the topaz halt-on-error number
       errorNumber < 0  : has no effect.

   See also PAUSEFORDEBUG

1 TOPAZWAITFORDEBUG
    Waits forever in a sleep loop until a C debugger (dbx or gdb)
    is attached to continue execution.
    If topaz is a topaz -l configured with GEM_LISTEN_FOR_DEBUG,
    will cooperate with another topaz attaching via DEBUGGEM .
    If the topaz that attached via DEBUGGEM disconnects ,
    execution will continue.

1 TRCLASSMETHOD:
    Compiles a class method for the trait whose name you give as a parameter.
    The trait of the new method will automatically become the current trait.
    If you don't supply a trait name, the new method is compiled for the
    current trait (as set with the SET TRAIT:, TRFILEOUT TRAIT:, TRMETHOD:,
    or TRLIST CATEGORIESIN: command).
    Compiles in the compilation environment 0.


    Text of the method should follow the TRCLASSMETHOD: command on subsequent
    lines. The method text is terminated by the first line that starts
    with the '%' character. For example:

           TRCLASSMETHOD: TAnimal
           returnAString
              ^ String new
           %

    After the method has been successfuly compiled in the trait, the method will
    be compiled in the dependent classes registered for the class side trait. 

1 TRFILEOUT
    Writes trait definitions and/or methods to a named file in a format
    that can be fed back into Topaz with the INPUT command.

    The current compilation environment(see ENV) is ignored by traits
    and environment 0 is exclusively used.

    If you supply a parameter that does not match one of the FILEOUT
    sub-commands, Topaz will assume it is a method selector for the
    selected trait and will attempt to file it out.

    Examples:
      trfileout trait: TReadStreamLegacy tofile: tlegacy.gs format: 8bit

      set trait TReadStreamLegacy
      trfileout category: 'Instance Creation' tofile: tlegacy.gs format: utf8

    Keyword arguments must be provided in this order
       exactly one of     TRAIT: CATEGORY: CLASSCATEGORY: METHOD: CLASSMETHOD:
       optional           TOFILE:
    If TOFILE: was given, then it may be followed by an optional  FORMAT:

    If the format: is omitted output it is controlled by the last FILEFORMAT.
    A FILEFORMAT command reflecting the way output was generated
    is written as the first line of the output file.

2 TOFILE:
    The output of the TRFILEOUT command is sent to the file that you name
    following the TOFILE: keyword. For example:

        trfileout trait: TReadStreamLegacy tofile: tlegacy.opl

    If you specify a host environment name such as $HOME/foo.bar in UNIX
    as the output file, Topaz will expand that name to the full filename.

    If the output file does not contain an explicit path specification, Topaz
    writes to the named file in the directory in which you started Topaz.

    If the filename begins with '&' , the '&' is discarded and output
    is appended to the specified file, otherwise the specified file
    is overwritten.

2 FORMAT:
    Overrides the current FILEFORMAT setting . Argument must be
    a string, either UTF8 or 8BIT . The FORMAT: keyword must
    be after a TOFILE: keyword.
    Example:
      trfileout trait: TReadStreamLegacy tofile: tlegacy.gs format: 8bit

2 TRAIT:
    Writes out the trait definition and all the method categories
    and their methods. The trait that you file out will be selected
    as the current trait for use with other Topaz commands.
    Example:
      trfileout trait: TReadStreamLegacy tofile: tlegacy.gs

    To write out the definition of the current trait, type:

        trfileout trait: ^

2 CATEGORY:
    Writes out all the methods contained in the named category
    for the current trait.
    Example
      set trait TReadStreamLegacy
      trfileout category: 'Accessing' tofile: tlegacy.gs format: utf8

2 CLASSCATEGORY:
    Writes out all the class methods contained in the named category
    for the current trait.
    Example:
      set trait TReadStreamLegacy
      trfileout classcategory: 'Instance Creation' tofile: tlegacy.gs format: utf8

2 CLASSMETHOD:
    Writes out the specified class method (as defined for the current
    class). The category of that method is automatically selected
    as the current category for use with other Topaz commands.
    Method lookup uses current compilation environment (see ENV).
    Example:
      set trait TReadStreamLegacy
      trfileout classmethod: new

2 METHOD:
    Writes out the specified method (as defined for the current class).
    The category of that method is automatically selected as the current
    category for use with other Topaz commands.
    Method lookup uses current compilation environment (see ENV).
    Example:
        set trait TReadStreamLegacy
        trfileout method: next

    You may omit the "METHOD:" keyword if the method selector does not
    conflict with any of FILEOUT's subcommands. For example, to file
    out a method named "category:", you'd need to explicitly include the
    METHOD: keyword as shown here:

        trfileout method: category:

1 TRIMPLEMENTORS
    Expects one argument, an selectorSpec, the value of which
    is either a String or Symbol .

    Equivalent to a DOIT of
      (ClassOrganizer newForEnvironment: <current env>) traitImplementorsOfReport: aString
    which reports implementors of (aString asSymbol) in Traits.
    May require larger than default GEM_TEMPOBJ_CACHE_SIZE configuration.
    See <selectorSpec> in Object_Specification_Formats
    DEFINE CurrentClassOrganizer  will override the class organizer used.

1 TRLIST
     This command is used in conjunction with the SET and EDIT commands
     to browse through traits and trait methods in the database.

2 TRAITS
    Lists all of the dictionaries in your symbol list and all of the traits
    they contain.

    Takes an optional argument aString, if given, limit the result to
    those traits for which  (aTrait name includesString: aString)==true.
      example  TRLIST TRAITS Legacy

2 TRAITSIN:
    Lists the traits in a specific dictionary. For example:

       trlist traitsin: UserGlobals

    LIST TRAITS is the for all dictionaries.

2 CATEGORIESIN:
    Lists all of the instance and class method selectors for the named
    trait, by category. If you do not specify a trait name, the categories
    of the current trait will be listed. If you do specify a trait name,
    that trait becomes the current trait for subsequent Topaz commands.
    (The current class is also set with the SET TRAIT:, FILEOUT TRAIT:,
    or TRMETHOD: command.)

2 CCATEGORIES:
    Lists all of the class method selectors for the named trait, by 
    category. If you do not specify a trait name, the class categories
    of the current trait will be listed. If you do specify a class name,
    that class becomes the current class for subsequent Topaz commands.

2 CLASSMETHOD:
    With an argument that is a <selectorSpec> ,
    lists the category and source of the given classmethod selector for
    the current trait in the compilation environment 0 (see ENV). (The 
    current trait is set with the SET TRAIT:, TRFILEOUT TRAIT:, TRMETHOD:, 
    or TRLIST CATEGORIESIN: command) . 
    See <selectorSpec> in Object_Specification_Formats

2 CMETHOD:
    TRLIST CMETHOD: is equivalent to TRLIST CLASSMETHOD:
    Uses compilation environment 0 (see ENV).

2 CSELECTORS
    List selectors of all class methods for the current trait in compilation 
    environment 0 (see ENV). May be abbreviated as CSEL . Accepts an 
    optional string token, example:   LIST CSEL policy lists only selectors 
    which contain 'policy' using case-insensitive match.

2 CPRIMITIVES
    List selectors of all class methods for the current trait in compilation 
    environment 0 (see ENV) which are primitives, May be abbreviated as CPRIM .
    Accepts an optional string token, example:   TRLIST CPRIM at lists only 
    selectors which contain 'at' using case-insensitive match.

2 ICATEGORIES:
    Lists all of the instance method selectors for the named trait, by category.
    If you do not specify a trait name, the categories of the current trait 
    will be listed. If you do specify a trait name, that trait becomes the 
    current trait for subsequent Topaz commands.

2 LINENUMBERS
    List the current trait method with line numbers prefixed to the source lines.
    The current method is the method specified by the last TRLOOKUP command .

2 METHOD:
    With an argument that is a selector, lists the category and source of
    the given instance method selector in the current trait and compilation 
    environment 0 (see ENV). (The current trait is set with the SET TRAIT:, 
    TRFILEOUT TRAIT:, TRMETHOD:, or TRLIST CATEGORIESIN: command.)

    Example 2
       set trait TObject
       trlist method doesNotUnderstand:

2 PRIMITIVES
    List selectors of all instance methods in the current trait and
    compilation 0 (see ENV)  which are primitives.
    May be abbreviated as PRIM .
    Accepts an optional string token, example:   TRLIST PRIM at
    lists only selectors which contain 'at' using case-insensitive match.

2 SELECTORS
    List selectors of all instance methods in the current trait and
    compilation environment 0 (see ENV). May be abbreviated as SEL .
    Accepts an optional string token, example:   LIST SEL policy
    lists only selectors which contain 'policy' using case-insensitive match.

1 TRLOOKUP
    TRLOOKUP meth <selectorSpec>
    TRLOOKUP method <selectorSpec>
    TRLOOKUP cmeth <selectorSpec>
    TRLOOKUP classmethod <selectorSpec>

    The arguments after 'TRLOOKUP' are case sensitive.
    Using the current trait , search for specified instance or class method
    Print the trait in which method found, and list the category and source 
    code . See <selectorSpec> in Object_Specification_Formats .

    TRLOOKUP <traitname> >> <selectorSpec> [envIdInteger]

    Make the specified trait the current trait,
    and do a lookup for the specified instance method
    A <traitname> may not be one of 'meth', 'method', 'cmeth', 'classmethod'

    TRLOOKUP <traitname> class >> <selectorSpec> [envIdInteger]

    Make the specified trait the current trait,
    and do a lookup for the specified class side method.
    A <traitname> may not be one of 'meth', 'method', 'cmeth', 'classmethod'

1 TRMETHOD:
    Compiles an instance method for the trait whose name you give as a
    parameter. The trait of the new method will automatically become the
    "current" trait. If you don't supply a trait name, the new method is
    compiled for the current trait (as set with the SET TRAIT:, TRFILEOUT
    TRAIT:, TRMETHOD:, or TRLIST CATEGORIESIN: command).
    Compiles in the compilation environment 0.

    Text of the method should follow the TRMETHOD: command on subsequent
    lines. The method text is terminated by the first line that starts
    with the '%' character. For example:

         TRMETHOD: TEmployee
         name
            ^ name
         %

    After the method has been successfuly compiled in the trait, the method will
    be compiled in the dependent classes registered for the instanceside trait.

1 TRREMOVEALLCLASSMETHODS
    Removes all class methods in from the trait whose name you give as a parameter.
    The specified trait will automatically become the "current" trait.

    Example:    trremoveallclassmethods TArray

    This command may not be abbreviated.

1 TRREMOVEALLMETHODS
    Removes all methods from the trait whose name you give as a parameter.
    The specified trait will automatically become the "current" trait.

    Example:    trremoveallmethods TArray

    This command may not be abbreviated.

1 TRSTRINGS
    Reports Trait methods that contain the argument in their source string, and
    trait comments that include the argument. The comparison is case-sensitive.

    Expects one argument, an objectSpecification, the value of which
    may be a String or Symbol. The search is in the compilation
    environment 0 (see ENV).

    Equivalent to:
      run
      | org | org := ClassOrganizer new.
      org traitStringsReport: (aString) ignoreCase: false includeTraitComments: true
      %

    May require larger than default GEM_TEMPOBJ_CACHE_SIZE configuration.
    Cannot be abbreviated.
    DEFINE CurrentClassOrganizer  will override the class organizer used.

1 TRSTRINGSIC
    Reports Trait methods that contain the argument in their source string, and
    trait comments that include the argument. The comparison is case-insensitive.

    Expects one argument, an objectSpecification, the value of which
    may be a String or Symbol. The search is in the compilation
    environment 0 (see ENV).

    Equivalent to:
      run
      | org | org := ClassOrganizer new.
      org traitStringsReport: (aString) ignoreCase: true includeClassComments: true
      %

    May require larger than default GEM_TEMPOBJ_CACHE_SIZE configuration.
    Cannot be abbreviated.
    DEFINE CurrentClassOrganizer  will override the class organizer used.

1 UNPROTECTMETHODS
    Cancels the effect of PROTECTMETHODS .

1 UP
    UP (with no arguments) -- In the current stack, change the current
    frame to be the caller of the current frame, and display the
    frame thus selected.

    UP <anInteger> -- Go up anInteger frames , make that the
    current frame, and display the frame thus selected.

1 WHERE
    Display frames of the current stack.
    Abbreviations W, WH will resolve to WHERE.
    See also THREADS, THREAD .

    WHERE
      Display entire current stack, one line per frame.

    WHERE <anInteger>
    WHERE +<anInteger>
       Display anInteger frames of the current stack,
       starting at the current frame, one line per frame.

    WHERE -<anInteger>
       display anInteger+1 frames ending with current frame

    WHERE +-<anInteger>
       display anInteger frames before current frame, current frame,
      and (anInteger-1) frames after current line

    WHERE +-
       same as WHERE +-5
    WHERE -
       same as WHERE -5
    WHERE +
       same as WHERE 5

    WHERE aString
       aString is a string not beginning with any of
         decimal digit, whitespace,  or any of the 3 characters ' + -
       and not containing whitespace.
       Searches all frames, and displays only those for which output of WHERE
       for that frame matches case-sensitive search for aString anywhere
       in that frame's output(not including the frame number or ==> marker
       at start of frames's line). Current frame is set to first frame
       matched by the search.

    WHERE 'bString'
       same as  for    WHERE aString    but bString may contain digits and
       whitespace characters.

1 Overview
    Topaz is a command-driven interface to the GemStone data management
    system. It provides commands for browsing classes, creating, debugging,
    and executing GemStone Smalltalk code, and inspecting and modifying
    GemStone objects.

    You can stop a command at any time by typing CTRL-C. Topaz may
    take a moment or two before halting the current operation. For more
    information, see topaz help topic Breaks.

    Topaz command lines are limited to 64K characters.

    A topaz command line may contain multiple commands separated by the
    semicolon character ( $;  in Smalltalk syntax), subject
    to the following limitations
      Commands with special behavior for "rest of command line"
        SPAWN  rest of line passed directly to shell
        SHELL  rest of line passed directly to shell
        IFERR  single command only, semicolon not allowed
        IFERROR single command only, semicolon not allowed
        REMARK  rest of line ignored as a comment
        RUN, DOIT, PRINIT   ignores the rest of the line
        EXEC  rest of line up to % or end of line is execution source
        INPUT, OUTPUT   semicolon not allowed

      Lines with ! or # as first character on the line are comments
      and the entire line is ignored as a comment

      DOIT, RUNENV and PRINTIT behave the same as RUN with regard
      to remainder of the line.

      Example of a EXEC command followed by  TIME
          EXEC String withAll:'abc' %; TIME

      For all other commands, the command is terminated by
      the end of line, or the first semicolon
      not within a quoted string, which ever occurs first.
      Quoted strings are delimited by single quotes ,
      i.e. $' in Smalltalk source syntax.

    For more on using help, see the help topic help.

    The "Topaz Programming Environment" manual provides further details on
    using topaz.

1 Abbreviations
    Most commands, except in particular ABORT, COMMIT, EXIT, LOGOUT, and
    QUIT and the OUTPUT keywords PUSH and POP may be abbreviated as much
    as you wish. Other exceptions are listed under the specific command.

    When an abbreviation matches more than one Topaz command, Topaz will
    list every command that the abbreviation matches (excepting ones that
    require a valid session when there is none). You may then reenter the
    command with further characters to remove ambiguity.

1 Blanks
    Topaz ignores any white space at the beginning of a line
    or between parameters. However, it is good practice to
    use white space to separate parameters. Do not use
    colons, commas, and other non-alphanumeric characters
    separate keywords and parameters. For example:

        object anObject at: 5 put: 6         <--- valid

        object anObject at:5 put: 6          <--- NOT valid

1 Break_Handling
    If you type Ctrl-C while Topaz is waiting for input,
    Topaz will automatically abort the current command.
    If you type Ctrl-C while Topaz is NOT waiting for input,
    and you are logged in to GemStone, Topaz will send a soft-break
    request to GemStone. A second Ctrl-C typed before GemStone can
    respond to the soft-break will cause a hard-break to be sent
    to GemStone .

    A hard break during the following Repository methods will kill
    the session, otherwise the hard-break terminates GemStone Smalltalk
    execution.
        markForCollection,  fullBackupTo:,  restoreFromBackup
        objectAudit, auditWithLimit:, repairWithLimit:
        pagesWithPercentFree,

    If you type Ctrl-C three times before Topaz is able to redisplay
    its prompt, Topaz will attempt to exit immediately.
    If you are running topaz -l  ($GEMSTONE/bin/topazl), and are logged
    in using a linkable session, then topaz will wait for shared memory
    data structures to reach a safe state before exiting.

1 DEBUGGEM
   May not be abbreviated.
   Takes two integer arguments, a processId and a token

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

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

   Attempts to attach to that gem or topaz -l and create a
   topaz session in this topaz process which has debugging control over
   the target session .

   If Smalltalk execution is in progress in the target session,
   it is interrupted by signalling a SoftBreak and DEBUGGEM
   will print the SoftBreak error followed by a topaz prompt. At this point
   you can debug the stack of that SoftBreak . If SoftBreak does not
   interrupt the execution a HardBreak is signalled. If the execution
   is in a long running primitive or waiting for stone , it may not
   respond and the DEBUGGEM will fail.

   It is recommended that an error handler invoke System class >> waitForDebug
   to wait for a topaz -r to attach with DEBUGGEM .
   In a topaz session created with DEBUGGEM,
     KILL will execute  kill -TERM against the topaz -l or gem being debugged,
     CONTINUE sets waitForDebug state to resume (using System __sessionStateAt: 26 put: 2)
            and stays attached to possibly handle other errors or breakpoints.
     DETACH  executes GciLogout and the gem remains in  waitForDebug,
            you can execute DEBUGGEM again to reconnect .
     LOGOUT executes GciLogout and the gem remains in  waitForDebug,
            you can execute DEBUGGEM again to reconnect .
     RESUME sets waitForDebug state to resume (using System __sessionStateAt: 26 put: 2),
            and does GciLogout
     STEP   sets waitForDebug state to resume (using System __sessionStateAt: 26 put: 2),
            and then does the single step

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

   If the target session was executing in a topaz script and stopped
   because of IFERR N TOPAZWAITFORDEBUG, you should have DISPLAY OOPS,
   and IFERR 1 WHERE before  IFERR 2 TOPAZWAITFORDEBUG in your topaz
   initialization script. Then the stack printed by the target topaz
   to its output or log files will end with  GsProcess ... MMM ,
   where MMM is an oop .
   In your interactive topaz after the DEBUGGEM succeeds ,
   STACK SET @MMM  will set the active stack, after which you can debug
   with WHERE, FRAME, etc .

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

1 Debugging_Smalltalk
    Topaz can maintain up to 500 simultaneous GemStone Smalltalk call
    stacks that provide information about the GemStone state of execution.
    Each call stack is made up of frames which represent
    method or block activations.

    Topaz provides debugging commands that enable you to:
     o  Step through execution of a method.
     o  Inspect/change the values of arguments, temporaries, and receivers.
     o  Set, clear, and examine GemStone Smalltalk breakpoints.

    For the purpose of determining exactly where a "step" will go during
    debugging, a GemStone Smalltalk method can be decomposed into "step points".
    The locations of step points also determine where interpreter breakpoints
    can be set. Generally, step points correspond to message sends,
    method returns and assignments.

2 Debugging_Commands
    Here's a quick overview of Topaz debugging commands. For more
    information, see the top-level help for the desired command.

   Stacks
     WHERE -- display current stack one line per frame  ('==>' shows current frame),
              will accept arguments to display just part of the stack.
     FRAME -- print currently selected frame, and the receiver, args and temps
     FRAME <n> -- goto specified frame and print with receiver, args and temps
     UP    -- go to caller of current frame and print with receiver, args and temps
     DOWN  -- go go callee of current frame and print with receiver, args and temps

     STACK NOSAVE [default] --- the current call stack will be automatically
       terminated via a GciClearStack by the next of
       any of these commands: DOIT, PRINTIT, RUN, SEND, EDIT LAST, EDIT NEW TEXT.
     STACK SAVE -- protect the current call stack from termination
     STACK DELETE -- terminate a specific call stack.

     THREADS - list the saved stacks, plus those known to the ProcessorScheduler
     THREAD <N> - make the specified stack the current stack, where N
              specifies an element of the list shown by THREADS

   Breakpoints
     BREAK METHOD -- halt execution at a step point within a method.
     BREAK MESSAGE -- halt execution before a selector is sent to an
       instance of a chosen class.
     BREAK DELETE -- delete a breakpoint.
     BREAK LIST -- list all currently set breakpoints.
     LIST BREAKS -- display all breakpoints currently set in a method.
     LIST STEPS -- list the source code of a method and display all step
       points (allowable breakpoints) in that source code.

   Step Through a Method
     CONTINUE execution after a breakpoint is encountered.
     STEP through a method after a breakpoint is encountered.

   Temporaries
     TEMPORARY -- examine or modify the values of temporaries.

   Legacy commands
     STACK -- display all frames in the current call stack, with
       receiver, args and temps printed for each frame
     STK --   same as WHERE
     STACK SCOPE -- print the current frame within the current stack
     STACK ALL -- replaced by THREADS
     STACK CHANGE -- select a different call stack to be "current",
             replaced by THREAD <N>

1 ExitClientError
   If an ExitClientError is signalled to the GCI of a interactive topaz -l process,
   and the topaz -l was configured with GEM_LISTEN_FOR_DEBUG=true in a config
   file or -C argument or by executing System listenForDebugConnection, topaz
   will stop to allow the ExitClientError to be debugged, rather than exiting.
   See also class comments in ExitClientError .

1 Initialization
    Before you can log in to GemStone (via the LOGIN command), you
    need to establish values for network and other parameters.
    You can create a Topaz initialization file that contains SET
    commands which establish the required parameter values.
    In this way, you can define parameter values once -- in the
    initialization file -- so that you won't need to explicitly provide
    those values each time you log in.

    When you start Topaz, it looks for this initialization file.

          In UNIX, the file is named .topazini

    If the initialization file is present, Topaz files it in.

2 Required_Parameters
    The following values must be established -- either interactively or
    in your Topaz initialization file -- before you can log in to GemStone:

        SET HOSTUSERNAME:   Your user account on the host computer
        SET HOSTPASSWORD:   Your password on the host computer
        SET GEMNETID:       Name of the GemStone service on the host computer
                               (defaults to gemnetobject)
        SET GEMSTONE:       Name of the Stone (database monitor) process
        SET USERNAME:       Your GemStone user ID

    (With linked Topaz, only the last two values are required.)

    For more information, see the Help information for the SET command
    or Chapter 1 of your Topaz manual.

1 Local_Variables
    Topaz allows you to define local variables. These variables associate
    local names with database objects so that you can keep track of the
    results of database messages without memorizing OOP values. The DEFINE
    command is used to create, display, and delete local definitions.

    You can use local variables in the OBJECT, SEND, and other commands.
    When you do, your local definition overrides any object with
    the same name in the database.

    Local symbols may be up to 255 characters in length, must begin with
    a letter (a-z) or an underscore, and may not contain white space.

    Topaz automatically creates several definitions for you. You
    can examine these definitions and use them in most Topaz commands,
    but you can't change them with the DEFINE command. For more
    information, select the Help subtopic "Local_Definitions".

2 Local_Definitions

     myUserProfile     the OOP of your GemStone UserProfile object

     ErrorProcess      the OOP of the last GemStone Smalltalk execution
                       error process; used in the CONTINUE command.

     LastText          the OOP of the last text compiled for execution
                       with a RUN, PRINTIT, DOIT, METHOD: or CLASSMETHOD:
                       command.

     LastResult        the OOP of the result of the last RUN, PRINTIT, DOIT,
                       SEND or CONTINUE command.  nil if the last such
                       command generated an error.

     CurrentClass      the OOP of the current class (set by the last
                       command taking a class name as a parameter).

     CurrentCategory   the OOP of the current method category.

     ErrorCount        the number of errors encountered during this
                       invocation of the topaz executable.

2 Examples
      DEFINE var1 **      saves the last result in local variable "var1".

      DEFINE var2 var1 entryAt: 4
        sends "entryAt:" to the object named "var1" (in this case
        a local variable defined on the previous line) and saves the
        result in the local variable "var2".

      DEFINE var3 1.444 * 47e32
        sends "*" to the float object "1.444" with arg "47e32"
        and saves the result in the local variable "var3".

      DEFINE              displays all current local variable definitions.

      DEFINE var3         removes the definition of "var3".

1 Linked_vs_RPC

    Two versions of Topaz are available to you: linked and "remote
    procedure call" (RPC). You can use linked Topaz to significantly
    enhance performance. In linked Topaz, your Topaz session and Gem
    (the GemStone session) exist as a single process. To invoke
    linked Topaz, you use the operating system command "topaz -l" in
    place of "topaz".

    Topaz can only be linked with a single GemStone session
    process. If you issue the login command to create multiple sessions,
    the new sessions are RPC sessions rather than linked.

1 Multiple_Sessions

    Topaz can keep several independent GemStone sessions alive
    simultaneously, allowing you to switch from one session to another
    with the SET SESSION command.

2 Example

    In this example, a user creates a second session, makes the new
    session his current session, then returns to the original session.

        topaz 1> login
        GemStone password? <password typed here but not echoed>
        topaz 2> run
        userglobals at: #myVar put: 1
        %
        1
        topaz 2> set session 1
        topaz 1>

1 Network_Resource_String

    A network resource string (NRS) provides a means for uniquely
    identifying a GemStone file or process by specifying its location on
    the network, its type, and authorization information. GemStone
    utilities use network resource strings to request services from a
    NetLDI.

    For example:

         topaz > set gemstone !tcp@oboe!testserver

    Example of an alternate netldi, other than the default gs64ldi
      assumming mynetldi is in the Unix services :
          topaz > set gemnet !@oboe#netldi:mynetldi!gemnetobject
      alternative using the netldi's listening port:
          topaz > set gemnet !@oboe#netldi:10027!gemnetobject

    Refer to your Topaz user manual for a detailed description of
    NRS syntax.

1 Object_Specification_Formats

    The following are legal <objIdentitySpec>
      @<integer>     an unsigned 64-bit decimal OOP value
      <integer>      a signed 61-bit literal SmallInteger object
      $<character>   a literal Character object
      text           the GemStone object with the specified name (either
                     a Smalltalk variable name or a local variable created
                     with the DEFINE command)
      **             the OOP of the result of the last execution
      ^              the current class

    The following are legal <literalObjectSpec>
      'text'         a literal String object
      #text          a literal Symbol object (no white space allowed)
      #'t e x t'     a quoted literal Symbol
      <float>        a Float object (a C double-precision floating point number)

    The following are legal <selectorSpec> . There is no enforcement in
    the command parsing of the quoted form being a valid method name.
      text
      'text'         a literal String object
      #text          a literal Symbol object (no white space allowed)
      #'t e x t'     a quoted literal Symbol
    The resulting token becomes String object and is later converted
    to a Symbol if required by the command.

    For most topaz commmands that take an object specification, you may
    specify either an <objIdentitySpec> or <literalObjectSpec>.

    In commands EXPECTVALUE, EXPECTERROR and EXPECTBUG, you may use the
    following <objInstancesOfSpec>, as well as <objIdentitySpec> and
    <literalObjectSpec>.

    The following are legal <objInstanceOfSpec>
      %text         specifies any instance of the class with symbolic name
                    "text"

      /text         specifies any kind of the class with symbolic name "text" .
                    GciIsKindOf(<result>, <class with symbolic name "text">)
                    is used to determine is-kind-of .

      %@<integer>   specifies any instance of the class with OOP <integer>

      /@<integer>   specifies any kind of the class with OOP <integer>


1 Specifying_Objects
    Certain commands (such as OBJECT and SEND) require you to specify GemStone
    objects that you want to work with. Here are some ways to do this:

    @<integer>     a signed 32-bit decimal OOP value
    <integer>      a 31-bit literal SmallInteger object
    <float>        a Float object (a C double-precision floating point number)
    $<character>   a literal Character object
    'text'         a literal String object
    text           the GemStone object with the specified name (either
                   a Smalltalk variable name or a local variable created
                   with the DEFINE command)
    #text          a literal Symbol object (no white space allowed)
    **             the OOP of the result of the last execution
    ^              the current class

2 Example
    Here is an example of how you might use object specification formats:

      topaz> display OOPS
      topaz> level 0
      topaz> !  First, send the message "entries" to the object named 'OFS'
      topaz> send OFS entries
  RESULT --> [11324 sz: 1 cls: 261] an Array
      topaz> !  Now send "at:" to that Array, with one arg: the SmallInteger 1
      topaz> send @11324 at: 1
  RESULT --> [11325 sz: 5 cls: 10324] an OfsDirEntry
      topaz> !  Save the result (an OfsDirEntry) in the local var. "result"
      topaz> define result **
      topaz> !  Send "instVarAt:put:" to that OfsDirEntry, with 2 args:
      topaz> !     the SmallInteger 3 and the String 'this is a test'
      topaz> send result instVarAt: 3 put: 'this is a test'

1 String_Arguments
    A command parameter in Topaz is any sequence of non-white
    characters, or any sequence of quoted characters. Only
    single quote marks (') are recognized by Topaz. To include quote
    marks within a quoted parameter, double the internal quotes:

          'don''t do as I do, do as I say'

    Commands which expect a method selector as an argument will
    accept quoted or non-quoted strings with or without a # prefix,
    such as
          at:put:
          #at:put:
          'at:put:'
          #'at:put:


