4. Converting from GemStone/S 64 Bit 2.4.x versions

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

2. File out modifications to GemStone classes

File out any modifications or additions you made to GemStone/S 64 Bit kernel class methods. You will need to carefully compare these changes with GemStone/S 64 Bit 3.3.1 kernel methods to determine whether your changes are appropriate.

GemStone kernel classes have extensive changes for version 3.0, as well as changes in v.3.1, 3.2, and 3.3. See the Release Notes for version 3.0 for details of the major changes, and read these carefully before filing 2.x code modifications into your version 3.3.1 repository. You should also review the changes documented in all subsequent release notes. For a listing of Release Notes, see GemStone/S 64 Bit Release History.

3. Update references to ScaledDecimal, if necessary

If your application uses the ScaledDecimal class, determine if you wish to continue to use this class under its new name FixedPoint, or if you want to use the new implementation of ScaledDecimal. If you wish to continue to use the old ScaledDecimal with its new name, you will need to modify your source code fileout so that all references to ScaledDecimal are changed to refer to FixedPoint, and all uses of the s ScaledDecimal literal notation are to the FixedPoint p literal notation.

Note that you will also have to manually update stored instances of ScaledDecimal, which is done following upgrade.

4. Verify returned value from disallowUsedPasswords is Boolean

Verify that your repository returns a boolean for this setting. Execute:

AllUsers disallowUsedPasswords

If result is neither true nor false, then before upgrade, execute:

AllUsers disallowUsedPasswords: true.

System commitTransaction.

5. Remove indexes on instances of reimplemented server classes

If you have indexes that include instance of any of the following classes, these indexes will need to be removed and rebuilt in version 3.3.1 to update information within the indexing structures.

DoubleByteString

DoubleByteSymbol

Float

LargeNegativeInteger

LargePositiveInteger

QuadByteString

ScaledDecimal (if you will be using the new ScaledDecimal implementation)

SmallFloat

If unsure, it is safer to remove the index rather than to risk incorrect indexed query results. You may remove these indexes prior to upgrade, or as part of application filein after upgrade.

6. Prepare class comments for 3.x changes, if necessary

The Class description variable is used in v2.x to hold class comments. If you have defined class comments using GBS browsers, depending on the version of GBS, class comments may be stored in the description variable or as class method named comment that returns a string containing the comment text.

If there is comment information in the description field, you will need to save the contents elsewhere. Due to structural changes in classes, the conversion process will remove any data stored here. Following upgrade, you can restore the class comment, which will then be upgraded for the new handling of comments in v3.1.

1. Install and configure GemStone/S 64 Bit 3.3.1

Install GemStone/S 64 Bit 3.3.1 to a new installation directory, separate from the installation directory for version 2.4.8, as described in Chapter 1 of this Installation Guide.

Configure GemStone/S 64 Bit 3.3.1 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.1, be sure to review any changes in configuration parameters to determin 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 2.4.8 system 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.

3. Stop users and shut down repository

Halt all user activity on the repository you are going to upgrade:

Log in to Topaz as DataCurator, and execute:

topaz 1> printit

System stopUserSessions.

%

You may now shut down the Stone:

% stopstone stone248

where stone248 is the name of the version 2.4.8 stone on this machine. It is strongly recommended, but not required, that the repository be cleanly shut down before it is restarted under version 3.3.1. If the repository is not cleanly shut down, you must restart using the -N option.

4. Set up the version 3.3.1 environment.

Set the environment variables required for the upgrade.

C shell:

% setenv GEMSTONE InstallDir331

% set path = ($GEMSTONE/bin $path)

% setenv upgradeLogDir tempDir 

Bourne or Korn shell:

$ export GEMSTONE=InstallDir331

$ export PATH=$GEMSTONE/bin:$PATH

$ export upgradeLogDir=tempDir

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

5. Copy extent files

Copy your version 2.4.8 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 2.4.8 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.3.1 installation. For example:

% cp InstallDir248/data/extent0.dbf 331location

% cp InstallDir248/data/extent1.dbf 331location

% cp InstallDir248/data/extent2.dbf 331location

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

If version 3.3.1 will run on a platform with a different byte ordering than the version 2.4.8 repository, or if you are using raw partitions, you will need to use copydbf.

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

1. Convert using startstone

Conversion is done using the -C flag to startstone. Perform the conversion on the 2.4.8 extents you just copied:

% startstone -C stoneName331

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 <tempObjCacheSize>] [-s <stoneName>]

-h prints this usage information.

