The sample classes com.ibm.cics.samples.SJMergedStream and com.ibm.cics.samples.SJTaskStream

For Java™ application threads that can make CICS® requests, you can intercept the output from the JVM and write it to a transient data queue. A log is created that correlates JVM activity with CICS activity.

You can add time stamps, task and transaction identifiers, and program names when the output is intercepted. You can therefore create a merged log file that contains the output from multiple JVMs. You can use this log file to correlate JVM activity with CICS activity. The sample class, com.ibm.cics.samples.SJMergedStream, is set up to create merged log files.

The com.ibm.cics.samples.SJMergedStream class directs output from the JVM to the transient data queues CSJO (for the stdout stream), and CSJE (for the stderr stream and internal messages). These transient data queues are supplied in group DFHDCTG, and they are redirected to CSSL, but you can redefine them if required.

By redirecting the output, the class adds a header to each record that contains the date, time, APPLID, 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.

The classes are shipped in the file com.ibm.cics.samples.jar, which is in the directory /usr/lpp/cicsts/cicsts55/lib, where /usr/lpp/cicsts/cicsts55 is the installation directory for CICS files on z/OS® UNIX. 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 classes are packaged as an OSGi bundle JAR. These classes can either be deployed into a CLASSPATH JVM server or as a middleware bundle that uses the OSGI_BUNDLES JVM server option in an OSGi JVM server. For more information, see Writing Java classes to redirect JVM stdout and stderr output.

Java applications that run on threads other than the ones that are attached by CICS are not able to make CICS requests. The output from the JVM cannot be redirected by using CICS facilities. The com.ibm.cics.samples.SJMergedStream class still intercepts the output and adds a header to each record. The output is written to the z/OS UNIX files /work_dir/applid/stdout/CSJO and /work_dir/applid/stderr/CSJE as referred to previously. If these files are unavailable, the output is written to the z/OS UNIX 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 z/OS UNIX files. You can also add time stamps and headers, to provide output streams that are specific to a single task. The sample class that is supplied with CICS, com.ibm.cics.samples.SJTaskStream is set up for this purpose. The class directs the output for each task to two z/OS UNIX files. One is for the stdout stream and one is for the stderr stream. The output entries within the streams are uniquely named by using a task number (in the format YYYYMMDD.task.tasknumber). The z/OS UNIX files are stored in directories called STDOUT and STDERR respectively. The process is the same for Java applications which run on threads that are attached by CICS, and Java applications that are running on other threads.

Error handling

The length of messages that are given by the JVM can vary. The maximum record length for the CSSL queue (133 bytes) might not be sufficient to contain some of the messages you receive. If you receive more messages than the maximum record length for the queue, the sample output redirection class issues an error message. The text of the message might be affected.

If you find that you are receiving messages longer than 133 bytes from the JVM, 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 to view the output. For information about how to define transient data queues, see TDQUEUE resources. 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 z/OS UNIX files /work_dir/applid/stdout/CSJO and /work_dir/applid/stderr/CSJE, where work_dir is the directory that is specified on the WORK_DIR option in the JVM profile, and applid is the APPLID identifier that is associated with the CICS region. If these files are unavailable, the output is written to the z/OS UNIX files named by the STDOUT and STDERR options in the JVM profile.

When an error is encountered by the sample output redirection classes, one or more error messages are given. If the error occurred while you processed an output message, then the error messages are directed to System.err, and are eligible for redirection. However, if the error occurred while you processed an error message, then the new error messages are sent to the file named by the STDERR option in the JVM profile, avoiding a recursive loop in the Java class. The classes do not return exceptions to the calling Java program.