!========================================================================
! Copyright (C) VMware, Inc. 1986-2011.  All Rights Reserved.
!
! Name - topaz.hlp
!
! Description: 
!  help file for the Topaz program.  This is not a VMS help file.  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.
!
! $Id: topaz.hlp,v 1.28.2.1 2008-03-17 16:07:08 otisa Exp $
!
!========================================================================

  TOPAZ - a programmer's interface to the GemStone system 

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

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 ABORT
     Aborts the current GemStone transaction.

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

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

1 BEGIN
     Begins a GemStone transaction when your session is outside a
     transaction.  For use with #manualBegin transaction mode.
     (See GemStone Smalltalk class System). 

     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 your 
     GemStone Smalltalk code.  For more information about breakpoints,
     see Chapter 2 of the Topaz manual.

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.

        break method GsFile nextLine
            Establishes 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).

     See BREAK CLASSMETHOD for setting breakpoints on class methods.

2 CLASSMETHOD 

        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 Restrictions

    Message breakpoints are not supported in GemStone 5.0 .

    Other restrictions which existed in GemStone 4.1 no longer exist.

3 Object_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
       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

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 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
     Commits the current GemStone transaction.
     Although you can abbreviate most other Topaz commands and
     parameter names, COMMIT must be typed in full.

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.

     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 "GemStone Kernel Reference".

     For information about user-defined errors, see the chapter entitled
     "Handling Errors" in the "GemStone Programming Guide".

2 Object_Specification_Formats

    @<integer>     a unsigned 64-bit decimal OOP value
    <integer>      a 61-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
    

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

     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.

2 Object_Specification_Formats

    @<integer>     an unsigned 64-bit decimal OOP value
    <integer>      a signed 61-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 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 DISPLAY
     The DISPLAY and OMIT commands control the display of instance variable 
     names, hexadecimal byte values, and OOPs (object-oriented pointers).
     The DISPLAY command turns on these display attributes, and the OMIT 
     command turns them off.  

2 OOPS
     After you issue the DISPLAY OOPS command, OOP values will be displayed
     with database results.  For each object, 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
     OOP of the object's class.

2 BYTES
     After you issue the DISPLAY BYTES command, the display for each string 
     object will include the hexadecimal value of each byte.

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

2 ERRORCHECK

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


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"

     Use OMIT PAUSEONERROR to cancel this pause-on-error mode.

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.

1 DISASSEM

     Disassemble the specified GsMethod.
     Produces no output from customer executables. If the session is remote,
     the output goes to stdout of the remote Gem. 

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


       DISASSEM METHOD: <selector>
         Disassemble the specified instance method for the class previously
         set by the SET CLASS command.

       DISASSEM CLASSMETHOD: <selector>
         Disassemble the specified class method for the class previously
         set by the SET CLASS command.
     

1 DOIT

     Sends the text following the DOIT command to GemStone for execution
     and displays the OOP (object pointer) of the resulting object.
     (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
     %
     result oop is -1073741821

1 DOWN [<anInteger>]

    DOWN -- Go down one activation in currently selected stack, and display 
    the activation thus selected.  

    UP <anInteger> -- Go down anInteger activations and display
    the activation thus selected.    See also STACK DOWN

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 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
     PRINTIT or DOIT commands for executing blocks of code in batch processes.




     EDIT has several subcommands.  If you supply any other parameter 
     to EDIT, Topaz will assume that you are naming an existing instance 
     method that you wish to edit.  For example: 
     
         topaz> Set class Integer
         topaz> edit +
     
     will edit the method whose selector is + in class Integer.

     As shown here, before you edit an existing method, you must use 
     SET CLASS: to select the method's class.  (The category of the method
     you edit will be automatically selected as the current category.)
     
2 LAST
     Tells Topaz that you want to edit the text of the last 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.  

2 CLASSMETHOD:
     Allows you to edit the source code of an existing class method.  The 
     selector of the method should be given as a parameter.  For example: 
         
            topaz> Set class OfsDirectory
            topaz> Edit class 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.

2 METHOD:
     Allows you to edit the source code of an existing instance method.  
     The selector of the method should be given as a parameter.

     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.

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 EXIT [<status>]
     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 nonzero integer status is given, a nonzero status will be returned
     to the operating system.  A zero status will return a zero status to
     the operating system.

