1. Installing GemConnect
This document describes how to install GemConnect 2.4 on workstations running the UNIX/Linux operating system. It also explains how to upgrade a GemStone repository for use with GemConnect and how to set up new GemConnect users.
Please review the GemConnect Release Notes for details of the changes before upgrading to this version. If you are upgrading from a version earlier than 2.3, please review the Release Notes for each intermediate version, to see the full set of changes.
This version of GemConnect supports GemStone/S 64 Bit v3.3.1 and later only.
System Requirements
Before installing GemConnect, ensure that the following system requirements are satisfied.
GemStone server
A GemStone/S 64 Bit v3.3.1 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.5, you will need to request a shared library built for your version of the GemStone server, GemConnect, and your platform; contact GemTalk Technical Support for assistance.
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.
Platform
A supported platform for the GemStone server product and version you will be using. See the GemStone/S 64 Bit Installation Guide for your server platform for more information.
Relational Database Server
- An Oracle 12c or later 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 12.2.0.1.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.
Install GemConnect
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.
We recommend that you log in using a local UNIX user name (such as the name of your GemStone system administrator) to perform this installation procedure, so that the GemConnect files will be owned by this user. Later in the installation you need to log in as root. However, if you copy the files as root, the original ownerships are maintained, which may result in file protection errors for users at your site. 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. 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.5.1-x86_64.Linux
then install GemConnect under /usr2. For example,
% mkdir /usr2/GemConnect2.4
In these instructions, the GemStone/S 64 Bit installation directory will be referred to as GS64InstallDir, and the GemConnect installation directory you have created will be referred to as GemConnectInstallDir.
Step 3. Copy the GemConnect distribution file to this directory. GemConnect is provided as a zipped archive file with a name similar to GemConnect-2.4+oracle12c-platform.OS.zip. See Distribution file names for specific file names on each platform.
Step 4. Change directory (cd) to the directory in which you will install the GemConnect files, GemConnectInstallDir. Unzip the distribution file. For example:
% cd GemConnectInstallDir
% unzip GemConnect-2.4+oracle12c-platform.OS.zip
InstallDir now contains the following subdirectories (denoted with a / character) and files:
PACKING
verora.txt
doc/
install/
make/
ualib/
See Files in GemConnect installation for a description of the contents of each file and each directory.
You must perform the rest of the installation as root, because a number of these procedures require root privileges.
Step 6. 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. This can be done by invoking $GEMSTONE/bin/gemsetup.sh or $GEMSTONE/bin/gemsetup.csh, or by appending to the machine search path environment variable.
Step 7. Define an environment variable to the GemConnect installation directory to reduce the need to type the complete pathname. For example:
% setenv GEMCONNECT GemConnectInstallDir
$ GEMCONNECT=GemConnectInstallDir
$ export GEMCONNECT
Step 8. Check to make sure that the new GemConnect directory tree includes all of the files listed in the PACKING file, and that they have the correct file protection settings.
GemConnect users should have read and execute access to GemConnect directories and all the directories above them in the directory tree. GemConnect users who need to rebuild the GemConnect shared library will also need write access to the make directory.
% cd $GEMCONNECT
% ls -al
If the permissions are set correctly, they look similar to this:
dr-xr-xr-x 2 gsadmin smtalk 4096 Mar 11 11:21 doc
dr-xr-xr-x 2 gsadmin smtalk 4096 Mar 11 11:21 install
drwxr-xr-x 2 gsadmin smtalk 4096 Mar 11 11:21 make
-r--r--r-- 1 gsadmin smtalk 912 Mar 11 11:21 PACKING
dr-xr-xr-x 2 gsadmin smtalk 4096 Mar 11 11:21 ualib
-r--r--r-- 1 gsadmin smtalk 55 Mar 11 11: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 built for the GemStone/S 64 Bit server product version and platform, as well as for the specific GemConnect version. These libraries are distributed with both the server product, and the GemConnect product. Since they are built using the current product version of the corresponding product, not all server and GemConnect version combinations are distributed.
If you are using a combination of versions that is not provided within a distribution of one of these products, please contact GemTalk technical support with your specific versions and platforms.
- 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.3; $GEMSTONE/ualib/liborapai23-643.so or liboraapi24-643.dylib. These libraries are not compatible with GemConnect 2.4.
- The GemConnect v2.4 release includes shared libraries that support GemStone/S 64 Bit version 3.5 and 3.5.1, and should be compatible with future 3.5.x versions. This library has the name liborapai24-643.so or liboraapi24-643.dylib.
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.
Copying the file as necessary, ensure that your GemStone/S 64 Bit server installation includes the file $GEMSTONE/ualib/liborapai24-643.so or liboraapi24-643.dylib.
Verify that this library has the correct file protection settings. The permissions should look like this:
-r-xr-xr-x 1 gsadmin smtalk 124036 Mar 11 11:21 liboraapi23-643.so
Add GemConnect to your GemStone Repository
You add GemConnect to your existing GemStone repository with the following steps.
Step 1. Back up your GemStone repository.
Before you begin the upgrade, make sure a current backup of your GemStone repository exists. If you need to make one, use the backup methods described in the System Administration Guide.
Step 2. Log in with some UNIX user name other than root.
Do not try this upgrade as root, unless the Stone (GemStone repository monitor process) is running on your local machine. Log in as the UNIX user who owns the GemConnect directories and files (gsadm in the example listing above).
Step 3. Set the GemStone environment for this user.
Define the GEMSTONE and GEMCONNECT environment variables and execute the gemsetup script for this user, as you did for root Ensure you have set the GemStone environment set up, as described in the GemStone/S 64 Bit Installation Guide.
Log In To GemStone
Step 4. Change to a directory in which you have write permission. This will be where the output log file for the GemConnect installation will be created. We will use workingDirectory in the following example.
% cd workingDirectory
Step 5. Log in to the GemStone server as SystemUser, using linked Topaz. For instance:
% topaz -l
...
topaz> set gemstone gs64stone
topaz> set user SystemUser password swordfish
topaz> login
[Info]: LNK client/gem GCI levels = 35100/35100
[Info]: User ID: SystemUser
[Info]: Repository: gs64stone
...
[03/12/2020 11:36:29.264 PDT]
gci login: currSession 1 linked session
successful login
topaz 1>
WARNING:
Logging in to GemStone as SystemUser is like logging in to your workstation as root—an accidental modification to a kernel object can cause a great deal of harm. Use the DataCurator account for all system administration functions except those that require SystemUser privileges, such as upgrades and full restores.
File In the New Classes
Step 6. File in the GemConnect for Oracle classes and methods, using the following Topaz command line:
topaz 1> input $GEMCONNECT/make/gsoraapi.gs
Step 7. 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 ErrorCount0
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/gsoraapifilein24.log
topaz 1> logout
Step 9. Leave Topaz and return to the operating system prompt, using quit or exit.
topaz> quit
This completes the GemStone repository upgrade procedure. GemConnect is now installed and ready for use with your GemStone system.
Set Up New Users
Step 10. If anyone who is going to use GemConnect does not have a GemStone user account, set it up according to the instructions in the GemStone/S 64 Bit Installation Guide for your server product and version.
Step 11. Have users edit their login shells’ initialization files (.bashrc or .profile). Have them add:
- The GemStone gemsetup command line. This should already be present for GemStone users.
- The definition of the ORACLE_HOME environment variable, which is the same command line they use to define $ORACLE_HOME interactively.
- The definition of an environment variable LD_LIBRARY_PATH to $ORACLE_HOME/lib in their path. $ORACLE_HOME/lib must be the first entry for the LD_LIBRARY_PATH environment variable.
Have the users invoke their edited initialization files immediately, to verify that this is setup correctly.
The environment needed for running GemConnect will now be set up automatically each time they log in.
Step 12. Once users log in to GemStone, they can also test the ORACLE_HOME environment variable setting by invoking this method:
System performOnServer: 'echo $ORACLE_HOME'
If the variable is set correctly, this method returns a GemStone string that is the pathname to the Oracle installation directory.
Installed Files and Directories
Table 2 shows the directories and files that compose this GemConnect distribution, and are installed under the GemConnect installation directory.