1. Getting Started with Topaz

Overview of a GemStone Session

A GemStone session consists of four parts, as shown in Figure 1.1. These are:

• An application, in this case, Topaz.
• One repository and repository monitor (Stone), and the associated server processes. An application has one repository to hold its persistent objects.
• At least one GemStone session, or Gem process. All applications, including Topaz, must communicate with the repository through Gem processes. A Gem provides a work area within which objects can be used and modified. Several Gem processes can coexist, communicating with the repository through a single Stone process.

Figure 1.1   GemStone Object Server Components

Remote Versus Linked Versions

Figure 1.1 includes the two types of topaz sessions -- Remote Procedure Call (RPC) and Linked. With a Topaz RPC login, the Topaz application and the Gem session that provides the repository services exist in two separate processes. In a linked login, the Topaz application process includes the Gem session. These two types of sessions and configuration details are described in more detail in the System Administration Guide for GemStone/S 64 Bit.

To allow control over the use of linked logins, GemStone client libraries and Topaz provide separate versions; one of which allows RPC logins only, the other allowing both Linked and RPC.

• Topaz RPC is the default, although you may specify the -r command line argument. You can run multiple RPC sessions, but in Topaz RPC, linked logins are not possible.
• Topaz Linked requires specifying the -l command line argument to topaz. The -l argument is is required to allow topaz to login linked; you may additionally run multiple RPC sessions.

In Figure 1.2, notice that the Topaz startup banner’s PROGRAM line refers to Remote Session. In a linked login, it will say Linked Session.

Under Windows, only the RPC version of Topaz is available. The Gem, which is part of the server code, can only run on a server platform.

The examples in this chapter can be executed equally well from either linked or RPC Topaz.

For additional command-line options, see Appendix A.

Invoking Topaz

To invoke Topaz, simply type topaz on the command line. The program responds by printing its copyright banner and issuing a prompt, as shown in Figure 1.2.

% topaz

__________________________________________________________________________

|             GemStone/S64 Object-Oriented Data Management System          |

|               Copyright (C) GemTalk Systems 1986-2015                    |

|                            All rights reserved.                          |

+--------------------------------------------------------------------------+

|    PROGRAM: topaz, Linear GemStone Interface (Remote Session)            |

|    VERSION: 3.3.0, Thu Aug 18 14:47:21 US/Pacific 2015                   |

|      BUILD: 64bit-37204                                                  |

|  BUILT FOR: x86-64 (Linux)                                               |

|       MODE: 64 bit                                                       |

| RUNNING ON: 4-CPU benton x86_64 (Linux 3.2.0-58-generic #88-Ubuntu SMP Tue|

| Dec 3 17:37:58 UTC 2013) 5965MB                                          |

| PROCESS ID: 27630     DATE: 09/10/15 15:41:54 PDT                        |

|   USER IDS: REAL=gsuser (534) EFFECTIVE=gsuser (534) LOGIN=gsuser (534)  |

|__________________________________________________________________________|

topaz>

Topaz Commands

Topaz interaction is performed by sending commands. Each command begins with a keyword, and may have optional or required arguments. Some commands are only meaningful in certain contexts. Chapter 3 provides a list of the commands you will be using and the options and arguments for each command.

The first thing you will do is use the set command to provide login parameters, and use the login command to perform the login to GemStone. This is described in more detail in the next section.

The commands and keywords in Topaz are case-insensitive; so for example, the command login can be entered as LOGIN or Login. Arguments to topaz commands, however, such as user names or the names of Smalltalk classes, will follow their specific rules for case sensitivity.

You can abbreviate most Topaz command to uniqueness, so for example you can type log instead of login. Some commands such as logout may not be abbreviated, to avoid accidental use.

To enter an argument to a Topaz command that includes white space, enclose it within single quotes. For example, a username such as 'Issac Newton' requires quotes, while Issac_Newton does not.

Normally, each topaz command is on a separate line, and the command is terminated by the return at the end of the line. You may include multiple topaz commands on a single line by separating each expression with a semicolon (;).

Any text following a command that does not have arguments is ignored; topaz will print a warning to that effect after executing the valid portion of the line.

