Writing Java classes to redirect JVM stdout and stderr output

Use the USEROUTPUTCLASS option in a JVM profile to name a Java™ class that intercepts the stdout stream and stderr stream from the JVM. You can update this class to specify your choice of time stamps and record headers, and to redirect the output.

CICS® supplies sample Java classes, com.ibm.cics.samples.SJMergedStream and com.ibm.cics.samples.SJTaskStream, that you can use for this purpose. Sample source is provided for both these classes in the directory /usr/lpp/cicsts/cicsts56/samples/com.ibm.cics.samples. The /usr/lpp/cicsts/cicsts56 directory is the installation directory for CICS files on z/OS® UNIX. This directory is specified by the USSDIR parameter in the DFHISTAR installation job. The sample classes are also shipped as a class file, com.ibm.cics.samples.jar, which is in the directory /usr/lpp/cicsts/cicsts56/lib. You can modify these classes, or write your own classes based on the samples.

Controlling the location for JVM output, logs, dumps and trace has information about:
  • The types of output from JVMs that are and are not intercepted by the class that is named by the USEROUTPUTCLASS option. The class that you use must be able to deal with all the types of output that it might intercept.
  • The behavior of the supplied sample classes. The com.ibm.cics.samples.SJMergedStream class creates two merged log files for JVM output and for error messages, with a header on each record that contains applid, date, time, transaction ID, task number, and program name. The log files are created by using transient data queues, if they are available; or z/OS UNIX files, if the transient data queues are not available, or cannot be used by the Java application. The com.ibm.cics.samples.SJTaskStream class directs the output from a single task to z/OS UNIX files, adding time stamps and headers, to provide output streams that are specific to a single task.
For a JVM server to use an output redirection class, you must create an OSGi bundle that contains your output redirection class. You must ensure that the bundle activator registers an instance of your class as a service in the framework and sets the property com.ibm.cics.server.outputredirectionplugin.name=class_name. You can use the constant com.ibm.cics.server.Constants.CICS_USER_OUTPUT_CLASSNAME_PROPERTY to get the property name. The following code excerpt shows how you might register your service in the bundle activator: 
Properties serviceProperties = new Properties();
    serviceProperties.put(Constants.CICS_USER_OUTPUT_CLASSNAME_PROPERTY, MyOwnStreamPlugin.class.getName());
    context.registerService(OutputRedirectionPlugin.class.getName(), new MyOwnStreamPlugin(), serviceProperties);
You can either add the OSGi bundle to the OSGI_BUNDLES option in the JVM profile, or ensure that the bundle is installed in the framework when the first task is run. Whichever method you use, you must still specify the class in the USEROUTPUTCLASS option.
If you decide to write your own classes, you need to know about:
  • The OutputRedirectionPlugin interface
  • Possible destinations for output
  • Handling output redirection errors and internal errors