Upgrading OMEGAMON Data Connect
Upgrade the Java™ runtime environment that you use to run OMEGAMON® Data Connect to Java 17 or later, 64-bit edition. Consider increasing the heap size of the Java virtual machine that you use to run OMEGAMON Data Connect. If you use OMEGAMON Data Connect to send data to Apache Kafka, revise the Kafka output configuration parameters.
Before you begin
Ensure that you have a Java 17 or later, 64-bit edition runtime environment installed on the platform where you run OMEGAMON Data Connect. For example, if you run OMEGAMON Data Connect on z/OS®, ensure that you have IBM® Semeru Runtime® Certified Edition for z/OS 17 installed. IBM Semeru Runtime Certified Edition for z/OS 17 requires z/OS 2.5 or later.
Locate the path of the Java installation directory. For example, on z/OS UNIX , /usr/lpp/java/J17.0_64/.
Procedure
- If you use a z/OS JCL procedure to run OMEGAMON Data Connect, upgrade the procedure to refer to a Java 17 runtime environment.
- Replace your procedure with the latest sample procedure supplied in
TKANSAM(KAYCONN).
Significant changes in the latest sample procedure:
VERSION
- In the
PROC
statement at the start of the procedure, the value of theVERSION
parameter is now17
. The procedure uses this value as the suffix of the Java virtual machine (JVM) load module name, JVMLDMxx. LIBPATH
- In the
PARMS
inline data set, the value of theLIBPATH
environment variable has been updated to match the directories listed in the JZOS documentation for Java 17. -Djava.protocol.handler.pkgs
- The value of the Java runtime option
java.protocol.handler.pkgs
has been updated tocom.ibm.crypto.zsecurity.provider
. This change is described later, in step 3.
- Edit the values of the symbolic parameters at the start of the procedure.
JAVAHOME
- The path of the installation directory of Java 17 or later, 64-bit edition. The directory must contain a bin subdirectory that contains the java command.
INSTLDIR
- The path of the OMEGAMON Data Connect installation directory.
USERDIR
- The path of your OMEGAMON Data Connect user directory.
- Ensure that the system can locate the JVMLDM17 load module.
The sample procedure does not contain a STEPLIB DD statement to specify the location of the load module. Instead, the procedure assumes that the load module is in a library that the system searches for programs, such as a library in the LNKLST concatenation. For example, a default SMP/E installation of JZOS places the load module in the SYS1.SIEALNKE library, which is in the default LNKLST concatenation.
If the load module is not in such a system library, then insert a STEPLIB DD statement that specifies the location of the load module. For example, hlq.JZOS.LOADLIB.
- Replace your procedure with the latest sample procedure supplied in
TKANSAM(KAYCONN).
- If you use a shell script or Java command line to
run OMEGAMON Data Connect, upgrade them to use a Java 17 or later, 64-bit edition runtime environment.
This step does not necessarily involve editing the shell script or command line. For example, the supplied sample shell script refers to the
JAVA_HOME
environment variable; in the profile that sets that variable, change the value to refer to a Java 17 runtime environment. - If you run OMEGAMON Data Connect on z/OS, and you specify the Java runtime option
java.protocol.handler.pkgs
, then set the option value tocom.ibm.crypto.zsecurity.provider
.-Djava.protocol.handler.pkgs=com.ibm.crypto.zsecurity.provider
(note the
zsecurity
qualifier in the value)The Java runtime option
java.protocol.handler.pkgs
refers to packages that contain protocol handlers. For example, a handler for thesafkeyring
protocol that you can use in OMEGAMON Data Connect SSL parameters on z/OS to refer to RACF® key rings.Previously, in Java 8, the
safkeyring
protocol handler was supplied by the IBMJCE provider in the packagecom.ibm.crypto.provider
.In Java 17, the IBMJCE provider is no longer supported. The
safkeyring
protocol handler is now supplied by the IBMZSecurity provider in the packagecom.ibm.crypto.zsecurity.provider
.Tip: Java only reads the value of thejava.protocol.handler.pkgs
runtime option if it encounters a reference to anunknown
protocol, such assafkeyring
. Otherwise, Java ignores the value of this runtime option. - In each of the methods that you use to run OMEGAMON Data Connect, consider increasing the Java heap size to match the latest samples provided with OMEGAMON Data Connect. In the sample JCL procedure and shell script to run OMEGAMON Data Connect, the Java runtime options for minimum and maximum heap size have been increased from:
-Xms64m -Xmx2048m
to:
-Xms1024m -Xmx4096m
This increase is a precautionary measure to accommodate higher data volume, including larger incoming record sizes.
Actual heap size requirements depend on factors that are specific to your site.
- If you run OMEGAMON Data Connect on z/OS, and your OMEGAMON Data Connect configuration contains Spring Boot server
SSL properties that refer to the
safkeyring
protocol, then reduce the number of slashes followingsafkeyring:
from four (4) to two (2).For example, given the followingkey-store
property value:server: ssl: key-store: safkeyring:////STCOMDP/OMDPring
remove two of the slashes:
key-store: safkeyring://STCOMDP/OMDPring
- If you use OMEGAMON Data Connect to send data
to Apache Kafka, revise the Kafka output configuration parameters.
- If you specify Kafka producer properties (that is, parameters under the key
connect.output.kafka.properties
), then wrap the property names in square brackets, and then in quotes.To ensure that OMEGAMON Data Connect correctly parses Kafka producer properties in the OMEGAMON Data Connect configuration file, you must enclose the property names in square brackets, and then in double quotes. Example:connect: output: kafka: properties: "[reconnect.backoff.max.ms]": 30000
- If you specify the optional Kafka output parameters
retry-interval
andmax-connection-attempts
, then remove those parameters.Previously, to configure the reconnection behavior of the Kafka output, you could specify optionalretry-interval
andmax-connection-attempts
parameters:connect: output: kafka: retry-interval: <seconds> # Default: 30 max-connection-attempts: <number> # Default: unlimited
retry-interval
andmax-connection-attempts
are no longer supported. They have been superseded by the enhanced internal queueing introduced by this APAR.Instead, to configure the reconnection behavior of the Kafka output, specify native Kafka producer configuration properties such as
reconnect.backoff.max.ms
:connect: output: kafka: properties: "[reconnect.backoff.max.ms]": 30000
For information about Kafka producer configuration properties, see the Apache Kafka documentation.
- If you specify Kafka producer properties (that is, parameters under the key