1. Installing GemConnect
This document describes how to install GemConnect 2.5 or to upgrade a GemStone repository from an older version of GemConnect to v2.5.
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.4, 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.6 and later.
System Requirements
Before installing GemConnect, ensure that the following system requirements are satisfied.
GemStone server
A GemStone/S 64 Bit v3.6 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 or link a shared library for your version of the GemStone server, GemConnect 2.5, and your platform. This can be done following the instructions Recompiling the GemConnect Shared Library, or by contacting GemTalk Technical Support. 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 shared library complied with a GCI-compatible version of your GemStone server. The shared library provided in the v2.5 distribution is compatible with GemStone/S 64 Bit versions 3.7 and 3.7.1, and may be compatible with later 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.
GemConnect Installation
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.1-x86_64.Linux
then install GemConnect under /usr2. For example,
os$ mkdir /usr2/GemConnect2.5
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:
os$ setenv GEMCONNECT /usr2/GemConnect2.5
os$ GEMCONNECT=/usr2/GemConnect2.5
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+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+oracle19-x86_64.Linux.zip
Step 7. 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.
See Files in GemConnect installation for a description of the contents of each file and each directory.
The GemConnect administrator should have read and execute access to GemConnect directories and all the directories above them in the directory tree. GemConnect administrators who need to rebuild the GemConnect shared library will also need write access to the make directory.
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 11 11:21 make
-r--r--r-- 1 gsadmin smtalk 912 May 11 11:21 PACKING
dr-xr-xr-x 2 gsadmin smtalk 4096 May 11 11:21 ualib
-r--r--r-- 1 gsadmin smtalk 55 May 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 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.
- If you are installing GemConnect v2.5 into GemStone/S 64 Bit version 3.7 or 3.7.1, 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, liboraapi25-3.7.1-64.ext. The version number must correspond to the version of your GemStone repository
For example, on Linux with GemStone/S 64 bit v3.7.1:
os$ cp $GEMCONNECT/ualib/liboraapi25.so $GEMSTONE/ualib/liboraapi25-3.7.1-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, or relink the library using the instructions on Recompiling the GemConnect Shared Library. A library 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.1-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:
os$ export GS_GEMCONNECT_ORACLE_LIBRARY=/opt/oracle/l9.14.0.0.0/lib/libclntsh.so.19.1
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.
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/make/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/gsoraapifilein25.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 is now installed and ready for use.
Setup Users
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.
The user’s environment must be setup to include:
- $GEMSTONE must be defined to the GemStone repository installation
- The operating system path must $GEMSTONE/bin.
- $ORACLE_HOME should be set to the Oracle home directory.
- $LD_LIBRARY_PATH must be defined and include the full path to directory containing the Oracle library
- $GS_GEMCONNECT_ORACLE_LIBRARY must be defined to the full path and name of the Oracle library.
To verify the connection, you may execute code such as:
run
| params conn |
params := GsOracleParameters new.
params server: oracleServerName;
userName: oracleUserLogin;
password: oracleUserPassword.
conn := GsOracleConnection newWithParameters: params.
conn connect.
conn disconnect.
%
Recompiling the GemConnect Shared Library
If you customize your GemConnect C code, or move to a new version of the GemStone/S 64 Bit server that does not have a compatible GCI library, you can rebuild the shared library using the included make file.
Note that this process may require additional configuration not documented here, depending on your customizations or on the nature of changes in future versions of the GemStone/S server. Contact GemTalk Technical Support for assistance.
Normally, the server’s GCI entry point changes occur only on major releases. In particular, any changes that may affect GemConnect are unlikely to occur on minor releases. Note that a connection to Oracle is not a sufficient test to verify compatibility, since this only confirms the subset of GCI entry points required for connection.
To use the make file, you must have a C compiler installed in your environment. See the Installation Guide for GemStone/S 64 Bit for your server version for compatible compiler versions.
To recompile the shared libraries, do the following:
Step 1. Setup the required environment variables. The following must be setup:
- $GEMSTONE must be defined to the GemStone repository installation for the version that this library is intended for.
- The operating system path must include $GEMSTONE/bin.
- $ORACLE_HOME must be set to the Oracle home directory.
- $LD_LIBRARY_PATH must be defined and include the full path to directory containing the Oracle library
- $GS_GEMCONNECT_ORACLE_LIBRARY must be defined to the full path and name of the Oracle library.
Step 2. Make a complete copy of $GEMCONNECT/make directory and change to this directory.
os$ cd $GEMCONNECT
os$ cp -r make mymake
os$ chmod -R 755 mymake
os$ cd mymake
os$ make -f Makefile25
If this does not report a error, the updated liboraapi25.so library was created in this directory. The new library must be copied to the $GEMSTONE/ualib directory and renamed. For example, on Linux with GemStone/S 64 bit v3.7.1:
os$ cp $GEMCONNECT/mynmake/liboraapi25.so $GEMSTONE/ualib/liboraapi25-3.7.1-64.so
Installed Files and Directories
Table 1 shows the directories and files that compose this GemConnect distribution, and are installed under the GemConnect installation directory.