As mentioned in the overview blog, there are some new features in APAR OA64880/PTF UJ93165 that are not disruptive to existing ODP users. This blog provides the details.
OMEGAMON® Data Broker
Updated Zowe™ cross-memory server
While you must update the Zowe server as mentioned in the disruptive updates blog, there are some new Zowe features that the OMEGAMON Data Broker has taken advantage of to make deployment and usability easier to manage. These include the rename of the load module, PARMLIB member, as well as the names of the Sample JCL and configuration members. The load module supplied with OMEGAMON Data Provider has been updated to match the load module supplied with Zowe 1.28.2. Details of the aforementioned changes are:
Previously, you had to rename the supplied module to ZWESIS01 before using it. The module relied on that name to load itself into the link pack area (LPA).
Now, the module no longer relies on that name. You can use the supplied member name KAYSIS01 or a name of your choice. A benefit of this change is that you can run the Zowe cross-memory server directly from theTKANMODP SMP/E target library. In the JCL that runs the Zowe cross-memory server, the STEPLIB concatenation can simply refer to the single TKANMODP library, which contains all of the required load modules: the server load module and the load modules for the OMEGAMON Data Broker plug-in.
OMEGAMON Data Broker configuration parameters are stored in the configuration member of the Zowe cross-memory server in a PARMLIB data set.
Previously, the PARMLIB member name was ZWESIPxx, where xx is the value of the optional MEM runtime parameter in the startup JCL for the Zowe cross-memory server. The default value of MEM is 00. Hence, the default PARMLIB member name was ZWESIP00.
Now, the PARMLIB member name is ppppIPxx, where pppp matches the first four characters of the Zowe cross-memory server load module name. If you use the load module name KAYSIS01 as supplied with OMEGAMON Data Provider and the default MEM value of 00, then the PARMLIB member name is KAYSIP00.
Support for line continuations in the PARMLIB member has moved from the OMEGAMON Data Broker plug-in to the Zowe cross-memory server. There is no change to the supported line continuation syntax. If you use the latest OMEGAMON Data Broker plug-in with the latest Zowe cross-memory server load module supplied with OMEGAMON Data Provider, you will not notice any difference in behavior.
Sample JCL procedure renamed to KAYSIS01 and updated
The sample OMEGAMON Data Broker startup JCL procedure TKANSAM(ZWESIS01) has been renamed to KAYSIS01. The new name reflects the fact that the corresponding supplied load module TKANMODP(KAYSIS01) no longer needs to be renamed to ZWESIS01before use.
Previously, the sample JCL procedure ZWESIS01 was a verbatim copy of the procedure supplied with Zowe . That procedure referred to the load module ZWESIS01 and specified the NAME parameter value ZWESIS_STD.
Now, the renamed and updated sample KAYSIS01 refers to the load module KAYSIS01 and specifies the NAME parameter value ODP_BROKER.
The new NAME parameter value ODP_BROKER reflects the fact that you might choose to run more than one instance of the Zowe cross-memory server on the same instance of z/OS®. For example:
- A server dedicated to running OMEGAMON Data Broker
- Another server running as part of a separate Zowe installation, unrelated to OMEGAMON Data Provider
Each Zowe cross-memory server on the same instance of z/OS must specify a unique NAME parameter value. The broker.name key of the OMEGAMON Data Provider collection configuration member, RKANPARU(KAYOPEN), must refer to the instance of the Zowe cross-memory server that runs OMEGAMON Data Broker.
Sample configuration member renamed to KAYSIP00
The sample OMEGAMON Data Broker configuration member TKANSAM(KAYBRP00) has been renamed to KAYSIP00. The new name matches the PARMLIB member name that is required if you use the Zowe cross-memory server load module supplied with OMEGAMON Data Provider with its original name, KAYSIS01, and you use the default MEM runtime parameter value, 00.
Value of broker.name key in sample collection configuration member changed to ODP_BROKER
Previously, the broker.name key in the sample OMEGAMON Data Provider collection configuration member TKANSAM(KAYOPEN)specified the value ZWESIS_STD, matching the NAME parameter in the sample OMEGAMON Data Broker startup JCL procedure.
Now, broker.name specifies the value ODP_BROKER, matching the NAME parameter in the updated sample JCL procedure. Again, this is part of the ability to run multiple Zowe instances, each with different roles, in a single z/OS instance.
OMEGAMON Data Connect
Changes to the sample JCL procedure and shell script
There are numerous changes to the sample OMEGAMON Data Connect startup JCL procedure sample/KAYCONN (now also supplied in the MVS™ library TKANSAM) and shell script bin/connect. Compare the new versions of these supplied files to your edited copies, and update your copies accordingly.
Common changes to both samples:
Previously, the sample JCL procedure and shell script assumed that your site-specific configuration file, connect.yaml, was stored in a config subdirectory under the OMEGAMON Data Connect installation directory.
The problem: that assumption risked your site-specific changes to connect.yaml being overwritten when you applied service to the installation directory. You had to be careful to not overwrite your edited connect.yaml with the latest sample file.
Now, the sample JCL procedure and shell script make it easier to keep your site-specific configuration files separate from the installation directory.
In the JCL procedure, the symbol KAYHOME, which referred to the OMEGAMON Data Connect installation directory, has been renamed to INSTLDIR. A new USERDIR symbol refers to the user directory containing your configuration file.
Similarly, in the shell script, the new environment variable ODP_CONNECT_USER_DIR refers to the user directory.
Each instance of OMEGAMON Data Connect now refers to a user directory. User directories can be shared.
Rather than referring to the original JAR file name, which contains a version, the -jar option in the Java command line that runs OMEGAMON Data Connect now refers to the new symbolic link, with the stable file name odp-server.jar. Referring to the symbolic link avoids the inconvenience of updating the -jar option when the version changes in the original JAR file name.
To conditionally filter records, you can write expressions in the Spring Expression Language (SpEL). These expressions can trigger runtime exceptions. For example, if an expression uses an integer field as the denominator in a division operation, then a zero value for that field in an incoming record will trigger a divide-by-zero runtime exception.
Previously, OMEGAMON Data Connect handled runtime exceptions that SpEL characterized as evaluation exceptions differently than other runtime exceptions:
1. For all runtime exceptions: discard the current record that triggered the exception.
2. Depending on the type of runtime exception:
- Stop processing records that use the expression; disable the table for outputs that use this filter.
- Report messages KAYC0048E and KAYC0056I.
Other runtime exceptions
- Continue processing records that use the expression.
- Report message KAYC0031W.
In that previous behavior, an expression that triggered an evaluation exception was considered to be unreliable, and was immediately excluded from processing to avoid the potential for undesirable filtering. However, in practice, that behavior is problematic, inconsistent, because other types of runtime exceptions could also be considered to mark the expression as unreliable. For details on which runtime exceptions SpEL characterizes as an evaluation exception, see the SpEL documentation.
Now, OMEGAMON Data Connect handles all runtime exceptions in expressions in the same way. A new configuration parameter for each condition, disable-table-on-error, enables you to control whether OMEGAMON Data Connect stops or continues processing records that use the expression:
1. Discard the current record that triggered the exception.
2. Report new message KAYC0057W.
3. Depending on the value of disable-table-on-error:
Continue processing records that use the expression.
- Stop processing records that use the expression; disable the table for outputs that use this filter.
- Report message KAYC0056I.
Message KAYC0048E no longer occurs.
Example use of the new configuration parameter in a global-level filter:
expression: sysplex_name.equals('PLEXA') # No safe navigation operator (?) after sysplex_name
disable-table-on-error: true # If sysplex_name field is missing, stop processing records from this table
Some events can occur frequently, resulting in numerous duplicate log messages. To avoid duplicate messages flooding the log, OMEGAMON Data Connect applies new flood control configuration parameters to some messages. Here are the new parameters shown with their default values:
where interval specifies a number of seconds (300 seconds = 5 minutes) and limit is the maximum instances of a particular message allowed within that interval.
OMEGAMON Data Connect applies flood control to the following messages:
Actuator endpoints over HTTP: now exposing only the health endpoint by default
Previously, OMEGAMON Data Connect specified the following Spring Boot property value to expose all Spring Boot Actuator endpoints over HTTP by default:
OMEGAMON Data Connect no longer specifies that property. OMEGAMON Data Connect now follows the default Spring Boot behavior, exposing only the health endpoint over HTTP.
To control which Spring Boot Actuator endpoints are exposed, use the corresponding include or exclude properties in the OMEGAMON Data Connect configuration file. For example, to expose the health and prometheus endpoints over HTTP:
For more details, see the Spring Boot documentation about exposing endpoints for production-ready features.
Removal of z/OS MVS MODIFY system command to restart OMEGAMON Data Connect
Previously, if you ran OMEGAMON Data Connect as a z/OS batch job or started task, then you could enter the following MVS MODIFYsystem command to restart OMEGAMON Data Connect without stopping the batch job or started task:
That application-specific restart method, using the parameter APPL=RESTART, is no longer supported. Instead, use the normal z/OS methods for stopping and starting batch jobs and started tasks, such as the MVS STOP system command and, for started tasks, the STARTsystem command. For details, see Reloading OMEGAMON Data Connect configuration.
Refreshed attribute support
Attributes support refreshed to include new attributes introduced by monitoring agents.
Lots of new function as described earlier. If you want additional information, don't hesitate to look at our Master Blog.