1. Installing GemConnect

GemStone server

A GemStone/S 64 Bit v3.6.x or later object server, installed and started according to instructions in the appropriate GemStone/S 64 Bit Installation Guide.

If you are using a server version earlier than 3.7, you will need to request a shared library for your version of the GemStone server, GemConnect 2.5.1, and your platform. Contact GemTalk Technical Support for a library. For more on this shared library, see Setup GemConnect Library.

Server keyfile

Authorization for using GemConnect is provided by the GemStone/S 64 Bit keyfile. Your GemStone server must be started using a keyfile that provides authorization for GemConnect in order to use GemConnect.

If you are licensed to use GemConnect, you should have received a keyfile with the appropriate authorization. Contact GemStone Technical Support, or write to keyfiles@gemtalksystem.com, if you have issues or questions.

GemConnect+GS64 shared library

A GemConnect version 2.5.1 shared library complied with a GCI-compatible version of your GemStone server. The shared library provided in the v2.5.1 distribution is compatible with GemStone/S 64 Bit versions 3.7 through 3.7.4, and is expected to be compatible with later 3.7.x server versions. For further details, Setup GemConnect Library.

Relational Database Server

• An Oracle 19 relational database server must be running and available via the $ORACLE_HOME environment variable. This version of GemConnect was built and tested with Oracle version l9.14.0.0.0.
• If GemStone and your relational database server run on different machines, you will also need Oracle Net10 (supersedes SQL*Net). Be sure that it is installed and running on the machine where GemStone will be running, so that GemStone will be able to communicate with the relational database.

C compiler

You do not need a C compiler to use GemConnect.

Prior to Installation

Before installing GemConnect into your repository, ensure that you have a current backup.

Install GemConnect Distribution

The following steps install GemConnect into a GemStone/S 64 Bit server.

Step 1. Log in to a machine that has the GemStone repository server installed on it.

You should login as your GemStone system administrator account to perform this installation procedure, so the GemConnect files will be owned by this user. If you plan to limit GemConnect access to a certain UNIX group, the owner of the GemConnect files must be a member of that group.

Step 2. Ensure you have set the GemStone environment set up, as described in the GemStone/S 64 Bit Installation Guide.

• The $GEMSTONE environment variable should be to the full pathname (starting with a slash) of your GemStone installation directory, as you would normally have when working with GemStone.
• The machine search path should include $GEMSTONE/bin.

Step 3. Create an installation directory.

You can install the GemConnect files into almost any directory. Administration is easier, however, if you install GemConnect in a directory you create in the same top-level directory you installed the GemStone server software. For example, if the GemStone server directory is:

/usr2/GemStone64Bit3.7.2-x86_64.Linux

then install GemConnect under /usr2. For example,

os$ mkdir /usr2/GemConnect2.5.1

Step 4. We recommend defining an environment variable to the GemConnect installation directory to reduce the need to type the complete pathname. For example, if you have installed GemConnect in /usr2/GemConnect2.5.1:

C shell:

os$ setenv GEMCONNECT /usr2/GemConnect2.5.1

Bourne shell or Korn shell:

os$ GEMCONNECT=/usr2/GemConnect2.5.1

os$ export GEMCONNECT

In these instructions, the GemStone/S 64 Bit installation directory will be referred to as $GEMSTONE, and the GemConnect installation directory you have just created will be referred to as $GEMCONNECT.

Step 5. Copy the GemConnect distribution file to this directory. GemConnect is provided as a zipped archive file with a name similar to GemConnect-2.5.1-oracle19-x86_64.Linux.zip.

Step 6. Change directory (cd) to the directory in which you will install the GemConnect files, $GEMCONNECT. Unzip the distribution file. For example:

os$ cd $GEMCONNECT

os$ unzip GemConnect-2.5.1-oracle19-x86_64.Linux.zip

Step 7. Check that the new GemConnect directory tree was correctly installed, and that they have the correct file protection settings.

The GemConnect administrator should have read and execute access to GemConnect directories and all the directories above them in the directory tree.

os$ cd $GEMCONNECT

os$ ls -al

If the permissions are set correctly, they look similar to this:

dr-xr-xr-x 2 gsadmin smtalk 4096 May 12 14:21 image

dr-xr-xr-x 2 gsadmin smtalk 4096 May 12 14:21 licence

dr-xr-xr-x 2 gsadmin smtalk 4096 May 12 14:21 ualib

