2. Upgrading from GemStone/S 64 Bit 3.x versions

Previous chapter

Next chapter

This chapter describes how to upgrade an existing GemStone/S 64 Bit 3.x installation to GemStone/S 64 Bit version 3.2.6. GemStone/S 64 Bit version 3.2.6 supports upgrade from GemStone/S 64 Bit versions 3.0.x, 3.1.x, and 3.2.x. For upgrading from GemStone/S 64 Bit 2.x versions, which require conversion, see Converting from GemStone/S 64 Bit 2.4.x versions.

If you are using GemBuilder for Smalltalk (GBS), you also need to upgrade the client libraries that are used by GBS. You may also need to upgrade your version of GBS; versions of GBS earlier than 7.6.1 are not compatible with v3.2.6. See Chapter 4 for supported versions of GBS for use with GemStone/S 64 Bit 3.2.6, and instructions on installing updated client libraries.


New keyfiles are required with GemStone/S 64 Bit version 3.2 and later. Keyfiles for GemStone/S 64 Bit 3.0.x or 3.1.x will not work with v3.2.6. To acquire an updated keyfile for version 3.2.6, email keyfiles@gemtalksystems.com, or contact GemStone Technical Support, preferably providing your existing keyfile.

The keyfiles for v3.2 and later also manage access to GemConnect and GemBuilder for Java. If you are using these add-on products, you must use a keyfile with the appropriate permissions. Applications using GemConnect or GemBuilder for Java also require updated versions of these products for compatibility with version 3.2 and later. These products need to be reinstalled following the upgrade process.

Upgrade Strategy

We recommend that you perform the upgrade twice: first a pilot upgrade and then the production upgrade. With this strategy, you can keep your production system running while you familiarize yourself with the upgrade process.

Upgrade Procedure

The following list summarizes the steps necessary to perform the upgrade to GemStone/S 64 Bit version 3.2.6.

The following instructions use the version number 3.2.4 to refer to the version you are upgrading from, and version number 3.2.6 indicate the target version you are upgrading to. The process is the same when upgrading from any 3.x repository, and upgrading to any 3.2.x versions for which this Installation Guide applies.

Prior to Upgrade in existing application

1. Check for use of deprecated methods

Verify that your application does not invoke any methods that were deprecated in previous releases, by enabling error or logging on deprecation in your existing repository. Deprecated methods are subject to removal in major releases; finding them before upgrading allows the deprecation messages to provide replacement instructions.

For details on finding deprecated methods, refer to the Programming Guide for GemStone/S 64 Bit v3.2.

2. File out modifications to GemStone classes

File out any modifications or additions you made to GemStone/S 64 Bit kernel class methods. For more information about fileout, see the GemStone/S 64 Bit Topaz Programming Environment.

You will need to carefully compare these changes with GemStone/S 64 Bit 3.2.6 kernel methods, and refer to the Release Notes, to determine whether your changes are still necessary or appropriate.

You MUST file out any changes that you have made to the GemStone/S 64 Bit kernel classes in order to preserve these changes in version 3.2.6.

Prepare for Upgrade

1. Install and configure GemStone/S 64 Bit 3.2.6

Install GemStone/S 64 Bit 3.2.6 to a new installation directory, separate from the installation directory for version 3.2.4, as described in Installing GemStone/S 64 Bit Version 3.2.6.

Configure GemStone/S 64 Bit 3.2.6 the way you expect to use it — that is, with the appropriate extent locations and sizes.

You should ensure that adequate space is available for extents, transaction logs, and a backup during the upgrade. You must provide space for the extents and transaction logs for both repositories, the old and the new.

2. Reset SystemUser password

Log in to the version 3.2.4 system as a user with OtherPassword privilege, such as DataCurator, and reset the SystemUser password to ‘swordfish’:

topaz 1> printit
(AllUsers userWithId: #SystemUser) password: 'swordfish' .
System commitTransaction.

The upgrade script logs in with the SystemUser account and the default password, and resets the password for DataCurator and GcUser.

3. Stop user activity

Log in to the version 3.2.4 system as a user with SessionAccess and SystemControl privileges, such as DataCurator, and halt all user activity on the repository.

topaz 1> printit
System stopUserSessions.
4. Shut down the repository

You may now shut down the Stone. At the UNIX command line:

% stopstone stone324

where stone324 is the name of the version 3.2.4 stone on this machine. The repository must be cleanly shut down to avoid needing recovery when it is restarted with the new version’s executables.

5. Set up the version 3.2.6 environment.

Set the environment variables required for the upgrade.

C shell:
% setenv GEMSTONE InstallDir326
% set path = ($GEMSTONE/bin $path)
% setenv upgradeLogDir tempDir 
Bourne or Korn shell:
$ GEMSTONE=InstallDir326
$ export GEMSTONE
$ export PATH=$GEMSTONE/bin:$PATH
$ upgradeLogDir=tempDir
$ export upgradeLogDir

where InstallDir326 is the GemStone/S 64 Bit version 3.2.6 installation and tempDir is a temporary directory for which you have write permission.

Use a separate log directory for each repository you convert.

6. Copy extent files

Copy your version 3.2.4 extent files into the location specified by the configuration file option DBF_EXTENT_NAMES:

a. Using a text editor, open the configuration file that the version 3.2.4 repository uses.

b. Locate the last occurrence of the option DBF_EXTENT_NAMES, and note its value, a list of .dbf files.

c. Copy each .dbf file to the noted location in the version 3.2.6 installation. For example:

% cp InstallDir324/data/extent0.dbf 326location
% cp InstallDir324/data/extent1.dbf 326location
% cp InstallDir324/data/extent2.dbf 326location

where 326location is the location specified by DBF_EXTENT_NAMES in the configuration file that will be used in version 3.2.6.

Before upgrading, ensure that there are no transaction logs from a previous version of GemStone/S 64 Bit in any of the transaction log locations specified in the configuration file that will be used by version 3.2.6. Transaction logs from earlier versions are not compatible with version 3.2.6. If the transaction log directories will be reused for version 3.2.6, any transaction logs should be deleted or copied elsewhere.

Perform the Upgrade

1. Start the Stone

Start the 3.2.6 Stone on the 3.2.4 extents you just copied:

% startstone stoneName326
2. Upgrade image

Ensure you are in a directory to which you have write permission, and run the upgrade script.

The upgrade is performed by the script upgradeImage. This script has optional switches to specify the stone name and to set to size of the GEM_TEMPOBJ_CACHE_SIZE used for the upgrade process.

upgradeImage [-h] [-c <cacheSize>] [-s <stoneName>]
-h prints this usage information.
-c <cacheSize> sets the size of the GEM_TEMPOBJ_CACHE_SIZE; if this is not
used, the script will default to use a value of 100000. 
-s <stoneName> sets the name of the running stone to upgrade; if this option is
not used, the script will default to gs64stone.

For example,

% upgradeImage -s stoneName326

The script will prompt you to press the return key to begin.

The script invokes subordinate scripts to complete the upgrade. The upgrade process will take some time. You can examine the progress, if desired, by examining the file $GEMSTONE/upgradeImage.out.

The script should complete with the message:

Upgrade completed. No errors detected.

If not, please preserve the Stone log file and the contents of $upgradeLogDir. Contact your internal GemStone support person or GemStone Technical Support.

3. Upgrade comments, if necessary

If you are upgrading from v3.0.x, you must upgrade comments on your application classes. This step is not required if you are upgrading from v3.1 or later.

The format for class comments changed between versions 3.0.x and v3.1. Now, comments are stored as Strings in a new field in the class, rather than as class methods or as instances of GsClassDocumentation in the description field.

Kernel class comments are upgraded automatically. To upgrade application class comments, use the script upgradeComments.

In particular, you should not have class methods named #comment on any of your classes. The upgradeComments script both sets the comment and deletes the class method #comment.

upgradeComments [-c <tempObjCacheSize][-s <stoneName>]
-c <tempObjCacheSize> sets the size of temp obj cache in KB.
-s <stoneName> sets the name of the running stone to upgrade comments; if this
option is not used, the script will default to gs64stone.

For example,

% upgradeComments -s stoneName326

The script should complete with the message:

Upgrade completed. No errors detected.

If you have a very large number of class comments, it is possible to run out of temporary object memory while upgrading comments. If so, use the -c argument to specify a larger temporary memory space.

4. Restore System Account passwords

Log in to GemStone/S 64 Bit version 3.2.6 as DataCurator or SystemUser, and change the password for SystemUser, DataCurator, and GcUser to a secure password, such as the passwords used for these accounts in v3.2.4. For example:

topaz 1> printit
(AllUsers userWithId: 'SystemUser') password: '324Password'.
(AllUsers userWithId: 'GcUser') password: '324Password'.
(AllUsers userWithId: 'DataCurator') password: '324Password'.
System commitTransaction

where 324Password is the account password used in version 3.2.4.

Post-upgrade Application Code Modifications

1. Reinstall any other GemStone products that modify kernel classes.

If you use GemConnect or GemBuilder for Java, you must reinstall the appropriate version of these products into your repository at this time.

To install, use the procedure in the Installation Guide for that product.

2. File in Kernel class changes

Any kernel class modifications that you had filed out prior to starting upgrade may now be filed into your v3.2.6 repository. carefully compare your changes with version 3.2.6 kernel methods to see whether these changes are still necessary or appropriate. If so, file in the changes, and commit.

3. Upgrade user account passwords, if necessary

Internal password formats changed in version 3.1. The new format uses updated, more secure encryption. As each user logs in after upgrade (to 3.1 or later), their password will be transparently upgraded to the new format, with no extra upgrade actions required. However, accounts that do not log in will continue to have the same passwords, which are stored in the older, less secure encryption.

If you are upgrading from 3.0.x, or if have not previously upgraded user passwords since upgrading to 3.1.x, you should ensure that all user accounts have logged in, or had their passwords explicitly updated by an administrator. To make these tasks easier, the following methods can be used:

UserProfileSet >> usersWithOldPasswordEncryption
UserProfileSet >> disableUsersWithOldPasswordEncryption

See image comments for more details.

Backup repository and configure GBS

1. Make backup

At this point, you should create a full backup of the upgraded repository.

2. Configure GBS

If you are using GBS clients, ensure you are running a supported version of GBS and client Smalltalk. You must use GBS version 7.6.1 or later for VW, or GBS 5.4.2 or later for VA, to connect to a GemStone/S 64 Bit v3.2 or later repository.

Configure GBS to use the version 3.2.6 client libraries. Depending on the GBS version you are upgrading from, the required libraries, library naming conventions, and the process GBS uses to identify the correct library to load may have changed.

See Configuring GBS for GemStone/S 64 Bit for details.

Previous chapter

Next chapter