PQ69792: CHANGE JVM_LOGFILE USAGE

APAR status
Closed as documentation error.

Error description
Change/clarify documentation on the usage of JVM_LOGFILE as it
only works with JVM_DEBUG=1 and not JVM_ENABLE_VERBOSE_GC=1.
JVM_DEBUG=1 setting only puts out JNI and class debug messages
redirected to this logfile and not Garbage Collection (GC)
output.
Local fix
If you need Garbage Collection (GC) output in an output file,
you will need to use IBM_JVM_ST_VERBOSEGC_LOG along with
JVM_ENABLE_VERBOSE_GC=1 set in the server's current.env.

Note: Recommend NOT to use the same filename for both
JVM_LOGFILE and IBM_JVM_ST_VERBOSEGC_LOG as one will overwrite
the other.
Problem summary
****************************************************************
* USERS AFFECTED: All users of WebSphere Application Server    *
*                 V4.0.1 for z/OS and OS/390                   *
****************************************************************
* PROBLEM DESCRIPTION: Text in the WebSphere for z/OS books    *
*                      Installation and Customization, and     *
*                      Assembling J2EE Applications, needs to  *
*                      be updated to clarify the type of       *
*                      output collected in the file specified  *
*                      by the environment variable             *
*                      JVM_LOGFILE. This file does not         *
*                      contain garbage-collection output.      *
****************************************************************
* RECOMMENDATION:                                              *
****************************************************************
WebSphere for z/OS Installation and Customization, and
Assembling J2EE Applications, both contain a description of
the environment variable JVM_LOGFILE.  This description needs
to clearly state that, if specified, this file will contain
only JNI and class debug messages, not garbage-collection
output.
Problem conclusion
APAR PQ69792 requires changes to documentation.

To access the latest online documentation, go to the product
library page at:

www.ibm.com/software/webservers/appserv/zos_os390/

WebSphere Application Server V4.0.1 for z/OS and OS/390
Installation and Customization (GA22-7834-06)
will be changed as follows:

"Appendix A. Environment and JVM properties files"
Topic "Environment variable use"
"Table 49. Where to use environment variables" on page 396
will be updated with the new entry for property
"IBM_JVM_ST_VERBOSEGC_LOG=" which is optional for
the System Management server instance and for
J2EE business application server instances.

"Appendix A. Environment and JVM properties files"
Topic "Environment variable descriptions" on page 404 will be
updated with the following new or changed variable
descriptions:

  IBM_JVM_ST_VERBOSEGC_LOG=filename
    Specifies the HFS file in which garbage-collection output
    will be logged. Use this variable with both of the
    following:
    - JVM_ENABLE_CLASS_GC=1 to enable garbage collection, and
    - JVM_ENABLE_VERBOSE_GC=1 to view verbose output from the
      garbage collection.

    Recommendation: If you also are using the JVM_LOGFILE
    variable to specify an HFS file for JVM-related output,
    do not specify the same HFS file for the
    IBM_JVM_ST_VERBOSEGC_LOG variable. WebSphere for z/OS
    will not append data to an existing file; instead, the
    data will be overwritten if both of these variables
    specify the same HFS file.

  JVM_DEBUG=1
    This option is equivalent to the ?verbose:class,jni Java
    invocation option. It reroutes JNI and class debug messages
    to SYSOUT for debugging purposes. Set JVM_DEBUG=1 to invoke
    JVM messaging.
    Note: Setting this variable does not result in garbage
    collection processing;  to enable garbage collection,
    you must specify JVM_ENABLE_CLASS_GC=1.

  JVM_ENABLE_CLASS_GC=1
    Enables garbage collection of class objects when this
    environment variable is set to the value 1. Without
    this setting, garbage collection is not enabled for
    class objects, so the default behavior is equivalent
    to the -Xnoclassgc Java invocation option.
    If you need garbage-collection output in an output file,
    specify the filename through the IBM_JVM_ST_VERBOSEGC_LOG
    environment variable. Otherwise, garbage-collection output
    appears in SYSOUT for the server region.

  JVM_ENABLE_VERBOSE_GC=1
    Sets verbose garbage collection on or off. The value 1 is
    required for enabling garbage collection messages. This
    option is equivalent to the -verbose:gc Java invocation
    option.
    If you need garbage-collection output in an output file,
    specify the filename through the IBM_JVM_ST_VERBOSEGC_LOG
    environment variable.  Otherwise, garbage-collection output
    appears in SYSOUT for the server region.

  JVM_LOGFILE=filename
    Specifies the HFS file in which JNI and class debug
    messages from the JVM will be logged.

    Recommendations:
    - Use this variable only in a single-server environment.
      If you use JVM_LOGFILE in a multiple-server environment,
      all the servers write to the same file, so you
      might have difficulty using the file for diagnostic
      purposes. In a multiple-server environment, use
      JVM_DEBUG=1 to direct JNI and class debug messages to
      the SYSOUT for a specific server.
    - This logfile does not contain garbage-collection
      output.  If you enable garbage collection by specifying
      JVM_ENABLE_CLASS_GC=1, the output appears in SYSOUT for
      the server region, or in an HFS file you specify through
      the IBM_JVM_ST_VERBOSEGC_LOG environment variable.
      Do not specify the same HFS file for the
      IBM_JVM_ST_VERBOSEGC_LOG variable as you do for the
      JVM_LOGFILE variable. WebSphere for z/OS will not append
      data to an existing file; instead, the data will be
      overwritten if both of these variables specify the same
      HFS file.

WebSphere Application Server V4.0.1 for z/OS and OS/390
Assembling J2EE Applications (SA22-7836-05)
will contain identical changes to the corresponding
table and environment variable descriptions in Appendix A:
- "Table 23. Where to use environment variables" on page 269
- "Environment variable descriptions" on page 275
Temporary fix Comments
APAR information
APAR number PQ69792
Reported component name WASKBASE
Reported component ID 5655A9801
Reported release 401
Status CLOSED DOC
PE NoPE
HIPER NoHIPER
Submitted date 2003-01-13
Closed date 2003-02-27
Last modified date 2003-02-27

APAR is sysrouted FROM one or more of the following:

APAR is sysrouted TO one or more of the following:

Modules/Macros

Fix information

Applicable component levels


Document Information


Product categories: Software > Application Servers > Distributed Application & Web Servers > WebSphere Application Server for z/OS
Operating system(s):
Software version: 401
Software edition:
Reference #: PQ69792
IBM Group: Software Group
Modified date: Feb 27, 2003