Logging In to GemStone

The first step in establishing a connection to GemStone and logging in is to give Topaz some information about the GemStone repository you will be using. To log in to the repository you must provide a GemStone user name and password.

The examples given here will be for RPC logins. Linked logins are similar. These examples also assume that the GemStone server configuration requires authentication in order to start the Gem session. This may not always be the case; see Configurations that do not require setting host information.

Here are the parameters to be established to log in to GemStone through Topaz:

• GemStone name. This the name of the Stone process to use and, optionally, the name of the network node on which it resides. The default name is gs64stone. If your Stone process is named gs64stone and is running on the local node, and the Gem process will also run on the local node, you don’t have to set the GemStone name.

Otherwise, specify the name of the Stone. If the node where the Stone is running is not the one where the Gem will run, you also need the name of the Stone host and perhaps the type of network connection between the Stone and Gem hosts. To specify a process named gs64stone running on node central, you can use a network resource string of the form !@central!gs64stone. Appendix B describes the syntax of network resource strings.

This is configured using the set command: set gemstone stonename.

• GemStone user name and password. These are defined within the GemStone server. You can log in using your personal username and password, created by your GemStone Administrator, or as predefined GemStone system users such as DataCurator. You may enter the user name and omit the password, in which case you will be interactively prompted for the password.

These are configured using the set command: set username gemStoneUserName and set password gemStoneUserPassword. You may abbreviate and combine them as
set user gemStoneUserName pass gemStoneUserPassword.

• host user name and password. The UNIX name and password for the account on the server that will own the Gem process. This are needed only for RPC sessions, and only if the NetLDI is configured to require this for authentication. You may enter the host user name and omit the host password, in which case you will be interactively prompted for the host password.

These are configured using the set command: set hostusername osUserName and set hostpassword osPassword. You may abbreviate and combine them as
set hostuser osUserName hostpass osPassword.

This is set using the command set hostusername and hostpassword.

• GemStone service name. For the RPC version the default is gemnetobject. You may also use gemnetdebug, if you are debugging memory issues, or the name of a customized version of the gemnetobject script that you have created.

For the linked version of Topaz, do not set gemnetid, nor set the gemnetid to ''.

NOTE
If you are running the linked version of topaz, and set gemnetid to gemnetobject, all your sessions will be RPC, in spite of having invoked the linked version. Use caution in using set gemnetid in topaz initialization files.

The gem service can be provided an NRS, in order to specify that the Gem process is running on a remote node. To do this, for the gemnetid, specify a network resource string of the form !@<remoteNode>#netldi:<netldiName>!gemnetobject. For example,

!@lark.gemtalksystems.com#netldi:gs64ldi!gemnetobject.

The GemStone service name is is configured using the set command: set gemnetid serviceName.

Use the Topaz set command to establish these parameters. For example:

topaz> set gemstone gs64stone

topaz> set username Isaac_Newton

For RPC login, you may need to also provide the host login credentials:

topaz> set hostusername newtoni

topaz> set hostpassword

Host Password? (Type your host password; it won’t be echoed)

To see your current login settings and other information about your Topaz session, type status:

topaz 1> status

Current settings are:

 display level: 0

 byte limit: 0 lev1bytes: 0

 omit bytes

 display instance variable names

 display oops   omit classoops   omit stacktemps

 oop limit: 0

 omit automatic result checks

 omit interactive pause on errors

 omit interactive pause on warnings

 listwindow: 20

 stackpad: 45

 tab (ctl-H) equals 8 spaces when listing method source

 transactionmode  autoBegin

 using line editor

   line editor history: 100

   topaz input is from a tty on stdin

EditorName________ vi

CompilationEnv____ 0

Source String Class  String

fileformat			   8bit (tty stdin is utf8)

Connection Information:

UserName___________ 'Isaac_Newton'

Password __________ (set)

HostUserName_______ 'newtoni'

HostPassword_______ (set)

NRSdefaults________ '#netldi:gs64ldi'

GemStone___________ 'gs64stone'

GemStone NRS_______ '!#encrypted:newtoni@password#server!gs64stone'

