Controlling the location for JVM output, logs, dumps and trace

Output from Java™ applications that are running in a JVM server can be written to the z/OS® UNIX files. The z/OS UNIX files are named by the STDOUT, STDERR, JVMLOG, and JVMTRACE options in the JVM profile or routed to the JES log. In a Liberty JVM server, Liberty server output can be found in messages.log relative to the configured log directory.

Logs and Traces

By default, the output from Java applications that are running in a JVM server is written to the z/OS UNIX file system. The z/OS UNIX file system follows the file name convention DATE.TIME.<dfhjvmxxx> within the directory structure of $WORK_DIR/APPLID/JVMSERVER. Additional overrides can be used to route the output to the JES log. For more information, see Using a DD statement to route JVM server output to JES.

If you want to override the defaults, you can specify a zFS file name for the STDOUT, STDERR, JVMLOG, and JVMTRACE options. However, if you use a fixed file name, the output from all the JVMs that were created with that JVM profile is appended to the same file. The output from different JVMs is interleaved with no record headers. This situation is not helpful for problem determination.

If you customize these values, a better choice is to specify a variable file name for the STDOUT, STDERR, JVMLOG, and JVMTRACE options. The files can then be made unique to each individual JVM during the lifetime of the CICS® region.

You can include the CICS region APPLID in the file name by using the APPLID symbol.

You can also include extra identifying information in file names. Other identifying information includes the DATE and TIME symbols.
  • DATE is replaced by the date the profile parses on JVM server start, in the form Dyymmdd.
  • TIME is replaced by the time the profile parses on JVM server start, in the format Thhmmss.
  • JVMSERVER is replaced by the name of the JVMSERVER resource.

Further customization can be achieved at the programmatic level that uses the USEROUTPUTCLASS option, which does not work with Liberty. The USEROUTPUTCLASS option, which is specified in the JVM profile, names a Java class. A Java class intercepts and redirects the output from the JVM to a custom location such as a CICS transient data queue. You can add time stamps and headers to the output records, and identify the output from individual transactions that are running in the JVM. CICS supplies sample classes that perform these tasks.

Dumps

The location for the javacore (also known as a Java dump), heap and snaptrace outputs from the JVM is the working directory on z/OS UNIX named by the JVMSERVER's WORK_DIR option in the JVM profile. These files are uniquely identified by a time stamp in their names. To override the default locations and names, you can use -Xdump:directory=<path> to specify a location for all dump types to be written to, and -Xdump:file=<filename> to specify the dump file names. For details about -Xdump, see -Xdump.

The more detailed Java system dumps are written to the data set named by the JAVA_DUMP_TDUMP_PATTERN option. You can use the APPLID, DATE, and TIME, and JVMSERVER symbols in this value to make the name unique to the individual JVM, as shown in the sample JVM profiles included with CICS. You can also use MVS symbols as supported by the IEATDUMP macro or dump agent tokens as supported by the JRE. For details about dump agent tokens see -Xdump and for details about MVS system symbols see What are system symbols?. You should ensure that the generated data set names are valid and can be allocated by the CICS region user ID otherwise first failure diagnostic information may be lost in the event of a system error.
Note: The terms system dump and TDUMP are occasionally used interchangeably. For clarification, TDUMP is a type of MVS system dump generated via IEATDUMP, producing an MVS transaction dump. Care should be taken to avoid confusing such MVS transaction dumps with CICS transaction dumps.

The JVM writes information to the stderr stream when it generates a javacore output or a system dump. For more information about the contents of javacore outputs and system dump files, see Troubleshooting and support.