-c <tempObjCacheSize> 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 stoneName331

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.1 as DataCurator, and change the password for SystemUser, which you changed to swordfish prior to the conversion, back to its previous value. Also, change the passwords for GcUser and DataCurator, which were reset by the conversion process, back to the version 2.4.8 value:

topaz 1> printit

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

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

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

System commitTransaction

%

where 248Password is the account password used in GemStone/S 64 Bit version 2.4.8.

1. Reinstall any other GemStone products that modify kernel classes

If you use GemConnect or GemBuilder for Java, you must reinstall the appropriate version into your repository at this time. Version 3.3.1 requires new versions of these products. Contact GemStone Technical Support for more information.

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.3.1 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, to use the new bytecodes and classes introduced in version 3.0. You should have fileins available, from Step 1.. Alternatively, you may iterate classes in your image and recompile each one.

GsDevKit environments will not need to perform this step.

a. Recompile by filein

Before filing in application code, you must prepare to handle any square-bracket Array constructors in your code. If your application code contains Array constructors using the syntax #[ a, b, c ], this is not valid syntax for version 3.x. In v3.x, you must use the syntax { a . b . c } for Array constructors.

To allow filein of application code that includes the square bracket Array constructors, in the gem that will perform the filein, prior to filein, execute:

System configurationAt: #GemConvertArrayBuilder put: true 

This allows code including the old Array constructor syntax to be compiled; the resulting compiled method will be correct, and its source code will be updated to the correct syntax. This configuration variable is runtime only, so it is not necessary to unset it manually.

Now, 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. Convert persistent blocks

ExecutableBlocks have been reimplemented in version 3.x; persistent instances of ExecutableBlocks are not usable in version 3.x. Executable blocks in source code are recompiled during application filein.

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 convert 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 stoneName331

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. These will need manual repair. Contact GemTalk Technical Support for assistance.

5. Restore and upgrade Class comments

In v3.1 and later, the class comment is stored in the class as a String, and accessed via #comment and #comment: methods. This differs from the comment handling in 2.x or 3.0.x.

As part of upgrade, you must upgrade comments. In particular, you should not have class methods named #comment on any of your classes. The upgradeComment script both sets the comment, from either the description field or the comment method results, and deletes the class method #comment.

Since GsDevKit handles class comments in a way that is consistent with 3.3.1 behavior, GsDevKit environments do not need to perform this step.

First, restore Class descriptions that were saved from your version 2.4.8 repository (as per Step 6.). Descriptions are restored using the description: method.

Then, convert all comments using the upgradeComments script.This converts both description: field comments and class #comment methods into the correct form.

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 stoneName331

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.

If this script reports errors, you may have non-standard comment forms. Preserve the error logs and contact GemStone Technical Support.

6. Convert instances of reimplemented server classes

Optionally, you may wish to convert instances of reimplemented classes. Instances of Float, SmallFloat, LargePositiveInteger, LargeNegativeInteger, DoubleByteString, DoubleByteSymbol or QuadByteString in your version 2.4.8 repository are not converted during conversion to 3.x. The instances auto-migrated to the new class each time they are faulted into the VM.

To avoid this overhead, you can perform a listInstances of the classes ObsLargePositiveInteger, ObsLargeNegativeInteger, ObsDoubleByteString, ObsDoubleByteSymbol, ObsQuadByteString, ObsFloat, and ObsSmallFloat, sending #convert to each instance, and committing.

7. Convert FixedPoint instances

If for Step 3., you decided to continue to use the old ScaledDecimal class, now named FixedPoint, do not perform this step.

If your 2.4.8 application included instances of ScaledDecimal, following conversion to 3.x they are now instances of FixedPoint. If you intend to use the new ScaledDecimal implementation rather than FixedPoint, you must perform a manual step to convert each instance to a new ScaledDecimal. To do this, find all instances of FixedPoint and execute code similar to the following:

newScaledDecimal := aFixedPoint asScaledDecimal.

newScaledDecimal become: aFixedPoint.

Verify that errorcount is 0, and commit.

8. Rebuild indexes, if necessary

If your application includes indexes on instances of kernel classes which have new implementations in version 3.x, these indexes must be rebuilt to update internal information in the Btree indexing structure, otherwise query results may be incorrect.

See Step 5. for more details on this requirement.

9. Upgrade user account passwords

Internal password formats changed in version 3.1. The new format uses updated, more secure encryption. As each user logs in after upgrade, 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.

For better security, 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.

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 have upgraded to 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.1 repository.

Configure GBS to use the version 3.3.1 client libraries. Note that the required libraries, library naming conventions, and the process GBS uses to identify the correct library to load 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.