The CICS JVM plugin mechanism

In addition to the standard JPDA debug interfaces in the JVM, CICS provides a set of interception points in the CICS Java middleware, which can be of value to developers of debugging applications. These interception points (or plugins) allow additional Java programs to be inserted immediately before and after the application Java code is run. Information about the application (for example classname and method name) is made available to the plugin programs. The plugin programs can also use the JCICS API to obtain information about the application. These interception points can be used in conjunction with the standard JPDA interfaces to provide additional CICS-specific debug facilities. They can also be used for purposes other than debugging, in a similar way to user exit points in CICS.

There are three Java exit points:
When you use plugin programs to debug Java applications, you need to: If the classes for plugin programs are placed on other class paths, they might not be accessible to the correct classloader, and could also cause resettable JVMs to be marked as unresettable. Debug plugins can be used with resettable, continuous and single-use JVMs (with REUSE=RESET, REUSE=YES or REUSE=NO in the JVM profile), provided that the classes are placed on the trusted middleware class path.

The programming interface consists of two Java interfaces. DebugControl (full name: com.ibm.cics.server.debug.DebugControl) defines the method calls that can be made to a user-supplied implementation, and Plugin (full name: com.ibm.cics.server.debug.Plugin) provides a general purpose interface for registering the plugin implementation. These interfaces are supplied in dfjwrap.jar, and documented in JAVADOC HTML (see The JCICS class library for more information).

The code fragment in Figure 1 shows an example implementation of the DebugControl interface.

Figure 1. Definitions of the DebugControl and Plugin interfaces
public interface DebugControl
{
    // called before an application object method or program main is invoked
    public void startDebug(java.lang.String className,java.lang.String methodName);

    // called after an application object method or program main is invoked
    public void stopDebug(java.lang.String className,java.lang.String methodName);

    // called before an application object is deleted
    public void exitDebug();

}
public interface Plugin
{
    // initaliser, called when plugin is registered
    public void init();
}

The code fragment in Figure 2 shows an example implementation of the DebugControl and Plugin interfaces.

Figure 2. Sample implementation of the DebugControl and Plugin interfaces
import com.ibm.cics.server.debug.*;

public class SampleCICSDebugPlugin 
    implements Plugin, DebugControl
{ 
    // Implementation of the plugin initialiser
    public void init()
    {
        // This method is called when the CICS Java middleware loads and
        // registers the plugin. It can be used to perform any initialisation
        // required for the debug control implementation.
    }

    // Implementations of the debug control methods
    public void startDebug(java.lang.String className,java.lang.String methodName)
    { 
        // This method is called immediately before the application method is
        // invoked. It can be used to start operation of a debugging tool. JCICS
        // calls such as Task.getTask can be used here to obtain further 
        // information about the application.
    }

    public void stopDebug(java.lang.String className,java.lang.String methodName)
    { 
        // This method is called immediately after the application method is
        // invoked. It can be used to suspend operation of a debugging tool.
    }

    public void exitDebug()
    {
        // This method is called immediately before an application object is
        // deleted. It can be used to terminate operation of a debugging tool.
    }
}
In order to activate a debug plugin implementation you need to set one or more of the following system properties in the JVM properties file for the JVM: Note that more than one plugin interface may be triggered when a Java application is run. For example, if plugin implementations are registered for all three interfaces, and an enterprise bean method is run, the JCICS wrapper, CORBA and EJB plugins will be triggered in succession.

The CICS® System Definition Guide tells you about the system properties available for JVMs. Setting up JVM profiles and JVM properties files tells you how to customize them.