The SJ domain uses trace levels 29-32 to control Java™ Virtual Machine (JVM) trace. These correspond to the CICS options for JVM Level 0 trace, JVM Level 1 trace, JVM Level 2 trace, and JVM User trace. The CICS default settings for these trace options map to trace point levels 0, 1, and 2 for JVMs, and also provide a user-definable trace level which can be used to specify deeper levels of tracing or complex trace options. The JVM trace options are defined using a "free-form" 240-character field. Note that JVM trace can produce a large amount of output, so you should normally activate JVM trace for special transactions, rather than turning it on globally for all transactions.
"Controlling tracing for JVMs" in Java Applications in CICS® tells you about the different ways to activate JVM tracing and change the JVM trace options. To summarize, you can control JVM trace using:
The first two methods, using CETR and using the CICS system initialization parameters, are most similar to the methods that you would use to define tracing for other components.
When you set trace levels 29-32 for the SJ component and activate JVM trace, each JVM trace point that is generated appears as an instance of CICS trace point SJ 4D01. If the JVM trace facility fails, CICS issues the trace point SJ 4D00.
The IBM® Developer Kit and Runtime Environment, Java 2 Technology Edition, Version 1.4.2 Diagnostics Guide, SC34-6358, which is available to download from www.ibm.com/developerworks/java/jdk/diagnosis/, has more detailed information about JVM trace and about problem determination for JVMs. This topic summarizes the information from that document which is most significant for tracing JVMs in CICS. The topic gives information about the JVM trace options that you can set using the JVM Level 0 trace, JVM Level 1 trace, JVM Level 2 trace, and JVM User trace options, and the ibm.dg.trc.external system property.
In addition to the JVM trace options, the standard trace points for the SJ (JVM) domain, at CICS trace levels 0, 1 and 2, can be used to trace the actions that CICS takes in setting up and managing JVMs and the shared class cache. These trace points can be activated using the CETR Component Trace screens, as described in Selecting tracing by component. The SJ domain includes a level 2 trace point SJ 0224, which shows you a history of the programs that have used each JVM. "JVM domain trace points" in CICS Trace Entries has details of all the standard trace points in the SJ domain.
When you set trace options for a JVM using the ibm.dg.trc.external system property in the JVM properties file, those options are present, and activated, throughout the JVM's lifetime, unless they are overridden by a subsequent instruction. That system property should therefore be used with caution, because the amounts of output produced in this way can be very large.
When you activate trace options for a transaction in a JVM using CETR, the SPCTRSJ and STNTRSJ system initialization parameters, or the EXEC CICS SET TRACETYPE command, CICS uses the JVM's JVMRI (formerly known as JVMRAS) interface to pass the trace options to the JVM at the point when the transaction begins to use the JVM. CICS concatenates the trace options that you have specified using the JVM Level 0 trace, JVM Level 1 trace, JVM Level 2 trace, and JVM User trace options, and prefixes the concatenated option string with EXTERNAL=. The CICS level 2 trace point SJ 052E shows the option string that has been passed to the JVM. This instruction applies the trace options in the JVM as if they had been specified by the ibm.dg.trc.external system property for the JVM, but it applies them only for the duration of the transaction's use of the JVM. The amount of output produced by this method can still be large, but is not so large as the output produced when you set the ibm.dg.trc.external system property directly.
You can select the JVM trace points that you require by using the ibm.dg.trc.external system property, the "free-form" 240-character fields in CETR, or the JVMxxxxTRACE system initialization parameters, to specify some or all of the following parameters:
The format that you can use to specify these parameters is the same whether you use the ibm.dg.trc.external system property directly, or whether you use one of the methods available in the CICS interface. This topic explains what these parameters are, and gives some examples of how to specify them.
The JVM trace points are classified into levels 0 through 9, based on the importance of the trace point. A level 0 trace point is very important, and this classification is reserved for extraordinary events and errors. A level 9 trace point provides in-depth component detail.
You can specify a given level of tracing by using the level0 through level9 keywords (which can be abbreviated to l0 through l9, or in CICS, can be specified in upper case). Note that enabling a JVM trace point level enables that level and all levels above it. For example, if level 5 is selected, all trace points that have levels 0 through 5 are included. If no trace point level is specified, the default is level 9, meaning that all levels of trace points are provided.
The default JVM trace options that are provided in CICS use the JVM trace point level specifications. The options for JVM Level 0 trace, JVM Level 1 trace, and JVM Level 2 trace specify LEVEL0, LEVEL1, and LEVEL2 respectively, so they map to the Level 0, Level 1 and Level 2 trace point levels for JVMs. It is suggested that you keep these level specifications, but if you find that another JVM trace point level is more useful for your purposes than one of the default levels, you could change the level specification to map to your preferred JVM trace point level (for example, you could specify LEVEL5 instead of LEVEL2 for the JVMLEVEL2TRACE option). Note that enabling a JVM trace point level enables that level and all levels above it, so for example, if you activate JVM Level 1 trace for a particular transaction, you receive Level 0 trace points for that transaction as well. This means that if you are using only the level specifications as your JVM trace options, you only need to activate the deepest level of tracing that you require, and the other levels are activated as well.
When the JVM trace point level specifications are used on their own, the default of ALL is assumed for the other parameters, so all trace points are enabled at the levels you have selected. You can add to the basic level specifications if you want to include or exclude particular components or trace point types at the selected trace levels. If you modify the basic level specifications in this way, remember that you might need to activate more than one of the JVMLEVEL0TRACE, JVMLEVEL1TRACE, and JVMLEVEL2TRACE options to obtain all the trace points you require. If you want to create more complex specifications for JVM tracing which use multiple trace point levels, or if you do not want to use trace point levels at all in your specification, use the JVMUSERTRACE option to create your option string.
The rest of this topic explains how to identify components, trace point types and trace point IDs, and then gives examples of how to use those parameters and the trace point levels to create customized trace option specifications.
A component, for the purposes of JVM tracing, is either a JVM sub-component or a pre-defined group of trace points.
JVM sub-components are functional areas, like the CICS domains. They are identified by alphabetic codes; for example, cl is classes, dc is data conversion, lk is locking, and st is storage. The chapter on tracing Java applications and the JVM in the IBM Developer Kit and Runtime Environment, Java 2 Technology Edition, Version 1.4.2 Diagnostics Guide, SC34-6358, has the full list of sub-components and explains the meaning of the most important of them. The list of sub-components is subject to change, so you should check the Diagnostics Guide for the latest information, but a recent list is as follows: ci, cl, dc, dg, lk, st, xe, xm, hpi, java, awt, awt_dnd_datatransfer, Audio, jit, jdwp, mt, fontmanager, net, awt_java2d, awt_print, core, nio.
Alternatively, a component can be a pre-defined group of trace points. They are also identified by alphabetic codes; for example, st_dump identifies the group of trace points in the storage sub-component that relate to dumps, and nativeMethods identifies the group of trace points that relate to native methods. The available groups are listed in the chapter on tracing Java applications and the JVM in the IBM Developer Kit and Runtime Environment, Java 2 Technology Edition, Version 1.4.2 Diagnostics Guide, SC34-6358. The groups are subject to change, so you should check the Diagnostics Guide for the latest information, but a recent list is as follows: checkedjni, compiledMethods, jitCl, jitCompCtrl, jitEh, jitError, jitInit, jitSt, jni, jvmmi, nativeMethods, st_alloc, st_backtrace, st_calloc, st_compact, st_compact_dump, st_compact_verbose, st_concurrent, st_concurrent_pck, st_concurrent_shadow_heap, st_dump, st_freelist, st_icompact, st_loaAdjustTargetSize, st_mark, st_parallel, st_refs, st_terse, st_trace, st_verbosegc, st_verify, st_verify_heap, staticMethods, threadSR, wrappedjni.
The JVM trace points are classified into the following types, which are identified by name:
You can specify a trace point type within a particular component, or you can specify a type to be shown for all components (by using the ALL option instead of a component name).
Each JVM trace point has a numeric ID, which can be specified as part of a trace option string, using the tpid keyword, in order to select or exclude individual trace points. Note that trace point level specifications do not apply to trace points that are explicitly specified by their trace point ID. This means that you can add trace point IDs that are classified at any level to any of the JVM trace options in CICS, and they will be supplied when the option is activated, regardless of the trace point levels that are enabled by that trace option.
The TraceFormat.dat file, supplied with the IBM Software Developer Kit for z/OS, Java 2 Technology Edition, Version 1.4.2, shows the level (0-9), type, ID and name of each JVM trace point, the JVM sub-component with which it is associated, and the template containing the description of the trace point. Note that this file is subject to change without notice; a version number is included as the first line of the file, and this will be updated if the file is changed. By default, this file is in the library /usr/lpp/java142/J1.4/lib/, where /java142/J1.4/ is the directory that is defined when you install IBM Software Developer Kit for z/OS, Java 2 Technology Edition, Version 1.4.2. You can use this file to identify an individual JVM trace point.
The format for specifying the component, type and trace point ID in an option string (using either the ibm.dg.trc.external system property or one of the methods available in the CICS interface) is as follows:
[!]component[(type[,...])]
[!]tpid(tracepoint_id[,...])
The rules for specifying these parameters are:
The following examples show how you might combine these parameters:
ALL,!DC,!LK All trace points except those in the DC and LK components
CL(ENTRY,EXIT) All entry and exit trace points in the CL component
ST,!TPID(4001,4002) All trace points in the ST component except 4001 and 4002
ALL(ENTRY,EXIT) All entry and exit trace points (in all components)
A JVM trace point level can be used on its own, which is the case for the default level specifications in CICS. In this case, the default of ALL is assumed for the other parameters, so all trace points at and above that level are enabled. Alternatively, a trace point level can be applied to all or part of your trace point selection, or to an individual component. It does not apply to trace points that are explicitly specified by their trace point ID. You can use more than one trace point level in an option string. For any complex option string, you should use the JVMUSERTRACE option in CICS. The JVMLEVEL0TRACE, JVMLEVEL1TRACE, and JVMLEVEL2TRACE options should each be used for a single trace point level.
You can add components to the default level specifications in CICS if you want to limit JVM tracing to particular components. For example, you could add components to the default JVMLEVEL1TRACE option to specify the following option string:
LEVEL1,ST,CL
This option string enables trace points that have a level of 0 or 1 for the ST and CL components only. You can also exclude a component by using the logical not (!). For example:
LEVEL1,ALL,!LK
enables trace points that have a level of 0 or 1 for all components except the LK component. You can include trace point types in your option string as well as components. For example:
LEVEL1,ALL(ENTRY,EXIT)
enables, in all components, entry and exit trace points that are classified as level 0 or 1.
You can also create complex option strings that use more than one trace point level. When the keyword for a trace point level is used before a trace point selection, that keyword applies to all trace point selection criteria that follow it in the option string. For example, the following option string:
LEVEL5,ST,LK,CL,LEVEL1,ALL
(which can be abbreviated to)
L5,ST,LK,CL,L1,ALL
enables trace points that have a level of 0 through 5 for the ST, LK, and CL components and that have a level of 0 or 1 for all other components.
When the keyword for a trace point level is used in brackets after an individual component, it applies only to the component for which it is specified. For example:
ST(L5),LK(L5),CL(L5),ALL(L1)
enables the same levels of trace points as the previous example.
If you use the logical not operator (!) with a component name when you specify a trace point level in brackets, the result is that the level is inverted, and all trace points deeper than the specified level are excluded. For example, specifying
!ST(L5)
disables all trace points at levels 6, 7, 8 and 9 for the ST component.
JVM trace appears as CICS trace points in the JVM domain. When you activate JVM trace, each JVM trace point that is generated appears as an instance of CICS trace point SJ 4D01. The following example shows how a JVM trace point appears in CICS trace that has been formatted using the FULL option:
SJ 4D01 JVM EVENT - TPID_00C094 ThreadID(P,49B8B2A8) "main" "com/ibm/cics/server/Wrapper"
TASK-00096 KE_NUM-0012 TCB-J8003/008B5068 RET-A0BE9086 TIME-16:20
1-0000 49B8B2A8 D70000C0 94FFFF00 6D61696E 00636F6D 2F69626D 2F636963 732F7365
The information in the trace data is interpreted as follows: