The CICS JVM plug-in mechanism

In addition to the standard JPDA debug interfaces in the JVM, CICS® provides a set of interception points (plug-ins) in the CICS Java™ middleware, which can be useful for debugging applications. You can use these plug-ins 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 plug-ins. The plug-ins 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 plug-ins 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 plug-in that provides methods that are called immediately before and after a Java program is invoked.

To deploy a plug-in, you package the plug-in 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.

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 plug-in 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 plug-in 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 plug-in initialiser
    public void init()
    {
        // This method is called when the CICS Java middleware loads and
        // registers the plug-in. 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)
    {
    }
}