Using the PERFORM JVMSERVER SPI to administer JVM servers

You can administer a JVM server with the PERFORM JVMSERVER SPI.

Administer your JVM server by choosing one of three action types:

JVM actions
OSGi actions
Liberty actions

JVM actions

JVM actions are core actions for generating diagnostics from a JVM server and can be performed on any JVM server type.

Taking Java™ dumps from a running JVM server

This command provides methods for taking Java dumps from an enabled JVM server and supports the following dump types:

Java core dumps, providing vital information about the JVM process, including garbage collection, thread states, loaded libraries etc.
Heap dumps, a snapshot of the memory of the Java process.
Snap traces, containing the tracepoint data held in the trace buffers.

Note: The Java address space is included as part of a CICS® dump.

When a dump is taken, a message is produced in the JVM log file similar to the following:

2020/01/14 11:49:44.319000 UTC I [EVENT_RESPONDER] [com.ibm.cics.common] [JVMDump] 
@Info : javacoreDump() - Javacore dump produced: /u/cicsuser/APPLID01/JVMSNAME/javacore.20200114.114944.67300.0001.txt

A corresponding message is produced by the JVM itself and written to STDERR (dfjvmerr). Depending on your configuration, you may also see a message in JESMSGLG.

11.49.44 JOB09255  BPXM023I (CICSUSER)  
   041                                               
   041             JVMDUMP034I User requested Java dump using './APPLID01/JVMSNAME/javaco
   041             re.20200114.114944.67300.0001.txt' through com.ibm.jvm.Dump.javaDumpTo
   041             File                                                                  
   041

Note: Check dfhjvmlog (not the CICS job log) to review messages relating the outcomes of calls to PERFORM JVMSERVER(jvmserver) JVM DUMP .... The CICS job log only contains messages that acknowledge the invocation of such calls, and does not report on their outcomes.

By default, Java dumps are written to the location determined by the value _CEE_DMPTARG in your JVM profile. When not set, JVM servers default this to ./&APPLID;/&JVMSERVER;. Additionally, the dump directory can be changed using a variety of more specific directives such as the -Xdump:directory=/path/to/file option in the JVM profile. These take precedence over the _CEE_DMPTARG option. See -Xdump for more information.

Dump options specified by the -Xdump option in the JVM profile are respected by this SPI.

This command runs asynchronously for a specific JVM server. When running, it holds a lock, so other identical commands for that JVM server are refused until the first command is complete and the lock released.

OSGi actions

OSGi actions can only be performed against OSGi JVM servers.

Refreshing OSGi packages

The PERFORM JVMSERVER(jvmserver) OSGI REFRESHPKGS command provides a mechanism for refreshing bundle dependencies. This can be used to re-wire bundle dependencies after updating bundles.

The way in which OSGi wires dependencies between bundles ensures stability. Even when dependent bundles are uninstalled, the wiring between the exported and imported packages remains in place until a refresh is issued. OSGi bundles managed by CICS bundles have the following lifecycle:

Table 1. OSGi bundle lifecycle
CICS bundle state	OSGi bundle state(s)
Install	Uninstalled → installed → resolved
Enable	Resolved → starting → active
Disable	Active → stopping → resolved
Discard	Resolved → installed → uninstalled

As an example, imagine a situation in which bundle A depends on package b with a version range of 1.0.0-2.0.0. Assume also that bundle B exports package b at version 1.0.0, and that bundle C exports package b at version 1.1.0.

Install and enable bundles A and B - this creates a wire between A and B. Bundle A will use version 1.0.0 of package b.
Install and enable bundle C. Bundle A continues to use version 1.0.0 of package b as the wire between bundles A and B is still the current, in-use wire.
Disable and discard bundle B. Bundle A continues to use version 1.0.0 of package b as the wire between bundles A and B is still the in-use wire, but is no longer current.
Execute PERFORM JVMSERVER(jvmserver) OSGI REFRESHPKGS. This removes the wire between bundles A and B and creates a new one between bundles A and C. Bundle A now uses version 1.1.0.

PERFORM JVMSERVER(jvmserver) OSGI REFRESHPKGS only refreshes bundles that have been uninstalled from the framework since the last refresh.

Note: The throughput of your system may be impacted by the use of this command. The impact will grow exponentially with the complexity of your system, the number of applications/packages and the number of interdependencies between packages. With only a few applications and interdependencies, the impact - in which workload will not fail, just stall or pause - will be minimal. Where possible, the use of OSGi declarative services is a preferred alternative to this command.

Liberty actions

Liberty actions are specific to a Liberty server embedded in a JVM server.

Collecting a Liberty server dump

Liberty server dumps provide a mechanism to collect the entire server configuration and runtime (if live) into a single file.

Note: Check the CICS job log for status messages (DFHAP1900, DFHSJ1600I and DFHSJ1603I) relating to calls to PERFORM JVMSERVER() LIBERTY SERVERDUMP.

Refreshing Liberty configuration and application changes

Liberty provides several mechanisms for receiving updates to configuration and applications. By default it polls the file system at an interval to monitor these changes. It can also be configured so that the configuration is never updated or to allow notifications of file updates to be sent via JMX MBeans.

This option is configured in server.xml using the config and applicationMonitor elements. These both contain an updateTrigger property which is used to specify which strategy is used to receive updates. The three options are supported:

polled
mbean
none

The config element is used to configure the monitoring of configuration files - server.xml and any includes. The applicationMonitor element is used to configure the monitoring of application files - those defined in the application elements in server.xml and any includes.

Note: The update trigger types for configuration monitoring and application monitoring can be independently specified.

The PERFORM JVMSERVER SPI provides the option to refresh configuration monitoring and/or application monitoring if their respective update triggers are set to type mbean. The mbean trigger type allows updates to be performed as needed, rather than when polled regularly on the off chance that something changed. The net gain is a saving of both CPU and file I/O.

To refresh configuration files, perform the following steps:

Ensure <config updateTrigger="mbean"/> is specified in server.xml (or one of its included files).
Modify server.xml and/or any included files.
Execute PERFORM JVMSERVER(jvmserver) LIBERTY REFRESH CONFIG.

This causes a configuration refresh to commence as soon as step 3. is complete.

To refresh application files, perform the following steps:

Note the Application id in server.xml, for example <application id="myApp" name="My Application" location="/u/cicsuser/apps/myApp.war" type="war" />.
Modify server.xml and/or any included files.
Execute PERFORM JVMSERVER(jvmserver) LIBERTY REFRESH APPLICATION APPID(myApp)..

This causes an application files refresh to commence as soon as step 3. is complete.

This notifies Liberty of a change to the file /u/cicsuser/apps/myApp.war.