1 EXPECTBUG

  expectbug <bugNumber> [ value <resultSpec> [ <integer> ] |
                          error <errCategory> <errNumber> [ <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> <errNumber> [ <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.

      <errNumber> must be a legal topaz object specification
         which evaluates to a SmallInteger .

      <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:
     The "Fatal" bit is not checked .

     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 command
     commit
  has an internal result of  true  for success and  false  for failure.

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

  The command
     object
  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 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 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.

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

     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.

2 CLASSCATEGORY:
     Writes out all the class methods contained in the named category
     for the current class.

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.

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.

     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 FRAME [<anInteger>]

    FRAME  displays current activation of current stack , without temps

    FRAME  <anInteger> goto specified activation in current stack,
    and make the specified activation the current activation and 
    display that activation 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 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 stk 
        iferr 2 stack

     See also  IFERR_LIST, IFERR_CLEAR .

1 IFERR_LIST

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

1 IFERR_CLEAR

    Clears all of the post-error command buffers.

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

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

     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.

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 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 
     (the default) 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 will inhibit the display of objects.
     (However, object headers will still be displayed if you 
     specify DISPLAY OOPS.)  The maximum display level is 32767.
     Attempting to set the level to less than 0 generates an error.

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.  Setting a limit of 0 tells Topaz not to 
     limit the size of output.  By default, Topaz attempts to display all
     of an object, no matter how long.

       limit bytes 40
           Tells Topaz to display no more than 40 bytes of any byte object 
           (instance of String or one of String's subclasses).

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

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.  If 
     you type LIST with no additional keywords, Topaz lists the source code of
     the current method or block activation.  For more information, see
     the discussion of debugging in Chapter 2 of the Topaz manual.

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.

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

       list classesin: UserGlobals
     
     If no dictionary name is given, all of the dictionaries in your
     symbol list are listed along with the classes they contain.

2 CATEGORIESIN:
     Lists all of the instance and class method selectors for the named
     class, by category.  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 METHOD: 
     Lists the category and source of the given instance method selector for
     the current class.  (The current class is set with the SET CLASS:, 
     FILEOUT CLASS:, METHOD:, or LIST CATEGORIESIN: command.)

2 CLASSMETHOD:
     Lists the category and source of the given class method selector for
     the current class.  (The current class is set with the SET CLASS:, 
     FILEOUT CLASS:, METHOD:, or LIST CATEGORIESIN: command.)

2 STEP
     Lists the source code of the current method or block activation within
     the current stack and displays just the step point corresponding to
     the step point of the selected activation .

     (See STACK SCOPE to select a activation within a stack).

2 STEPS
     Lists the source code of the current method or block activation within
     the current stack and displays all step points in that source code.

     (See STACK SCOPE to select a activation within a stack).

2 STEPIPS
     Lists the source code of the current method or block activation within
     the current stack and displays IPs of all step points in that source code.

     (See STACK SCOPE to select a activation 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.  For example:

         list steps method: habitat

     You can use the BREAK METHOD command to set method breakpoints 
     at any step point.

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.

     You can use the BREAK METHOD command to set method breakpoints 
     at any step point.

2 BREAKS 
     Lists the source code of the current method or block activation,
     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.

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.

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 network communications 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.)
     For more information about these parameters, see the Help information
     on SET.  Also, see Chapter 1 of the Topaz manual.

     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 .
 

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

     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 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 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)
    <float>        a Float object (a C double-precision floating point number)

  For the purpose of most topaz commands we have the production:
    <objSpec> := <objIdentitySpec> | <literalObjectSpec>

  For the purpose of the commands EXPECTVALUE, EXPECTERROR and EXPECTBUG
  we have the following productions:

  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>

    <resultSpec> := <objSpec> | <objInstanceOfSpec>


1 OMIT
     The DISPLAY and OMIT commands control the display of instance variable 
     names, hexadecimal byte values, and OOPs (object-oriented pointers).
     The OMIT command turns off these display attributes, and the DISPLAY
     command turns them on.  

2 OOPS
     After you issue the OMIT OOPS command, OOP values will NOT 
     be displayed with database results.  (This is the default condition.)

2 BYTES
     After you issue the OMIT BYTES command, the display for each string 
     object will NOT include the hexadecimal value of each byte.
     (This is the default condition.)

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 RESULTCHECK
     Disables automatic error and result checking.  (See DISPLAY RESULTCHECK for
     details.)

2 ERRORCHECK
     same as  omit RESULTCHECK 

2 PAUSEONERROR

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

2 FLUSHOUTPUT

     Disables immediate flushing of topaz output files 
     (see DISPLAY FLUSHOUTPUT for details).

1 OPAL

     Same as DOIT.   Implemented for compatibility with previous releases.

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 can maintain a stack of up to 20 output files.  Current 
     interactions are captured in the file on top of 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. (this paragraph added for gss64 to document
     previously existing behavior).

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

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

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 <= 99 such that foo_N.out did
     not previously exist . If all 100 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


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 PRINTIT

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

     (If there is an error in your code, Topaz 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 + 2
        %
        4

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 UNPROTECTMETHODS

     Cancels the effect of PROTECTMETHODS .

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 REMOVEALLMETHODS
     Removes all methods 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 REMOVEALLCLASSMETHODS
     Removes all class methods 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 RUN
     Same as PRINTIT. Implemented for compatibility with previous releases. 

1 NBRUN

     Similar to PRINTIT, but execution is non-blocking, using GciNbExecute().
     To get the result , 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, but execution is non-blocking, using GciNbStep().
     To get the result , 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 SEND
     Sends a message to an object.  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 should be delimited by 
     one or more spaces or tabs.  A maximum of 20 keyword/argument pairs
     is allowed on the SEND command.

2 Object_Specification_Formats

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

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

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

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 GEMNETID:
     Establishes the name of the GemStone service on the host computer 
     (that is, the host process to which Topaz will be connected).  
     The default name is "gemnetobject".  If this doesn't work for you,
     see your GemStone data curator.

     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

     If you are using linked Topaz, GEMNETID is not used.

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

          SET GemStone: 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 GEMSTONE: !@theNode!theGemStoneName

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.  

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

     Sets the default components to be used in network resource string
     specifications. 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.  The STATUS command shows the value of NRSDEFAULTS
     unless it is the empty string.

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 host 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.
     
     If you're using linked Topaz, you may not use SET SESSION.

2 SOURCESTRINGCLASS

     Sets the class used to instantiate Smalltalk source strings 
     generated by RUN, EDIT, METHOD, and CLASSMETHOD commands.
     Examples

       set sourcestringclass String
       set sourcestringclass DoubleByteString
       set sourcestringclass IsoLatin

     The default source class is String.  The current source class is shown
     by the status command.  A  SET SESSION command will reset the
     source string class to the default.

2 SHAREDCACHE:

     If the argument is not 0 then the next linked login will use a
     shared cache. If the argument is 0 then the next linked login will
     just use private cache.
     Examples:
       set sharedcache: 0
       set sharedcache: 1

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 (from the UNIX Bourne shell) or LOGOUT (from VMS
     or from the UNIX C 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 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 (from the UNIX Bourne shell) or LOGOUT (from VMS
     or from the UNIX C 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
     Topaz can maintain up to 8 simultaneous GemStone Smalltalk processes
     that provide information about the GemStone state of execution.
     Each processes call stack is made up of method or block activations.

     When you type "STACK", Topaz displays all method or block activations in
     the current call stack, starting with the current activation.
     ("STACK 1" displays only the current method or block activation;
     "STACK 2" displays the current activation and its caller.)

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

     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 method or block activation of every call stack ("STACK 1"):
            *1  Lion (Object) | doesNotUnderstand: @ 9
             2  Lion (Animal) | habitat @ 3
             3  Executed Code
       The "*" indicates the current call stack, if one exists.  
       If there are no saved stacks, a message to that effect is displayed.

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.

2 DELETE

     STACK DELETE anInt
       Removes the call stack indicated by "anInt" in the STACK ALL display.

     STACK DELETE ALL removes all call stacks.

2 NOSAVE 

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

     See also STACK SAVE .

2 SAVE

     STACK SAVE causes your current call stack to be saved before executing 
       any of the commands listed for STACK NOSAVE.


2 SCOPE 

     STACK SCOPE 
       Displays the current scope within the current stack.

     STACK SCOPE <anInteger>
       Sets the method or block activation at the specified position within
       the current stack to be the current scope within that stack,
       and displays the new scope.

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

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


2 UP

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

     equivalent to STACK SCOPE <current scope + 1>

2 DOWN

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

     equivalent to STACK SCOPE <current scope - 1>

2 TRIM

     Trim the stack so that the current scope becomes the new top of stack,
     and that exection will resume at the first instruction in the method
     at new top of stack.  The new top of stack must not represent the
     activation 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 documentation of
     the method GsProcess>>__trimStackToLevel: for details.

1 STACKWAITFORDEBUG

     Displays all method or block activation in
     the current call stack, starting with the current activation.
     Then waits for a debugger to attach as defined for TOPAZWAITFORDEBUG.
     STACKWAITFORDEBUG takes no arguments.

1 STK 

     Similar to STACK except that parameters and temporaries for each
     activation 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 scope (as set by last STACK SCOPE, 
     STACK UP, or STACK DOWN)  with '==>'  .

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 activation
         record or its caller.  "Current activation record" is defined as
         the activation record specified 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
         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.


1 TEMPORARY
     Displays or redefines the value of one or more temporaries 
     in the current method or block activation previously specified by 
     a STACK or STACK SCOPE command.  The command  STACK 1  will show
     the the current activation.

     TEMPORARY Displays the names and values of all temporaries in the 
       current method or block activation.

     TEMPORARY preferences
       Displays the temporary named "preferences" in the current method
       or block activation.

     TEMPORARY preferences 'bouzouki'
       Redefines the value of the temporary named 
       "preferences" in the current method or block activation 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 activation.
       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 activation.


2 Object_Specification_Formats

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

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

    TOPAZWAITFORDEBUG

    Waits forever in a sleep loop until a C debugger (dbx or gdb)
    is attached to continue execution.  You will need to have tpaux.c
    be debuggable in order to be able to use the C debugger to
    change the loop control variable and have topaz execution continue .
    See the source code for implementation of cmdTpWaitForDebug 
    in tpaux.c .


1 QUIT [<status>]
     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 nonzero integer status is given, a nonzero status will be returned
     to the operating system.  A zero status will return a zero status to
     the operating system.

     QUIT has the same function as EXIT.

1 UP [<anInteger>]

    UP -- Go up one activation in currently selected stack, and display 
    the activation thus selected.  

    UP <anInteger> -- Go up anInteger activations and display
    the activation thus selected.      See also STACK UP

1 WHERE [<anInteger>]

    WHERE -- Display current stack, one line per activation, same as STK .
 
    WHERE <anInteger> -- Display anInteger activations of the current stack,
      starting at the current activation, one line per activation.

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. 
  
  All commands except ABORT, COMMIT, EXIT, LOGOUT, and QUIT (and the
  OUTPUT keywords PUSH and POP) may be abbreviated as much as you wish.
  When an abbreviation matches more than one Topaz command, Topaz will list
  every command that the abbreviation matches.  You may then reenter
  the command with enough characters to remove ambiguity. 
  
  You can stop a command at any time by typing CTRL-C.  Topaz may
  take a moment or two before halting the current operation.  

  Topaz command lines are limited to 511 characters.

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_in_Topaz

      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 Debugging_Smalltalk_DB_Code
    Topaz can maintain up to eight simultaneous GemStone Smalltalk call 
    stacks that provide information about the GemStone state of execution.
    Each call stack is made up of method or block activation.

    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
     STACK -- display all method or block activations in the current call stack.
     STK --   like STACK, but prints just one line per activation 
     STACK SCOPE -- show the current method or block activation within the
       current call stack or select a new current activation.
     STACK ALL -- display your list of saved call stacks.
     STACK CHANGE -- select a different call stack to be "current".
     STACK NOSAVE [default] --- delete the current call stack before executing 
       any of these commands: PRINTIT, SEND, DOIT, EDIT LAST, EDIT NEW TEXT.
     STACK SAVE -- automatically save the current call stack before
       executing any of the above commands.
     STACK DELETE -- delete a specific call stack.

     WHERE -- same as STK,  one line per activation  ('==>' shows current activation)
     FRAME -- print currently selected activation
     FRAME <n> -- goto specified activation and print it with temps
     UP    -- go to caller of current activation and print it with temps
     DOWN  -- go go callee of current activation and print it with temps
 
   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.

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 PRINTIT, DOIT, METHOD: or CLASSMETHOD:
                          command.

        LastResult        the OOP of the result of the last 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 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 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 Strings
     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'

     A string token is limited to 383 characters.
        
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 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 1> set gemstone !tcp@oboe!testserver
        
      Refer to your Topaz user manual for a detailed description of
      NRS syntax.
