3. Upgrading from 3.2x, 3.1.x, or 3.0.x

Previous chapter

Next chapter

This chapter describes how to upgrade an existing GemStone/S 64 Bit 3.2.x, 3.1.x, or 3.0.x installation to GemStone/S 64 Bit version 3.3.5. If you are upgrading from version 3.3, which does not require recompile, see Upgrading from GemStone/S 64 Bit 3.3.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 8.1 or 5.4.3 are not compatible with v3.3.5. See Chapter 5 for supported versions of GBS for use with GemStone/S 64 Bit 3.3.5, and instructions on installing updated client libraries.

ICU library version

ICU libraries support unicode comparisons in v3.1 and later. These are versioned corresponding to changes in the Unicode standard. Major releases of GemStone/S 64 Bit default to the latest ICU library version:

3.3: ICU library version 54.1
3.2: ICU library version 51.2
3.1: ICU library version 48.1

There is some risk for repositories with data structures that depend on ICU collation and encoding—specifically SortedCollections and indexes, but other structures may be affected—if they do not use the same ICU library version as was in use when the data structure was built; see the bugnote for bug 46056.

After upgrade to 3.3.5, your repository will use either v54.1 or 52.1, depending on the particular sequence of upgrades.

If the repository you are upgrading from has ever been upgraded to any 3.1.x version, and (starting in or before that version) contains persistent SortedCollections or Indexes that involve ICU collation, then you may have an ICU library version mismatch, and resort and rebuild (respectively) is required to avoid risk of errors.

If you have previously performed a resort/rebuild in any v3.2.x version, it does not need to be done again, the correct library will be automatically used.


New keyfiles are required with GemStone/S 64 Bit version 3.3.5; keyfiles for GemStone/S 64 Bit 3.2.x or earlier will not work with v3.3.5. To acquire an updated keyfile for version 3.3.5, 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, depending on which version you are upgrading from. 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.3.5.

The following instructions use the version number 3.2.16 to refer to the version you are upgrading from, and version number 3.3.5 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.3.

2. File out your application code

If you do not already have source code for your application stored externally to the GemStone repository in a code management system, it is recommended to file out all application source code. Filein of application code is used to recompile all methods. You may also write code to manually recompile methods in all classes; see Recompile application code for details.

You should confirm that the format of your filed out code does not create new versions of your application classes on filein.

GemStone supports multiple versions of the same class, but tools operate on the most recent version of the classes. If you have instance of older versions of your applications classes that have not been migrated to the latest version, these class versions will not be upgraded by filein. We recommend that you migrate all instances to the most recent version of your application classes.

3. 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.3.5 kernel methods, and refer to the Release Notes for version 3.3 and all release notes after the version you are upgrading from, to determine whether your changes are still necessary or appropriate. For a listing of Release Notes, see GemStone/S 64 Bit Release History.

Any changes that you have made to the GemStone/S 64 Bit kernel classes will be lost during upgrade; you MUST file these out in order to preserve the changes in version 3.3.5.

Prepare for Upgrade

1. Install and configure GemStone/S 64 Bit 3.3.5

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

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

If you copy the configuration files from your previous version to the version 3.3.5, be sure to review any changes in configuration parameters to determine if changes are needed.

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.16 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.16 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. The repository must be cleanly shut down to avoid needing recovery when it is restarted with the new version’s executables. For example:

% stopstone stone3216

where stone3216 is the name of the version 3.2.16 stone on this machine.

5. Set environment variables for version 3.3.5

Set the environment variables required for the upgrade.

C shell:

% setenv GEMSTONE InstallDir335
% set path = ($GEMSTONE/bin $path)
% setenv upgradeLogDir tempDir 

Bourne or Korn shell:

$ GEMSTONE=InstallDir335
$ export GEMSTONE
$ export PATH=$GEMSTONE/bin:$PATH
$ upgradeLogDir=tempDir
$ export upgradeLogDir

where InstallDir335 is the GemStone/S 64 Bit version 3.3.5 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 each extent file that your v3.2.16 repository uses, to the directory and/or filename that will be used with v3.3.5.

For example:

% cp InstallDir3216/data/extent0.dbf InstallDir335/data/
% cp InstallDir3216/data/extent1.dbf InstallDir335/data/
% cp InstallDir3216/data/extent2.dbf InstallDir335/data/

The extent file names and locations are specified in the configuration file under the parameter name DBF_EXTENT_NAMES.

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.3.5. If the transaction log directories will be reused for version 3.3.5, any transaction logs should be deleted or copied elsewhere.

Perform the Upgrade

1. Start the Stone

Start the 3.3.5 Stone on the 3.2.16 extents you just copied:

% startstone stoneName335
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 stoneName335

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. Restore System Account passwords

Log in to GemStone/S 64 Bit version 3.3.5 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.16. For example:

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