GemNetId___________ '!#encrypted:newtoni@password!gemnetobject'

CacheName__________ (default)

Browsing Information:

Class_____________

Category__________ (as yet unclassified)

If you are will be logging in linked, certain login parameters (HostUserName and HostPassword) have no effect. Setting GemNetId will result in an RPC login.

If any login settings are incorrect, use the set command to fix them.

You are now ready to issue the login command, connecting your Topaz session to the GemStone repository:

topaz> login

GemStone password? (type your GemStone password)

[Info]: libssl-3.3.0-64.so: loaded

[05/14/2015 15:02:40.874 PDT]

  gci login: currSession 1  rpc gem processId 1363 

successful login

topaz 1>

As this example shows, Topaz displays a session number in its prompt once you have logged in. In the topaz RPC version, these numbers start with 1. In the linked version of topaz, session 1 is the linked session, and the RPC session numbering starts with session 2.

You may supply several of these login parameters on a single command line in any order, and abbreviate the parameter names:

topaz> set gemstone gs64stone user Isaac_Newton pass gravity

topaz> set hostuser 'newtoni'

topaz> set hostpass <return>

Host Password? (type your host password)

topaz> login

[Info]: libssl-3.3.0-64.so: loaded

[05/14/2015 15:02:40.874 PDT]

  gci login: currSession 1  rpc gem processId 1363 

successful login

topaz 1> 

Because setting the host user name causes Topaz to discard the current host password, you must set hostusername before hostpassword.

If you are using the linked version of Topaz, you can login with fewer set commands:

topaz> set gemstone gs64stone user Isaac_Newton pass gravity

topaz> login

[Info]: LNK client/gem GCI levels = 33000/33000

[Info]: libssl-3.3.0-64.so: loaded

[Info]: User ID: Isaac_Newton

[Info]: Repository: gs64stone

[Info]: Session ID: 5

[Info]: GCI Client Host: <Linked>

[Info]: Page server PID: -1

[Info]: Login Time: 05/14/2015 15:00:39.542 PDT

[05/14/2015 15:00:39.543 PDT]

  gci login: currSession 1  linked session 

successful login

topaz 1>

Setting Up a Login Initialization File .topazini

You can streamline the login process by creating an initialization file that contains the set commands needed for logging in. When you invoke Topaz, it automatically executes those commands for you. If you insert set hostpassword and login commands without parameters, Topaz automatically prompts you for the necessary values.

You may also explicitly specify a path for a topazini file on the command line where you started up the Topaz executable. Using this option overrides any topazini files that Topaz would otherwise use.

% topaz -I /gemstone/utils/mylogin.topazini

If you want to run Topaz non-interactively, you must explicitly specify both the GemStone and host passwords in this initialization file.

CAUTION:
Entering your passwords in a file can pose a security risk.

The Topaz initialization file shown in Figure 1.3 performs most of the same functions as the interactive commands shown in the previous discussion.

set gemstone gs64stone

set username Isaac_Newton

set password mypassword

set hostusername 'newtoni'

set hostpassword hostpassword

login

GemStone Password?     Type your password. It will not be echoed.topaz 1>

set gemnetid gemnetobject

Multiple Concurrent GemStone Sessions

Topaz can keep several independent GemStone sessions alive simultaneously. This allows you to switch from one session to another, for instance to access more than one GemStone repository. Both RPC and linked versions of Topaz allow you to run multiple sessions by using the login and set session commands; however, you can only have one linked session at a time. While you can login both RPC and linked session from the linked version of topaz, the RPC version of topaz does not allow linked sessions.

topaz> login

gci login: currSession 1 rpc gem processId 95

successful login

topaz 1> set gemstone !@srv2!gs64stone

topaz 1> set username Isaac_Newton

Warning: GemStone is clearing previous GemStone password.

GemStone password? <password typed here but not echoed> 

topaz 1> login

gci login: currSession 2 rpc gem processId 141

successful login

topaz 2> printit

UserGlobals at: #myVar put: 1

%

1

topaz 2> set session 1

topaz 1>

topaz> set gemnetid gemnetobject

topaz> login

GemStone password? <password typed here but not echoed> 