-r--r--r-- 1 gsadmin smtalk  214 May 12 14:21 verora.txt

If necessary, use the chmod command to reset permissions or the chown command to change the owner.

Setup GemConnect Library

GemConnect requires a shared library that is linked with a GCI-compatible version of the GemStone/S 64 Bit server product, as well as for the specific GemConnect version, and is named according to the rules for the GemConnect version.

The GemConnect shared library is distributed with both the server product and the GemConnect product. Since each of these is built using the product version of the corresponding product that is current at the time of release, not all server and GemConnect version combinations are distributed.

Versions of GemStone/S 64 Bit that are current at the time of this GemConnect release include the distribution library that is compatible with GemConnect v2.4. These libraries are not compatible with GemConnect 2.5.1.

• If you are installing GemConnect v2.5.1 into GemStone/S 64 Bit version 3.7 through 3.7.4, and potentially future versions, you may use the library that is distributed with the GemConnect release. This library is distributed with the nonspecific name liboraapi25.ext, and must be renamed to conform to the new naming format, e.g. liboraapi25-3.7.4-64.so. The version number must correspond to the version of your GemStone repository.

For example:

os$ cp $GEMCONNECT/ualib/liboraapi25.so $GEMSTONE/ualib/liboraapi25-3.7.4-64.so

• If you are using an earlier version of the GemStone/S 64 Bit server, you will need to request the shared library from GemTalk Technical Support. A library that is provided by GemTalk Technical Support will have the correct name; copy this file to $GEMSTONE/ualib/.
• If a future release of GemStone/S 64 Bit version includes $GEMSTONE/ualib/liboraapi25-version-64.ext, then no copy is needed.

Ensure that your GemStone/S 64 Bit server installation includes the file $GEMSTONE/ualib/liborapai25-version-64.ext, with the correct file permissions. The permissions should look like this:

-r-xr-xr-x gsadmin smtalk 124036 May 11 11:21 liboraapi23-3.7.4-64.so

Setup access to the Oracle Library

The installation process requires access to your Oracle library libclntsh*. The specific path and name will depend on the version of Oracle. For example, on Oracle 19 the name might be libclntsh.so.19.1 and the full path /opt/oracle/l9.14.0.0.0/lib/libclntsh.so.19.1.

Step 1. Your $LD_LIBRARY_PATH environment variable must include the directory containing this library. For example,

os$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/export/smalltalk/oracle/19.14.0.0.0/x86_64.Linux/lib/

Step 2. You must specify the full path to the library name. There are two way to specify this path:

• Set the environment variable $GS_GEMCONNECT_ORACLE_LIBRARY.

For example,

os$ export GS_GEMCONNECT_ORACLE_LIBRARY=/opt/oracle/l9.14.0.0.0/lib/libclntsh.so.19.1

• Set Globals at: #GemConnectOracleLibrary to a String, or a block returning a String.

For example,

topaz 1> exec Globals at: #GemConnectOracleLibrary put: '/opt/oracle/l9.14.0.0.0/lib/libclntsh.so.19.1' %

If both are specified, #GemConnectOracleLibrary takes precedence over $GS_GEMCONNECT_ORACLE_LIBRARY.

Add GemConnect to your GemStone Repository

This step either installs GemConnect into a repository in which it was not previously installed, or upgrades an existing earlier version of GemConnect to version 2.5.1.

Step 1. Change to a directory suitable for writing the GemConnect installation log file. You must have write permission to this directory.These instructions used workingDirectory to refer to this directory.

% cd workingDirectory

Step 2. Log in to the GemStone server as SystemUser, using linked Topaz.

os$ topaz -l

...

topaz> set user SystemUser pass systemUserPassword

topaz> login

...

topaz 1>

Step 3. File in the GemConnect for Oracle classes and methods, using the following Topaz command line:

topaz 1> input $GEMCONNECT/image/gsoraapi.gs

Step 4. Check for errors in the upgrade.

The number of errors will appear at the end of the file-in process. The error line should look similar to the following:

topaz 1> obj ErrorCount

0

If the number is greater than zero, please contact GemTalk Technical Support. With your request, include the log file that was created during the installation:

workingDirectory/gsoraapifilein251.log

Step 5. Since this session is logged in as SystemUser, you should log out of GemStone, and exit topaz.

topaz 1> logout

topaz> quit

This completes the installation or upgrade. GemConnect 2.5.1 is now installed and ready for use.