where 3216Password is the account password used in version 3.2.16.

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

If you have modified any kernel class methods of the previous version or if you have added methods to kernel classes, compare your changes with the changes in version 3.3.5 to see whether your changes are still necessary or appropriate. Carefully review the Release Notes for each intervening version, as well as examining code in the image.

If the kernel class changes are still applicable, file in the changes, verify that errorcount is 0, and commit.

3. Recompile application code

The upgrade process requires all executable methods to be recompiled. You should have fileins available, from Step 2.. Alternatively, you may iterate classes in your image and recompile each one. If you are reusing scripts that managed recompile for the 2.x conversion, verify that the configuration parameter GemConvertArrayBuilder is not set.

a. Recompile by filein

File in all development and application code. Verify that errorcount is 0, and commit.

If you have instances of previous versions of classes, these old class versions will not be recompiled by this process. You should ensure that all application instances are migrated to current class versions before conversion, or manually recompile instances of older class versions.

b. Recompile within image

To recompile classes without filein, for each class in your repository execute

Class recompileAllMethods

You should ensure that you do not miss any classes. If you have instance of older versions of your classes, you will need to recompile methods on these older versions. For example:

class classHistory do: [:aClassVersion | 
		aClassVersion recompileAllMethods]

Attempting to execute methods that have not been recompiled will result in errors.

4. Recompile source code in persistent blocks

The compiled code in persistent blocks also requires recompile before it can be executed. All persistent executable blocks will need to be recompiled as part of upgrading.

c. Application-specific stored blocks

If your application stores persistent blocks, you will have to locate and recompile all such blocks before they can be executed.

d. SortBlocks in SortedCollections

To recompile the sortBlocks in persistent SortedCollections in your application, you may run the postconv script. This script only converts simple blocks; if your SortedCollection blocks are not simple (such as referring to method context), they cannot be automatically recompiled.

postconv [-c <numCacheWamerGems>][-h][-s <stoneName>] [-r]
[-n <numberOfSessions>] [-t <tempObjCacheSize>] [-u <userId>]

-c <numCacheWamerGems> specifies the number of cache warmer threads in a single gem to load the object table into the shared cache before starting post-conversion. If not specified, no cache warming is done.
-h prints this usage information.
-s <stoneName> sets the name of the running stone to scan; if this option is not used, the script uses gs64stone.
-n <numberOfSessions> specifies the number of parallel sessions which will convert the instances of SortedCollection and its subclasses. By default, use one session.
-r specifies to reuse an existing version of $upgradeLogDir/AllSortedCollections.bms, if it exists. This file contains the OOPs of all instances of SortedCollections and its subclasses. By default, the existing file is deleted and a new one created.
-t <tempObjCacheSize> sets the size of GEM_TEMPOBJ_CACHE_SIZE in KB; by default, 20000.
-u <userId> is the UserId whose SymbolList includes all subclasses of SortedCollection, for which instance’s sortBlocks will be converted. If not specified, defaults to SystemUser

For example,

% postconv -s stoneName335

The postconv script will write progress messages to stdout. When it completes, it will report:

postconv[INFO]: Congratulations! NNN SortedCollections were
successfully converted. No errors were detected.

If postconv reports errors, the results include information on the specific sortBlocks that failed recompile, such as those for complex sort blocks. These will need manual repair. Contact GemTalk Technical Support for assistance.

5. Resort for ICU-based collation

This step is only required if all of the following are true:

  • The repository has been progressively upgraded through any 3.1.x version.
  • It contains data structures that existed in v3.1.x, that depend on ICU collation order or encoding, including SortedCollections that include unicode strings, indexes on unicode strings, , or other string-based persistent data structures for application in Unicode comparison mode
  • These data structures have not been resorted/rebuilt in a previous 3.2.x version as part of an earlier upgrade.

If these are true, then you should resort all instances of SortedCollection that involve unicode strings (or legacy strings in Unicode Comparison Mode), and drop and rebuild indexes that involve instances of unicode strings (or legacy strings in Unicode Comparison Mode), to ensure these are sorted according the ICU collation now in use in the image.

After upgrade to 3.3.5, the repository be will configured to use either ICU v52.1 or v54.1, depending on the previous version. The ICU library version loaded at login is controlled by the value of (Globals at:#IcuLibraryVersion).

6. Regenerate cached instances of PetitParser classes

Instance of PetitParser classes (classes with names that begin with PP) are not automatically converted to the new class versions. If you are upgrading from v3.2x and using PetitParser classes directly, and you have persistent instances, you should regenerate these instances.

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 8.1 or later for VW, or GBS 5.4.3 or later for VA, to connect to a GemStone/S 64 Bit v3.3.5 repository.

Configure GBS to use the version 3.3.5 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. If your GBS clients run on a different platform than your GemStone server, refer to the Installation Guide for that platform.

Previous chapter

Next chapter