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

  1. If you use a z/OS JCL procedure to run OMEGAMON Data Connect, upgrade the procedure to refer to a Java 17 runtime environment.
    1. 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 the VERSION parameter is now 17. 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 the LIBPATH 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 to com.ibm.crypto.zsecurity.provider. This change is described later, in step 3.
    2. 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.
    3. 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.

  2. 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.

  3. 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 to com.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 the safkeyring 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 package com.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 package com.ibm.crypto.zsecurity.provider.

    Tip: Java only reads the value of the java.protocol.handler.pkgs runtime option if it encounters a reference to an unknown protocol, such as safkeyring. Otherwise, Java ignores the value of this runtime option.
  4. 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.

  5. 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 following safkeyring: from four (4) to two (2).
    For example, given the following key-store property value:
    server:
      ssl:
        key-store: safkeyring:////STCOMDP/OMDPring

    remove two of the slashes:

        key-store: safkeyring://STCOMDP/OMDPring
  6. If you use OMEGAMON Data Connect to send data to Apache Kafka, revise the Kafka output configuration parameters.
    1. 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
    2. If you specify the optional Kafka output parameters retry-interval and max-connection-attempts, then remove those parameters.
      Previously, to configure the reconnection behavior of the Kafka output, you could specify optional retry-interval and max-connection-attempts parameters:
      connect:
        output:
          kafka:
            retry-interval: <seconds> # Default: 30
            max-connection-attempts: <number> # Default: unlimited

      retry-interval and max-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.