[Info]: libssl-3.3.0-64.so: loaded

[09/10/2015 14:40:49.338 PDT]

  gci login: currSession 1  rpc gem processId 31427 

successful login

topaz 2> set gemnetid ''

topaz 2> login

[Info]: LNK client/gem GCI levels = 33001/33001

--- 09/10/2015 14:37:56.603 PDT Login

[Info]: User ID: DataCurator

[Info]: Repository: gs64stone

[Info]: Session ID: 5

[Info]: GCI Client Host: <Linked>

[Info]: Page server PID: -1

[Info]: Gave this VM preference for OOM killer, Wrote to /proc/4458/oom_adj value 250

[09/10/2015 14:37:56.609 PDT]

  gci login: currSession 1  linked session 

successful login

topaz 1>

topaz 1> printit

System currentSessionNames

%

session number: 2 UserId: GcUser

session number: 3 UserId: GcUser

session number: 4 UserId: SymbolUser

session number: 5 UserId: DataCurator

session number: 6 UserId: Isaac_Newton

session number: 7 UserId: Isaac_Newton

session number: 8 UserId: Gottfried_Leibniz

Transaction state

GemStone is a transactional system. The process of making persistent changes in the GemStone repository require that you begin a transaction, make the changes, then commit the transaction.

To make this easier, GemStone provides automatic transaction mode (autoBegin). In this mode, the session is always in transaction. Each commit or abort automatically starts a new transaction.

When you login through Topaz, your session is in automatic transaction mode. This allows you to make changes and commit them without having to explicitly start a transaction.

However, being in transaction on a system in which other users are also committing changes incurs a risk. GemStone must maintain your transactional view of the repository as long as you are in the transaction and do not commit or abort. These commit records require space in the repository, and in a rapidly changing system, an idle session in transaction can create a “commit record backlog”. Under worst-case conditions, this can cause the repository to fill up with this old data, run out of space, and shut down. If you are logging into a system that is in use, avoid remaining logged in and idle.

If you use topaz to log into a multiple-user system, you may wish to configure your system to default to not being in a transaction; this mode is manual transaction mode (manualBegin). In manual transaction mode, you are out of transaction until you explicitly begin a transaction (either by the begin command, or by executing a Smalltalk expression such as System beginTransaction), and when you commit, your session becomes out of transaction.

You can set topaz to be in manual transaction mode:

topaz> set transactionmode manualBegin

no transaction was in progress, transaction mode changed to manualBegin

Note that if you are logged in, using this command will abort any transaction in progress, so it is better to execute this before login. You may wish to add this to the .topazini initialization file; see details starting here.

See the System Administration Guide for GemStone/S 64 Bit for more information on managing transactions and handling sigAborts.

WARNING
Idle topaz sessions should not be left logged into active multi-user systems. Even if the session is not in transaction and does not cause serious problems, your stale commit record requires extra work for the stone, and session may be terminated.

The Help Command

You can type help at the Topaz prompt for information about any Topaz command. For example:

topaz 1> help time

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.

Topic?

You may enter further help topics at the Topic> prompt.

The enter key brings you back to the topaz command prompt.

For a full list of help topics, use help without specifying an argument.

Interrupting Topaz and GemStone

The Ctrl-C key combination interrupts Topaz and GemStone:

• When Topaz is awaiting input from your terminal, such as when you’re entering a command, you can enter Ctrl-C to terminate entry of the command and prepare Topaz for accepting a new command.
• When GemStone is compiling or executing some GemStone Smalltalk code sent to it by Topaz, such as in a printit command, typing Ctrl-C sends a request to GemStone to interrupt its activities as soon as possible. GemStone stops execution at the conclusion of the current method, and Topaz displays the message: A soft break was received.

Logging Out

To log out from your current GemStone session, just type logout.

topaz 1> logout

topaz>

Logging out implicitly aborts your transaction.

Leaving Topaz

To leave Topaz and return to your host operating system, just type exit:

topaz> exit

If you are still logged in when you type exit, this will implicitly abort all your transactions and log out all active sessions.

You can also use quit, which has the same effect as exit.

Strings vs. Unicode strings

