11. The GemStone Tools: an Overview
This part of the manual introduces you to the GemBuilder visual programming environment. This and the following chapters describe the tools for managing logins to the GemStone server, programming in GemStone Smalltalk, and the GemBuilder tools for performing some GemStone Administrative tasks.
11.1 GemStone Launcher
The GemStone Launcher provides the starting place for your interactions with GemBuilder and the GemStone server. It streamlines logging in and logging out of GemStone and managing sessions and transactions, as well as providing menus and toolbar shortcuts that allow you to access all the GemBuilder programming and administrative functions.
This section describes the tools for managing Session Parameters and Sessions and handling logins. For a more detailed discussion, and the underlying programmatic login process, see the discussion under Session Parameters.
To access the GemStone Launcher, use the VisualWorks Launcher menu item GemStone > GemStone Launcher, or use the equivalent Toolbar icon.
Figure 11.1 GemStone Launcher
Session Parameters
To log in to a GemStone repository using the GemStone Launcher, you need to have a Session Parameters. The GemStone Launcher allows you to create new Session Parameters.
The Add... button allows you to create a regular Session Parameters; using the Menu item Parameters, you may also create X509 Session Parameters, which allow to specify certificates needed to login to X509-secured GemStone.
The list of previously registered session parameters is displayed in the Session Parameters Pane, the upper left part of the window. The buttons in this pane perform operations on Session Parameters. These operations are also found in the Parameters menu and the Session Parameters Pane popup menu.
You may drag and drop Session Parameters with the list, to reorder them for convenience. The order is not relevant.
Sessions
Once you select a session parameters and log in successfully, your session, along with any other logged in sessions, is displayed in the Sessions Pane, the lower left part of the window. The Sessions Buttons operate on the selected session in the Sessions Pane. You may login multiple sessions from a single session parameters, or multiple sessions based on different parameters.
The operations provided by the Sessions Buttons, as well as additional operations, are available on the Session menu and the Sessions Pane popup menu.
Current Session vs. Selected Session
Selecting a session in the Sessions Pane highlights the session by coloring the background of the text. The Sessions Buttons and Session menu items, and other GemStone Launcher menu items such as those on the Browse menu, operate on the selected session or are associated with the selected session, and are disabled if no session is selected.
The current session is in bold text. This is the session used when executing code using system-wide GemStone code execution such as the Workspace or client Smalltalk browser menu items “GS-Do it”, etc., or in the debugger. If any sessions are logged in, one of these is always the current session; it may or may not be the selected session.
To make a session the current session, select that session and use the Current button, or the menu item Session > Be Current Session.
Session Parameters Editor
The Session Parameters Editor is used to create a new session parameters, or to edit an existing one. You must define a Session Parameters before you can login.
Creating a new Session Parameters
To create a new (regular) Session Parameters, select the menu item Parameters > Add..., or the Add.. button, to open a dialog allowing you to define a set of session parameters.
The first time this is done after starting the client Smalltalk image, the server-specific client libraries are loaded. Any problems in the client library configuration will show up now. For more information on these libraries, see Client Libraries, and the Installation Guide.
In the Session Parameters Editor, specify the following session parameters:
-
GemStone repository
For a Stone running on a host other than the Gem host (described under Gem service below), you must include the server’s hostname in Network Resource String (NRS) format. (NRS format is described in an appendix to the System Administration Guide) -
GemStone user name and GemStone password
This user name and password combination must already have been defined in GemStone by your GemStone data curator or system administrator. Because GemStone comes equipped with a data curator account, we show the DataCurator user name in many of our examples. -
Host username and Host password (not required for a linked session, or if netldi is running in guest mode)
This user name and password combination specifies a valid login on the Gem’s host machine (the network node specified in the Gem service name, described below). Do not confuse these values with your GemStone username and password. You do not need to supply a host user name and host password if you are starting a linked Gem process. However, an application that must control more than one GemStone session can use a linked interface for only one session. Other sessions must use the RPC interface.
CAUTION
To avoid inadvertently removing or modifying a GemStone kernel class, use the DataCurator account for all system administration functions except those that require SystemUser privileges, such as upgrading or restoring the GemStone repository.
-
Gem service (not required for a linked session)
The name of the Gem service on the host computer (that is, the Gem process to which your GemBuilder session will be connected). For most installations, the Gem service name is gemnetobject.
You can specify that the gem is to run on a remote host by using an NRS for the Gem service name. For example:
!@pelican!gemnetobject
You do not need to supply a Gem Service name if you are starting a linked Gem process.
For maximum password security, leave the Password and Host Password fields empty, and the Remember boxes unselected.
When you click on OK, GemBuilder creates an instance of GbsSessionParameters and registers it with GBSM. The new session description is added to the GemStone Launcher.
Editing Existing Session Parameters
To change a session parameters object, select the session parameters in the GemStone Launcher, and select the menu item Parameters > Edit, or the Edit.. button. This opens a Session Parameters Editor displaying the parameters. Clicking on OK causes your changes to take effect.
For more details on the available operations for a session parameters, see Session Parameters Buttons and Parameters Menu.
X509 Session Parameters Editor
In addition to regular sessions that are logged in using Session Parameters, GemBuilder supports X509 logins, which require a different set of Session Parameters.
To edit X509 Session Parameters, you can use the X509 Session Parameters Editor. This dialog is accessed by the menu item Parameters > Add X509....
Login using X509 Session Parameters is limited to GemStone/S 64 Bit v3.5 that has apprproate licence, and with the X509-secured GemStone environment configured and started up. See the GemStone/S 64 Bit X509-Secured GemStone System Administration Guide for more on X509 logins from GemBuilder.
Logging into and logging out of GemStone
The session parameters specify a Stone by name, on a the same or a different node, and for an RPC session, includes the name or port of the NetLDI (network long distance information). Before you can login, the specified Stone must be running on that node, and if needed, the specified NetLDI must be running. The versions of the stone and NetLDI must also match the client shared library that is (or will be) loaded into GBS.
Depending on the terms of your GemStone license, you can have many sessions logged in at once from the same GemBuilder client. These sessions can all be attached to the same GemStone repository, or they can be attached to different repositories, provided they are running the same version of the GemStone server.
Logging in to GemStone
To log into the GemStone server with the GemStone Launcher, select the session parameters object in the Session Parameters pane, and click on either Login Link or Login RPC. You may also use the equivalent menu items on the Parameters menu.
Note that linked logins are not always available. In order to login linked, you must use the ”lnk” version of the shared libraries, be running the appropriate bit size (32-bit or 64-bit) version of the client VisualWorks executables, and have the appropriate GemStone server components available on the client.
When you are logged in, the GemStone Launcher displays the session description in the Sessions Pane.
On login, sessions are in automatic transaction mode. If you want to be in manual begin transaction mode, for example if you are only viewing code and do not want to consume resources on the GemStone server, select the radio button or use the Session > Automatic Begin Mode menu item.
Figure 11.3 GemStone Launcher with session logged in
Logging Out of GemStone
To log out of GemStone from the GemStone Launcher, select the session in the lower pane and click the Logout button.
Before logging out, GemBuilder prompts you to commit your changes, if the GbsConfiguration setting confirm is true (it is true by default). If you log out after performing work and do not commit it to the permanent repository, the uncommitted work you have done will be lost.
If you have been working in several sessions, be sure to commit only those sessions whose changes you wish to save.
For more details on the operations on each session, see Sessions Buttons and Sessions Menu.
11.2 GemStone Launcher Menus and Toolbar shortcuts
The GemStone launcher provides direct access to most commonly used GemBuilder functions. The Toolbar provides access to a subset of the operations that are available in the menu bar menus and popup-menus
Browse Menu
The Browse menu provides access to the programming tools, such as the System Browser, and the administrative tools. The most commonly accessed of these tools also have icons on the ToolBar.
The following items are under the menu bar Browse menu.
System Opens a System Browser, comparable to the client Smalltalk System Browser. The System Browser is described starting here.
Available as a ToolBar shortcut.
Class... Prompts for the name of a class and opens a System Browser focused on that class.
Available as a ToolBar shortcut.
Symbol Dictionary... Prompts for the name of a symbol dictionary, then opens a System Browser focused on that dictionary.
References to...
Prompts for the name of class or class variable name, then opens a References Method List Browser listing all methods that refer to that variable. Search accepts wildcard characters * and ?, and is case-insensitive unless any uppercase characters are used.
Available as a ToolBar shortcut.
Implementors of Selector...
Prompts for the name of a message selector, then opens an Implementors Method List Browser showing all methods that implement that selector. Search accepts wildcard characters * and ?, and is case-insensitive unless any uppercase characters are used.
Available as a ToolBar shortcut.
Senders of Selector... Prompts for the name of a message selector, then opens a Senders Method List Browser showing all methods that send that selector. Search accepts wildcard characters * and ?, and is case-insensitive unless any uppercase characters are used.
Available as a ToolBar shortcut.
Methods with String Matching...
Prompts for a string, then opens a browser listing all methods whose source code contains the specified string.
Breakpoints Opens a Breakpoint Browser, allowing you to view and manipulate breakpoints in GemStone Smalltalk code. The Breakpoint Browser is described here.
Available as a ToolBar shortcut.
Connectors Opens a Connector Browser, allowing you to view and manipulate connectors between Client and GemStone server objects. The Connector Browser is described here.
Available as a ToolBar shortcut.
Users Opens the User Account Management Tools, allowing you to create new users, assign attributes to them, and manage user accounts, provided you have the privileges to do so. The User Account Management Tools are described here.
Symbol Lists Opens a Symbol List Browser, allowing you to examine and modify symbol dictionaries and their entries. The Symbol List Browser is described here.
Security Policies Opens a Security Policy Tool, allowing you to control authorization at the object level by assigning objects to security policies. The Security Policy Tool is described here.
Session Parameters Buttons and Parameters Menu
The Parameters menu, and the popup menu in the Session Parameters Pane, include operations that are performed on the Session Parameters. Many of these functions are also provided as Session Parameters Buttons.
The following items are on the parameters menu: 
Add... Open an empty Session Parameters Editor. Available as a Session Parameters Button.
Add X509... Open an empty X509 Session Parameters Editor. This creates Parameters that can only be used to login to X509-Secured GemStone, a server feature in GemStone/S 64 Bit v3.5 and later.
Copy Make a copy of the selected session parameters, and add it to the list.
Available as a Session Parameters Button.
Edit Open a Session Parameters Editor on the selected session parameters.
Available as a Session Parameters Button.
Login Link Log in linked, using the selected session parameters.
Available as a Session Parameters Button.
Login RPC Log in RPC, using the selected session parameters.
Available as a Session Parameters Button.
Remove... Remove the selected session parameters.
Available as a Session Parameters Button.
Import... Prompt for a filename, and read a previously exported list of Session Parameters from a text file.
Export... Prompt for a filename, and write out the selected Session Parameters to a text file. The exported information is in plain text. If you have included passwords in your session parameters, these will be visible.
Export All... Prompt for a filename, and write out the complete list of Session Parameters to a text file. The exported information is in plain text. If you have included passwords in your session parameters, these will be visible.
Sessions Buttons and Sessions Menu
The Sessions menu, and the popup menu in the Sessions Pane, include operations that are performed on the selected Session. Many of these functions are also provided by the lower right set of buttons.
The following items are on the Sessions menu:
Auto-Commit in Browsers
Turns on auto-commit, so saved changes in the code browsers are automatically committed. Only code changes in code browsers are committed via auto-commit, although auto-commit does commit all changes in your transaction.
Commit Transaction Commit all changes in the selected session.
Available as a Session Button.
Abort Transaction Abort in the selected session. Available as a Session Button.
Begin Transaction Abort in the selected session and start a new transaction.
Available as a Session Button.
Automatic Begin Mode
Toggles the transaction mode between Automatic begin and Manual begin. When this is checked, the session is in automatic transaction mode, when unchecked, in manual transaction mode. For more information on transaction modes, see the details starting here.
Available as radio button options with the Session Buttons.
Be Current Session Makes the selected session into the current session. This is described in more detail here.
Available as a Session Button.
Break Execution Sends a soft break to the selected session, interrupting any currently executing server Smalltalk code, and open a debugger. Available as a Session Button.
Logout Logs out the selected session. Available as a Session Button.
Tools Menu
The Tools menu provide access to operations whose functionality is primarily provided by the client Smalltalk environment.
The following items are on the Tools menu: 
Settings Opens a Settings Browser in which you can examine, change, and store parameters for configuring GemBuilder. The Settings Browser is described here.
Available as a ToolBar shortcut.
File Browser Opens a client Smalltalk File Browser.
Available as a ToolBar shortcut.
Workspace Opens a client Smalltalk Workspace.
Available as a ToolBar shortcut.
System Workspace Opens the GemStone System Workspace, a workspace containing a variety of useful GemStone Smalltalk and client Smalltalk expressions. The System Workspace is described here.
Window Menu
The window menu allows you to collapse and re-expand most GemStone Windows, other than the GemStone Launcher itself.
Raise GemStone Windows
Expands all minimized GemBuilder for Smalltalk windows.
Collapse GemStone Windows
Minimizes all GemBuilder for Smalltalk windows, except the GemStone Launcher.
11.3 Settings Browser
The Settings Browser allows you to examine and set the configuration parameters for GemBuilder. The Settings Browser is integrated with the client Smalltalk settings.
Opening the Settings Browser
To open the Settings Browser, select Tools > Settings from the GemStone Launcher; or select System > Settings from the VisualWorks Launcher and scroll down to see the GemStone configuration settings categories.
Buttons on the Settings Browser
Apply Default Settings (At the highest level only)
Reset all GemStone settings to their default value.
OK Close the Settings Browser, applying all changes to the current configuration.
Cancel Close the Settings Browser, cancelling all unapplied changes.
Apply Apply all unapplied changes to the current configuration.
Help Open a dialog with help for the configurations in the categories that you are currently viewing.
11.4 System Workspace
The GemStone System Workspace is a workspace containing templates for many useful GemStone Smalltalk and client Smalltalk expressions. Browse it to familiarize yourself with its contents.
To open a GemStone System Workspace (Figure 11.5),From the GemStone Launcher choose Tools > System Workspace.
