The CICS-supplied sample classes com.ibm.cics.samples.SJMergedStream and com.ibm.cics.samples.SJTaskStream

For Java applications executing on the initial process thread (IPT), which are able to make CICS requests, the intercepted output from the JVM can be written to a transient data queue, and you can add time stamps, task and transaction identifiers, and program names. This enables you to create a merged log file containing the output from multiple JVMs. You can use this log file to correlate JVM activity with CICS activity. The CICS-supplied sample class, com.ibm.cics.samples.SJMergedStream, is set up to create merged log files like this.

The com.ibm.cics.samples.SJMergedStream class directs output from the JVM to the transient data queues CSJO (for stdout output), and CSJE (for stderr output, internal messages, and unresettable event logging). These transient data queues are supplied in group DFHDCTG, and they are indirected to CSSL, but they can be redefined if necessary. In particular, note that the length of messages issued by the JVM can vary, and the maximum record length for the CSSL queue (133 bytes) might not be sufficient to contain some of the messages you receive. If this happens, the sample output redirection class issues an error message, and the text of the message might be affected. If you find that you are receiving messages longer than 133 bytes from the JVM, you should redefine CSJO and CSJE as separate transient data queues. Make them extrapartition destinations, and increase the record length for the queue. You can allocate the queue to a physical data set or to a system output data set. You might find a system output data set more convenient in this case, because you do not then need to close the queue in order to view the output. The CICS® Resource Definition Guide tells you how to define transient data queues. If you redefine CSJO and CSJE, ensure that they are installed as soon as possible during a cold start, in the same way as for transient data queues that are defined in group DFHDCTG.

If the transient data queues CSJO and CSJE cannot be accessed, output is written to the HFS files /work_dir/applid/stdout/CSJO and /work_dir/applid/stderr/CSJE, where work_dir is the directory specified on the WORK_DIR option in the JVM profile, and applid is the applid identifier associated with the CICS region. If these files are unavailable, the output is written to the HFS files named by the STDOUT and STDERR options in the JVM profile.

As well as redirecting the output, the class adds a header to each record containing applid, date, time, transid, task number and program name. The result is two merged log files for JVM output and for error messages, in which the source of the output and messages can easily be identified.

For Java applications executing on threads other than the initial process thread (IPT), which are not able to make CICS requests, the output from the JVM cannot be redirected using CICS facilities. The com.ibm.cics.samples.SJMergedStream class still intercepts the output and adds a header to each record containing applid, date, time, transid, task number and program name. The output is then written to the HFS files /work_dir/applid/stdout/CSJO and /work_dir/applid/stderr/CSJE as described above, or if these files are unavailable, to the HFS files named by the STDOUT and STDERR options in the JVM profile.

As an alternative to creating merged log files for your JVM output, you can direct the output from a single task to HFS files, and add time stamps and headers, to provide output streams that are specific to a single task. The CICS-supplied sample class, com.ibm.cics.samples.SJTaskStream is set up to do this. The class directs the output for each task to two HFS files, one for stdout output and one for stderr output, that are uniquely named using a task number (in the format Task.tasknumber). The HFS files are stored in the directory /work_dir/applid/stdout for stdout output, or /work_dir/applid/stderr for stderr output, where work_dir is is the directory specified on the WORK_DIR option in the JVM profile, and applid is the applid identifier associated with the CICS region. The process is the same for both Java applications executing on the IPT, and Java applications that are executing on other threads.

When an error is encountered by the CICS-supplied sample output redirection classes, one or more error messages are issued reporting this. If the error occurred while processing an output message, then the error messages are directed to System.err, and as such are eligible for redirection. However, if the error occurred while processing an error message, then the new error messages are sent to the file named by the STDERR option in the JVM Profile. This is done to avoid a recursive loop in the Java class. The classes do not return exceptions to the calling Java program.

The classes are shipped as a middleware class file dfjoutput.jar, which is in the directory /usr/lpp/cicsts/cicsts31/lib, where cicsts31 is a user-defined value that you chose for the CICS_DIRECTORY variable used by the DFHIJVMJ job during CICS installation. The source for the classes is also provided as samples, so you can modify the classes as you want, or write your own classes based on the samples. The CICS Customization Guide tells you how to customize these classes, or write your own classes based on the samples.