Java command line to run OMEGAMON Data Connect

Whichever platform you choose, you can use a Java™ command line to run OMEGAMON® Data Connect.

Before you enter the Java command line

In the shell where you will enter the Java command line, perform the following actions:

  • If you choose to run OMEGAMON Data Connect on z/OS®, deactivate automatic code page conversion of tagged files. For example, set the z/OS UNIX environment variable _BPXK_AUTOCVT to OFF.

    Reason for this action: on z/OS, automatic code page conversion can cause the Java virtual machine to misinterpret OMEGAMON Data Connect configuration files.

  • Change the current working directory to the OMEGAMON Data Connect user directory that you want to use for this instance of OMEGAMON Data Connect.

    Reason for this action: OMEGAMON Data Connect treats the current working directory as the OMEGAMON Data Connect user directory.

Example Java command line

java \
  -Xms1024m -Xmx4096m -XX:+ExitOnOutOfMemoryError \        1 
  -Dfile.encoding=ISO8859-1 \                              2 
  -Djava.net.preferIPv6Addresses=system \                  3 
  -Dodp.ext=<odp_extensions_paths_list> \                  4 
  -jar <odp_installation_directory>/lib/odp-server.jar \   5 
  --spring.config.name=connect                             6 
 1 
The initial heap size (-Xms) and maximum heap size (-Xmx) shown here are examples only.

The maximum heap size must be large enough to accommodate the OMEGAMON Data Connect queue capacity of each output. In practice, the default queue capacity meets typical requirements and fits within this example maximum heap size.

For more information on setting the heap size, see the advice on how to do heap sizing in the IBM® Semeru Runtime® Certified Edition for z/OS documentation.

 2 
Setting the file encoding option avoids a potentially inappropriate system default encoding, such as EBCDIC on z/OS.
 3 
Setting the Java system property java.net.preferIPv6Addresses to system causes OMEGAMON Data Connect to resolve hostnames into IP addresses according to the order of IP addresses that the operating system returns for a hostname. That order determines whether OMEGAMON Data Connect uses an IPv4 address or an IPv6 address.

For example, if you specify the hostname myserver.example.com as the value of an OMEGAMON Data Connect configuration parameter, then, if the operating system returns an IPv6 address before an IPv4 address for that hostname, OMEGAMON Data Connect uses the IPv6 address.

For more information about the order of IP addresses returned by the operating system and how to change that order, see the operating system documentation for the IP resolver.

 4 
The -Dodp.ext runtime option specifies the value of the custom Java system property odp.ext.

odp.ext specifies the location of OMEGAMON Data Connect mapping extension JAR files. The value of odp.ext is a comma-separated list of directory paths and individual .jar file paths. In the directory paths, OMEGAMON Data Connect looks for files with the extension .jar. OMEGAMON Data Connect does not recurse into subdirectories.

Mapping extensions extend OMEGAMON Data Connect to support different types of incoming data. OMEGAMON Data Connect supplies mapping extension JAR files in the lib/ext directory under the installation directory. You can also choose to store mapping extension JAR files in the user directory.

The sample JCL procedure and shell script for running OMEGAMON Data Connect set a default value for -Dodp.ext that includes the lib/ext directory under the installation directory and the extensions directory under the user directory:

  -Dodp.ext=<odp_installation_directory>/lib/ext,\
            <odp_user_directory>/extensions

If a mapping extension JAR file for an agent exists in more than one location, then OMEGAMON Data Connect uses the latest version of the file.

 5 
odp-server.jar is a symbolic link that refers to the OMEGAMON Data Connect core JAR file, odp-server-version.jar.

It is your choice whether to use the symbolic link, which has no version in its file name, or the original file with a version in its name. To avoid updating the command for each version, use the symbolic link.

 6 
connect is the base name for OMEGAMON Data Connect configuration files. For example, a config/connect.yaml file in the OMEGAMON Data Connect user directory.

Platform-specific options

In some cases, on some platforms, you might need to specify additional Java command-line options.

For example, on z/OS, if you use Transport Layer Security (TLS) with the store type JCERACFKS to specify a RACF® key ring with the safkeyring protocol, then you need to ensure that the Java virtual machine (JVM) includes the IBMZSecurity provider to handle that protocol. You can include the IBMZSecurity provider by specifying the following command-line option:

  -Djava.protocol.handler.pkgs=com.ibm.crypto.zsecurity.provider