GemStone Smalltalk supports two set of string classes; the traditional Strings, including String, DoubleByteString and QuadByteString; and Unicode strings, including Unicode7, Unicode16, and Unicode32. Traditional Strings are native GemStone, while Unicode strings rely on the ICU libraries to provide sophisticated national language support. This is described in more detail in the Programming Guide for GemStone/S 64 Bit.

When you execute a Smalltalk expression in Topaz that creates a string object, the class of this object depends on the Topaz setting for SourceStringClass. The default is String, in which case a traditional string is created, of the lowest order in which all Characters of the result can be contained. Or it can be set to Unicode16, in which case a Unicode string is created, either a Unicode7, Unicode16, or Unicode32.

topaz 1> set sourcestringclass unicode16

topaz 1> display oops

topaz 1> exec 'hello' %

[4582145 sz:5 cls: 154369 Unicode7] hello

For further details, see sourcestringclass.

Controlling the Display of Results

The result of the Smalltalk expression is returned to Topaz, and this object is displayed on the topaz console. Topaz provides several options to allow you to control the level of detail that is displayed for the object .

topaz 1> printit

DateTime now

%

a DateTime

  year                2015

  dayOfYear           126

  milliseconds        83048864

  timeZone            a TimeZone

topaz 1> doit

DateTime now

%

06/05/2015 15:04:35

topaz 1> level 0

topaz 1> run

DateTime now

%

06/05/2015 15:05:23

topaz 1> level 2

topaz 1> run 

DateTime now

%

a DateTime

  year                2015

  dayOfYear           126

  milliseconds        83121913

  timeZone            a TimeZone

    transitions         an Array

    leapSeconds         nil

    stream              nil

    types               nil

    charcnt             nil

    standardPrintString PST

    dstPrintString      PDT

    dstStartTimeList an IntegerKeyValueDictionary

    dstEndTimeList      an IntegerKeyValueDictionary

topaz 1> limit bytes 4

topaz 1> printit

'this and that'

%

this

...(9 more bytes)

[21336065 sz:3 cls: 110849 Symbol]

topaz 1> display oops

topaz 1> printit

DateTime now

%

[25521409 sz:4 cls: 118785 DateTime] a DateTime

  year 				[16114 sz:0 cls: 74241 SmallInteger] 2014 == 0x7de

  dayOfYear 				[362 sz:0 cls: 74241 SmallInteger] 45 == 0x2d

  milliseconds				[665595786 sz:0 cls: 74241 SmallInteger] 83199473 == 0x4f585f1

  timeZone 				[12049153 sz:9 cls: 14631169 TimeZone] a TimeZone

topaz 1> display bytes

topaz 1> printit

'this and that'

%

1 'this and that' 74 68 69 73 20 61 6e 64 20 74 68 61 74

Committing and Aborting Transactions

To commit a transaction while using Topaz, you can execute the GemStone Smalltalk expression System commitTransaction within a printit command, or you can enter the Topaz commit command:

topaz 1> commitSuccessful commit

Similarly, you abort a transaction by executing the GemStone Smalltalk expression System abortTransaction within a printit command, or by entering abort at the Topaz command prompt. Entering abort does not reset Topaz system definitions, such as your current class and category.

The topaz command begin, or executing System beginTransaction, may also be used to begin a transaction if you are not in automatic transaction mode, or to abort your transaction.

Although you can abbreviate most Topaz commands and parameter names, commit, abort, and begin (as well as some others such as quit and exit) must be typed in full.

Topaz Scripts

The Topaz commands you have entered interactively to login and execute code can alternatively be stored in an external text file. This allows you to execute a sequence of commands as often as needed and whenever needed without having to type it in each time.

You have already seen the .topazini initialization file, which is a specialized use of scripting capability. Topaz provides the ability to run any of its commands, invoke other topaz scripts or operating system functions, and perform error checking and logging. It is not itself a complete scripting environment and does not provide flow-of-control operators; topaz invocations can be embedded in shell script as needed.

If you have complicated queries, sequences of repository updates, reports, or administrative tasks that you repeat on a regular basis, this is an easy way to do it. You can type the Topaz commands into a file, and test and edit them until they run correctly. If your procedures change, you can easily edit the script.

