1. GemConnect 2.5 Release Notes

Platforms for Version 2.5

GemConnect version 2.5 is certified on the following GemStone server product versions and platforms:

Minimum Oracle version is now 19

GemConnect now built using Oracle version l9.14.0.0.0. All versions of Oracle earlier than 19 are not supported.

New library name format

For v2.5, the GemConnect library name has been changed to be consistent with other GemStone shared library names.

Previously the name was (for example), liboraapi24-643.so, where "24" was the GemConnect version, "64" indicated 64 bit, and "3" distinguished the library from those for legacy environments.

Now, the name is (for example), liboraapi25-3.7.1-64.so, which includes the server version with which the library was built, in this case 3.7.1.

The current GemStone/S 64 distributions include (in ualib), a GemConnect 2.4 library using the older filename. An undetermined future release of GemStone/S 64 Bit will start including GemConnect 2.5 libraries using the new filename format.

The GemConnect v2.5 distribution includes an equivalent v2.5 shared library, with the name liboraapi25.so. This is a library built with GemStone/S 64 Bit v3.7 library, that is compatible with 3.7 and later 3.7.x versions. When this library is copied to the GemStone/S 64 bit installation, it must be renamed to match the new format.

For example:

os$ cp $GemConnect/ualib/liboraapi25.so $GEMSTONE/ualib/liboraapi25-3.7.1-64.so

Makefile name change

The name of the makefile for GemConnect has also been changed. The name now includes the version, for example Makefile25.

New Process for specifying Oracle Library

Earlier releases of GemConnect required specifying the location of the Oracle libraries using $LD_LIBRARY_PATH. The SELinux security mode does not pass on the value of this environment variable, causing problems on this operating system.

To avoid this problem, in this release a new process is used to specify the Oracle libraries. You must now specify the full path to the Oracle library libclntsh*.

The actual path and name will depend on your particular 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.

There are two ways to specify the path:

• Set the environment variable $GS_GEMCONNECT_ORACLE_LIBRARY.

For example,

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

• Set Globals at: #GemConnectOracleLibrary

For example,

Globals at: #GemConnectOracleLibrary put: '/opt/oracle/l9.14.0.0.0/lib/libclntsh.so.19.1'

#GemConnectOracleLibrary may be a String or a Block which returns a String when evaluated.

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

Incorrect configuration will signal RdbError 34 (#orlibError), which produces an error similar to the following:

ERROR 34 , a GsRdbError occurred (error 34), reason:oralibError, Oracle library load error, path: '/opt/oracle/12.2.0.1.0/lib/libclntsh.so' details: 'Dlopen failed: /opt/oracle/12.2.0.1.0/lib/libclntsh.so: cannot open shared object file: No such file or directory'

Support for Kerberos / Oracle wallet authentication

GemConnect now supports Kerberos and Oracle wallet authentication.

To activate this, set the new GsOracleParameters instance variable #credentials to #EXT (external). The default value for normal Oracle-based authentication is #RDBMS.

One of the following informational messages will appear on stdout during a GsOracleConnection connect:

[Info] Credentials: #RDBMS

or:

[Info] Credentials: #EXT

Attempting to set credentials to something other than #RDBMS or #EXT will trigger the RdbError 35 (#credentialsError). For example:

ERROR 35 , a GsRdbError occurred (error 35), reason:credentialsError, Invalid credentials - must be either #RDBMS or #EXT

SHA build information provided in version information

The unique internal GemTalk SHA code for this build of GemConnect is now included in the verora.txt file in the product.

For example:

GemConnect for Oracle

2.5

Official Release

8316dc34a89c61bd41215d064675db19c29208c4

Mon Sep  9 13:17:32 PDT 2024

Additional information printed during the connection to Oracle

When a connection to Oracle is established, the output now includes the Oracle database name and the username for the connection.

Timeouts for OCI operations

The default timeout for Oracle OCI calls is 2 minutes. This timeout can be overridden using an environment variable, or for an individual connection.

The new environment variable $GS_GEMCONNECT_OCI_TIMEOUT specifies how long to wait for Oracle OCI calls before timing out.

To control the timeout for individual database calls, the following methods have been added:

GsOracleConnection >> ociTimeout: seconds
Set the timeout in seconds for OCI operations. If seconds is nil, the default handling ($GS_GEMCONNECT_OCI_TIMEOUT or 2 minutes) will apply.

GsOracleConnection >> ociTimeout
Returns an integer seconds timeout value that has been set. If this is nil, the default handling ($GS_GEMCONNECT_OCI_TIMEOUT or 2 minutes) will apply.

After an OCI call is initiated and does not complete within the timeout (including a default timeout when no specific timeout is defined), it triggers RdbError 33 (#timeoutError), for example:

ERROR 33 , a GsRdbError occurred (error 33), reason:timeoutError, Oracle OCI operation timed out, connection: aGsOracleConnection stream: aGsRdbWriteStream

Support for recent GemStone/S 64 Bit special classes

GemConnect support has been added for the new "special" classes added in GS 3.6:

SmallTime

SmallDate

SmallDateAndTime

SmallScaledDecimal

These classes are comparable to the previously existing Integer/SmallInteger and Fraction/SmallFraction, etc., pairs. When an instance of a Time, Date, DateAndTime, or ScaledDecimal is returned from Oracle, and the value is in the range of the equivalent Small* class, the instance of the Small* class will be returned.

Returning instances of DateAndTime rather than DateTime

By default, GemConnect will return DateTime objects for Oracle dates.

The new GsOracleConnection instance variable #returnDateAndTime enables mapping of appropriate Oracle fields to DateAndTime objects. When this flag is set to true, GemConnect will return instances of SmallDateAndTime or DateAndTime, instead of instances of DateTime.

Added Errors

The following errors have been added in this release.

33: #timeoutError
Oracle OCI operation timed out, connection: <c> stream: <s>.
See Timeouts for OCI operations.

34: #orLibError
Oracle library load error, path: <p> details: <d>.
See Added Errors.

35: #credentialsError
Invalid credentials - must be either #RDBMS or #EXT.
SeeSupport for Kerberos / Oracle wallet authentication.

UncontinuableErrors in GemConnect userActions when trapped by an application exception handler

There are a number of places within GemConnect userActions where they do callbacks to the Smalltalk VM. If this Smalltalk code happens to hit an error, and the error is trapped by a customer application exception handler, this can confuse the Smalltalk VM and trigger an UncontinuableError. (#49024)

Uncontinuable error during GemConnect user actions

When using GemConnect in a multi-threaded environment where one or more of the other threads are performing socket operations (for example, while using Seaside), there can be rare failures of threads performing GemConnect user actions with an UncontinuableError (error 6011). There are a number of different detailed error messages, but these will usually mention: "would cross frame of C primitive, user action, or FFI call". (#48479)

GsRdbChangeNotifObj >> removeAllNotification invokes obsolete code

This method used an obsolete primitive to enter protected mode, resulting in an error. (#49506)

Rounding error on Oracle BINARY_FLOAT fields

The auto conversion from an Oracle BINARY_FLOAT, when SQLT_IBFLOAT fields are mapped to SQLT_FLT rounded incorrectly. (#48862)

Note that this fix has been available in the shared libraries distributed with server versions 3.6 and later.

GemConnect Installation Errors

The GemConnect installation script for v2.4 included an topaz define that was invalid in GemStone/S 64 Bit v3.6 and later. (#49155)