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 to create a log 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 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 and internal messages). These transient data queues are supplied in group DFHDCTG, and they are indirected to CSSL, but you can redefine them if required.

As well as redirecting the output, the class adds a header to each record containing 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/cicsts52/lib, where /usr/lpp/cicsts/cicsts52 is the installation directory for CICS files on CICS® 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. You must take special steps to enable these samples in an OSGi environment. For more information, see Writing Java classes to redirect JVM stdout and stderr output.

For Java applications executing on threads other than those attached by CICS, 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. The output is written to the z/OS UNIX files /work_dir/applid/stdout/CSJO and /work_dir/applid/stderr/CSJE as described above, or if these files are unavailable, 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, 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 z/OS UNIX files, one for stdout output and one for stderr output, that are uniquely named using a task number (in the format YYYYMMDD.task.tasknumber). The z/OS UNIX files are stored in the stdout directory for stdout output, or stderr directory for stderr output. The process is the same for both Java applications executing on threads attached by CICS, and Java applications that are executing on other threads.

Error handling

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, 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. 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 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 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 issued. If the error occurred while processing an output message, then the error messages are directed to System.err, and 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 avoids a recursive loop in the Java class. The classes do not return exceptions to the calling Java program.

Note: Output redirection samples function in OSGi and classpath JVM servers and not in Liberty.