topaz 1> input $HOME/animal.gs

set user DataCurator password swordfish gemstone gs64stone

login

! run garbage collection mark/sweep 

exec SystemRepository markForCollection %

exit

topaz 1> input runmfc.topaz

#! /bin/sh

#set -x

$GEMSTONE/bin/topaz -il <<EOF >>MFC.out

set user DataCurator password swordfish gemstone gs64stone

login

! run garbage collection mark/sweep 

exec SystemRepository markForCollection %

exit

EOF

topaz> fileformat UTF8

Capturing Your Topaz Session In a File

It’s often useful to keep a record of your interactions with GemStone during testing and debugging, and when executing scripts to simplifying finding errors.

You can do this with the Topaz command output. This command causes Topaz to write all input and output to a named file as well as to standard input and standard output (your terminal).

For example, either of these lines cause all subsequent interactions to be captured in a file called animaltest.log:

topaz 1> output animaltest.log

topaz 1> output push animaltest.log

Using output alone or output push, if the file you name doesn’t exist, Topaz creates it. Under UNIX, if you name an existing file, Topaz will overwrite the previous file.

To add output to an existing file without losing its current contents, use output append, or precede the file name with an ampersand (&). For example:

topaz 1> output push &animaltest.log

To have topaz create a new file if a file with the given name already exists, use pushnew:

topaz 1> output pushnew animaltest.log

If animaltest.log already exists, the file animaltest_1.log is created.

To stop writing to the current log, use output pop.

topaz 1> output pop

topaz 1> output push animaltest.log only

topaz 1> ! Capture the next command and result in mathtest.log

topaz 1> output push mathtest.log

topaz 1> time

05/07/2015 14:49:47.558 PDT

CPU time:   0.013 seconds

topaz 1> exec 5 * 8 %

40

topaz 1> ! Capture the next command and result in mathtest2.log

topaz 1> output push mathtest2.log only

topaz 1> time

topaz 1> exec 5 * 9 %

topaz 1> ! Close mathtest2.log and resume using mathtest.log

topaz 1> output pop

Creating Methods

Creating a class is done using GemStone Smalltalk class creation protocol. For more on class creation, refer to the GemStone Programming Guide.

For example,

topaz 1> printit

Object subclass: 'Animal'

  instVarNames: #('name' 'favoriteFood' 'habitat') 

  classVars: #() 

  classInstVars: #() 

  poolDictionaries: #() 

  inDictionary: UserGlobals

%

a metaAnimal

  superClass          a metaObject

  format              0

  instVarsInfo        1125899906846723

  instVarNames        an Array

  constraints         an Array

  classVars           nil

  methDicts           a GsMethodDictionary

  poolDictionaries nil

  categorys           a GsMethodDictionary

  primaryCopy         nil

  name                Animal

  classHistory        a ClassHistory

  transientMethDicts an Array

  destClass           nil

  timeStamp           a DateTime

  userId              DataCurator

  extraDict           a SymbolDictionary

  classCategory       nil

  subclasses          nil

Once you have a class, you can create methods for it in topaz.

You can begin the definition of an instance method by issuing the method: command at the Topaz prompt. This command takes a single argument: the name of the class for which the method will be compiled.

topaz 1> set category 'Accessing'

topaz 1> method: Animal

habitat

	"Return the value of the instance variable 'habitat'."

	^habitat

%

A class method definition is similarly initiated by the Topaz command classmethod:. For example:

topaz 1> set category 'Instance creation'

topaz 1> classmethod: Animal

returnAString

	"Returns an empty String"

	^String new

%

Topaz maintains state for the Class and method category, so if you have multiple methods, you do not need to specify these values for each method definition. Expressions such as the above will set the Class and the category, and this will be used for subsequent methods until changed.

To set the current class, use the set class command:

topaz 1> set class Animal

To set the current category, use the set category command:

topaz 1> set category Updating

If the category you name doesn’t exist, Topaz creates it when you compile the method.

You can examine your current class and category settings by typing status.

topaz 1> status

Current settings are:

(display of current settings and connection information appears here)

browsing information:

Class_____________ Animal

Category__________ Updating

Once you’ve established a class and a category, you can define a method simply:

topaz 1> method:

habitat: newValue

	"Modify the value of the instance variable 'habitat'."

	habitat := newValue

%

Like the text of a printit command, the text of a method definition is terminated by the first line that starts with the % character. As soon as you enter the %, Topaz sends the method’s text to GemStone for compilation and inclusion in the selected class and category.

Using a Text Editor to Edit Methods

The edit command allows you to use a host text editor to edit GemStone Smalltalk expressions, including method text.

To use the edit function, you must first have established the name of the host editor you wish to use. Topaz can read the UNIX environment variable EDITOR, if you have it set. Otherwise, use the Topaz set editorname command, interactively or in your Topaz initialization file.

topaz 1> set editorname vi

Then, to edit the text of the last printit command, you need only do this:

topaz 1> edit last

Topaz opens your editor, as a subprocess, on the text of the last command that defined Smalltalk expressions: including printit, exec, run, doit, method, and classmethod. When you exit the editor, Topaz saves the edited text in a temporary file and asks you whether you’d like to compile the altered code. If you type y or yes, Topaz effectively reissues your command with the new text.

For example, to edit the existing instance method habitat: in the current class, you would enter edit as shown below:

topaz 1> edit method habitat:

To edit an existing class method, use an expression of the form:

topaz 1> edit classmethod returnAString

To create an entirely new method with the editor, you can enter edit new method or edit new classmethod.

Listing Methods, Categories, and other information

The topaz list command provides a way to find out information about classes and methods, as well as other information about your system.

To list the instances method selectors for a class, use list selectors:

topaz 1> list selectors

  habitat

  habitat:

To see the categories and methods that are in the current class, use list categoriesin. Topaz lists all of the class and instance method selectors in the selected class by category.

topaz 1> list categoriesin

----------------- Instance Methods:

category (as yet unclassified)

  habitat

category Updating

  habitat:

----------------- Class Methods:

category (as yet unclassified)

  returnAString

To list the source code of an instance method, use list method:

topaz 1> list method: habitat:

habitat: newValue

"Modify the value of the instance variable 'habitat'."

habitat := newValue

A parallel command, list classmethod:, lists the source of the given class method.

Other list options allow you to examine the classes in one or all of your symbol list dictionaries or to examine the methods in some class other than the current class. The list command by itself is used in debugging, to display source for a method on the current execution stack. For more information, see the options described under LIST.

Filing Out Classes and Methods

You will commonly want to file out GemStone Smalltalk code at some level of granularity, by Method, Method Category, Class, or SymbolDictionary. Some reasons to do this are:

• transport your code to other GemStone systems,
• perform global edits and recompilations,
• produce paper copies of your work, and
• recover code that would otherwise be lost when you are unable to commit.

GemStone fileouts are in topaz executable form. You can process this text using editors or other operating system utilities and then execute it with the Topaz input command.

Fileouts are commonly done using GemStone Smalltalk methods, including Class fileOutMethod:on:, Class fileOutCategory:on:, Class fileOutClassOn:, and similar methods; and ClassOrganizer fileOutClassesAndMethodsInDictionary:on:. For more information on these methods, see the methods in the image.

Fileout can also be performed using the Topaz fileout command. For example, the following command:

topaz 1> fileout class: Animal toFile: animal.gs

would create in the file animal.gs, a Topaz script containing a definition of class Animal and all of its categories and methods. Here is how animal.gs would look:

fileformat 8Bit

set sourcestringclass String

run

Object subclass: 'Animal'

	instVarNames: #( 'name' 'favoriteFood' 'habitat')

	classVars: #()

	classInstVars: #() 

	poolDictionaries: {} 

	inDictionary: UserGlobals 

%

category: 'Updating' 

method: Animal

habitat: newValue

	"Modify the value of the instance variable 'habitat'."

	habitat := newValue

%

...

“Filing in” this script with the input command would create a new class Animal exactly like the original.

In addition to class:, the fileout command has other subcommands, to allow you to fileout a method or other granularity of code. For more details, see the options under FILEOUT.

