The CICS JVM plugin mechanism

In addition to the standard JPDA debug interfaces in the JVM, CICS® provides a set of interception points (plugins) in the CICS Java™ middleware, which can be useful for debugging applications. You can use these plugins to insert additional Java programs immediately before and after the application Java code is run.

Information about the application, for example, class name and method name, is made available to the plugins. The plugins can also use the JCICS API to obtain information about the application, and can also be used in conjunction with the standard JPDA interfaces to provide additional debug facilities specifically for CICS. The plugins can also be used for purposes other than debugging, in a similar way to CICS user exits.

The Java exit is a CICS Java wrapper plugin that provides methods that are called immediately before and after a Java program is invoked.

To deploy a plugin, you package the plugin as an OSGi bundle. For more information see Deploying OSGi bundles in a JVM server.

Two Java programming interfaces are provided.

Both interfaces are supplied in com.ibm.cics.server.jar, and are documented in the Javadoc. For more information see The Java class library for CICS (JCICS).

The Java programming interfaces are:

• DebugControl: com.ibm.cics.server.debug.DebugControl. This programming interface defines the method calls that can be made to an implementation supplied by the user.
• Plugin: com.ibm.cics.server.debug.Plugin. This is a general purpose programming interface that you use for registering the plugin implementation.

Here is an example of the DebugControl interface:

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();
}

Here is an example 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 initialization
        // 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.
    }

    public static void main(com.ibm.cics.server.CommAreaHolder ca)
    {
    }
}