2. Upgrading from GemStone/S 64 Bit 3.4.x or later

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.

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.7 kernel methods, and refer to the Release Notes for version 3.7 to determine whether your changes are still necessary or appropriate.

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

1. Install and configure GemStone/S 64 Bit 3.7

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

Configure GemStone/S 64 Bit 3.7 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.7, 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.6.6 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.6.6 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 stone366

where stone366 is the name of the version 3.6.6 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.7 environment.

Set the environment variables required for the upgrade. For example:

 export GEMSTONE=InstallDir37

 export PATH=$GEMSTONE/bin:$PATH

 export upgradeLogDir=tempDir

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

6. Copy extent files

Copy your version 3.6.6 extent files into the location specified by the v3.7 configuration file option DBF_EXTENT_NAMES:

a. Identify the complete set of extent files that are used by your 3.6.6 stone. This can be found by examining the configuration file for the version 3.6.6 repository, looking for the last entry for DBF_EXTENT_NAMES.

b. The target location is the setting for DBF_EXTENT_NAMES in the version 3.7 installation. Copy each of these extent files to the target location.

For example:

 cp dataDirFor366/extent0.dbf dataDirFor37

 cp dataDirFor366/extent1.dbf dataDirFor37

 cp dataDirFor366/extent2.dbf dataDirFor37/

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

1. Start the Stone

Start the 3.7 Stone on the 3.6.6 extents you just copied:

 startstone stoneName37

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 stoneName37

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 $upgradeLogDir/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.7 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.6.6. For example:

topaz 1> run

(AllUsers userWithId: 'SystemUser') password: '366Password'.

(AllUsers userWithId: 'GcUser') password: '366Password'.

(AllUsers userWithId: 'DataCurator') password: '366Password'.

System commitTransaction

%

where 366Password is the account password used in version 3.6.6.

4. Recompile methods referencing instance of reimplemented class definitions

GsHostProcess and JsonParser have new implemenations in v3.7 that affect some applications.

GsHostProcess

If you have methods that encode a reference to the GsHostProcess class (and you have not recompiled these methods after a previous upgrade to 3.6.4 or later), these methods must be recompiled. After upgrade, the compiled method will refer to the class ObsoleteGsHostProcess, which does not support new GsHostProcess primitives.

Affected instances can be found using an expression such as:

(ClassOrganizer newExcludingGlobals) referencesToObject:

		(ObsoleteClasses at: #ObsoleteGsHostProcess)

This returns instances of GsNMethod. Once these have been examined, recompile can be done using an expression of the form:

aGsNMethod recompileFromSource

Note that this recompiles using the SymbolList of the current session, which may affect other class references in the method.

If you refer to the GsHostProcess class by name or symbol, the correct class will be found in the SymbolList, and no further action is needed.

JsonParser

The JsonParser class has been replaced in v3.7 with a non-PetitParser based implementation, which is smaller and faster. The basic parse: API is the same, but PetitParser-specific methods are not present in the new implementation.

If you are using JsonParser to simply parse JSON, you do not need to do anything. The methods reference the older class (now JsonPetitParser); if you want faster JSON parsing, you can recompile methods with class references. Affected instances can be found using an expression such as:

(ClassOrganizer newExcludingGlobals) referencesToObject:

   (Globals at: #JsonPetitParser)

If you are using JsonParser as part of a PetitParser customization, references to the class by name must be updated to refer to ‘JsonPetitParser’ instead of ‘JsonParser’.

References from compiled methods to the class will continue to work, but it is recommended to edit the source code, so that a future recompile does not inadvertently introduce a reference to the new implementation, or fail due to a reference to an inherited instance variable.

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, carefully compare your changes with the changes in version 3.7 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.

1. Make backup

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

1. Recompile User Actions

It is recommended to recompile and relink User Action libraries.

2. Configure GBS

If you are using GBS clients, ensure you are running a supported version of GBS and client Smalltalk. Versions of GBS earlier than 8.7 for VW and GBS 5.4.7 for VA may be usable but are not fully supported with GemStone/S 64 Bit v3.7.

Configure GBS to use the version 3.7 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.