topaz 1> fileformat UTF8

Structural Access To Objects

In your GemStone Smalltalk programs, you should generally access the values stored in objects only by sending messages. During debugging, however, it’s sometimes useful to be able to read an instance variable or store a value in it without sending a message. For example, if an instance variable is normally read only by a message with side effects, it won’t do to examine its value during debugging by sending that message.

To allow you to “peek” and “poke” at objects without passing messages, Topaz provides the commands object at: and object at:put:.

topaz 1> printit

UserGlobals at: #MyAnimal put: Animal new.

%

an Animal

	name               nil

	favoriteFood       nil

	habitat            nil

topaz 1> printit

MyAnimal habitat: 'water'

%

an Animal

	name               nil

	favoriteFood       nil

	habitat            water

topaz 1> object MyAnimal at: 3 

water

topaz 1> object MyAnimal at: 3 at: 1 

$w

Specifying Objects

As you have seen, objects can be identified within an object command by global GemStone Smalltalk variable names. This is only one of several kinds of object specification acceptable in such Topaz commands as object at:. The others include object identity specification formats and literal object specification formats.

[sign]digits[.[digits][E[sign]digits]]

topaz 1> display oops

topaz 1> object Animal

[1337089 sz:19 cls: 150617 Animal class] Animal class

  superClass      [72193 sz:19 cls: 206081 Object class] Object class

  format          [2 sz:0 cls: 74241 SmallInteger] 0

  instVars        [26 sz:0 cls: 74241 SmallInteger] 3

  instVarNames    [1335297 sz:3 cls: 66817 Array] an Array

...

topaz 1> ! Look at first element of instVarNames array 

topaz 1> object @1335297 at: 1

[1248257 sz:4 cls: 110849 Symbol] name

topaz 1> ! Look at first character of first instvarname

topaz 1> omit oops

topaz 1> object ** at: 1

$n

Topaz Variables

As you saw in the last section, Topaz lets you refer to objects via their OOPs. Because long numerical OOPs are hard to remember, Topaz also provides a facility for defining local Topaz variables so that you can name those OOPs.

topaz 1> display oops

topaz 1> object Animal

[1337089 sz:19 cls: 1337601 Animal class] Animal class

	superClass  [72193 sz:19 cls: 206081 Object class] Object class

	format      [2 sz:0 cls: 74241 SmallInteger] 0

	instVars    [26 sz:0 cls: 74241 SmallInteger] 3

	instVarNames[1335297 sz:3 cls: 66817 Array] an Array

...topaz 1> define animalVars @1335297

topaz 1> omit oops

topaz 1> object animalVars at: 1

name

topaz 1> define thirdvar animalVars at: 3

topaz 1> object thirdvar

habitat

topaz 1> define sum 1.0e1 + 500

topaz 1> define mystring 'this and that'

topaz 1> define mycharacter $z

topaz 1> define

Current definitions are:

	mycharacter        = 142538

	mystring           = 150133

	sum                = 147709

	thirdvar           = 114793

	animalVars         = 147682

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

	CurrentMethod       = nil

	ErrorCount          = 2

	SourceStringClass   = 74753

	CurrentCategory     = nil

	CurrentClass        = nil

	LastResult          = nil

	LastText            = nil

	myUserProfile       = nil

topaz 1> define abc 'this string'

topaz 1> object abc

this string

topaz 1> define abc

topaz 1> object abc

GemStone could not find an object named abc.

Sending Messages

Usually you’ll send messages only inside methods or within printit commands. If you can point to an object only via a local Topaz variable or via an OOP, however, this won’t work.

Therefore, Topaz provides the send command, which lets you send a message to an object identified by any of the means described in Specifying Objects. For example:

topaz 1> send @71425 class

a Metaclass

	superClass     a Metaclass

	format 1040

	...

	categories     a GsMethodDictionary

	secondarySuperclasses nil

	thisClass       UndefinedObject class

The send command’s first argument is an object specification identifying a receiver. That argument is followed by a message expression built almost as it would be in GemStone Smalltalk. Here’s another example:

topaz 1> send 2 - 1

1

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