Using DFHJVMAT to modify options in a JVM profile

DFHJVMAT is a user-replaceable program that you can use to override the options specified in a JVM profile.

"How CICS® creates JVMs" in Java™ Applications in CICS explains how applications request a JVM, how CICS locates the JVM profile, and how CICS uses the JVM profile to create a JVM. Normally, a JVM profile provides sufficient flexibility to configure a JVM as required. "Setting up JVM profiles and JVM properties files" in Java Applications in CICS tells you how to configure a JVM using a JVM profile. You should consider using DFHJVMAT only if you need to tailor the JVM in a way that cannot be achieved by specifying options in the JVM profile.

You can also use DFHJVMAT to override the JVMCLASS attribute on the CICS PROGRAM resource definition. This attribute specifies the main class in the Java program that is to execute in the JVM. If you use the PROGRAM resource definition, the limit for the JVMCLASS attribute is 255 characters, but you can use DFHJVMAT to specify a class name longer than 255 characters.

You can call DFHJVMAT by specifying INVOKE_DFHJVMAT=YES as an option on the JVM profile that you want to override.

Important

You can only call DFHJVMAT for a single-use JVM, that is, a JVM with a JVM profile that specifies the option REUSE=NO or the older option Xresettable=NO (for example, the supplied sample JVM profile DFHJVMPS). With single-use JVMs, when the task using the JVM terminates, CICS does not attempt to make the JVM available for reuse for another task.

You cannot call DFHJVMAT for a resettable JVM or a continuous JVM, that is, JVMs with JVM profiles that specify REUSE=RESET, REUSE=YES or the older option Xresettable=YES (for example, the default CICS-supplied JVM profile, DFHJVMPR). If you specify INVOKE_DFHJVMAT=YES for one of these types of JVM, then INVOKE_DFHJVMAT=YES is ignored and DFHJVMAT is not called.

The values specified in the JVM profile are available to DFHJVMAT as C/C++ environment variables, which you can modify before the JVM is created.

Note:
The values of the STDERR and STDOUT parameters, which can be interpreted by CICS to generate task-specific names, are passed to DFHJVMAT before interpretation.

DFHJVMAT uses the C/C++ getenv and setenv functions to change the environment variables that correspond to the options in the JVM profile. For example, you could use the following command to replace the CLASSPATH environment variable with the specified value:

setenv(eclasspath, classpathval,1)

where:

char *eclasspath = "CLASSPATH";
char *classpathval ="/usr/lpp/java130s/J1.3/bin   ->
:/usr/lpp/java130s/J1.3/bin/classic:/u/jtilli1/Java/test:.";
Note:
The "right arrow" character (->) indicates that the line of code continues in the following line of text. (It has not been possible to print the whole line of code on the same line of text.)

Note that the setenv function has no effect on the CICS PROGRAM definition and remains in effect only for the lifetime of the JVM.

The CICS-supplied DFHJVMAT:

If you write your own program to tailor options in the JVM profile based on the supplied version, the name must be DFHJVMAT, and the program must be written in C. You can use EXEC CICS commands within DFHJVMAT but you should be aware that this might incur a processing overhead. Note that DFHJVMAT must be written to threadsafe standards and defined with CONCURRENCY(THREADSAFE) in its program resource definition, because multiple invocations of this module might run in parallel.

Options in the JVM profile that are available to DFHJVMAT

The options are read from the specified JVM profile and created as environment variables using Language Environment® services.The JVM profile options listed in Table 33 below are made available to DFHJVMAT. The full descriptions of these options are in the CICS System Definition Guide. Before modifying any of these options using DFHJVMAT, you should read the full description of the option.

Notes:
  1. Except where explicitly stated as being for information only, you can reset the values of these variables.
  2. All environment variables and values are case sensitive, and should be set as shown.
  3. CICS ignores any values that it does not recognise as a valid option.
Table 33. JVM profile options available to DFHJVMAT
Option Specifies
CICS_DIRECTORY Path to CICS-supplied JAR files
CLASSPATH Standard class path for non-shareable application classes
INVOKE_DFHJVMAT For information only
JAVA_HOME Path to IBM® Developer Kit for OS/390®, Java 2 Technology Edition subdirectories and JAR files
JVMPROPS Path and name of the JVM properties file
LIBPATH Path to JVM system classes and native C DLL files loaded by the JVM
STDERR Name of HFS file for stderr output from the JVM
STDIN Name of HFS file for stdin
STDOUT Name of HFS file for stdout output from the JVM
TMPREFIX, TMSUFFIX Paths to be added at start and end of trusted middleware class path
USEROUTPUTCLASS Name of a Java class that intercepts and redirects the stdout and stderr output from the JVM.
VERBOSE Level of information messages from the JVM
WORK_DIR HFS directory to contain stdin, stdout and stderr files
X Display information about non-standard options
Xcheck Perform additional checks
Xdebug Enable debugging support
Xinitsh Initial system heap size
Xmaxe, Xmaxf, Xmine, Xminf Maximum and minimum heap expansion sizes and free heap percentage sizes for the middleware heap
Xms Initial size of the middleware heap
Xmx Maximum total size of the middleware and transient heaps
Xnoagent Disable the old sun.tools.debug agent (if Xdebug specified)
Xnoclassgc Disable class garbage collection
Xoss Maximum Java stack size for any thread
Xresettable For information only
Xrs Reduces the use of operating system signals by the JVM
Xrundllname Loads the specified dynamic link library (DLL) and passes it the specified options
Xss Size of stack for each new Java thread
Xverify Level of verification to perform on classes loaded

Two additional fields not found in a standard JVM profile are passed to DFHJVMAT, as follows:

CICS_PROGRAM
Specifies the name of the CICS program (1-8 characters) associated with the Java class to be run. This name is established at run-time; it is passed to DFHJVMAT for information only and cannot be changed. Any changes are ignored by CICS.
CICS_PROGRAM_CLASS
Specifies the CICS user application class name, and is obtained from the program resource definition. This is defined by the JVMCLASS attribute on the CICS PROGRAM resource definition. As an alternative to using DFHJVMAT to override this attribute, you can use EXEC CICS SET PROGRAM or CEMT SET PROGRAM commands to modify the JVMCLASS attribute on the PROGRAM resource definition before control is passed to the JVM. If you use the PROGRAM resource definition, the limit for the JVMCLASS attribute is 255 characters, but you can use DFHJVMAT to specify a class name longer than 255 characters.

Related tasks
Setting up JVM profiles and JVM properties files
Redirecting JVM output
Writing Java classes to redirect JVM stdout and stderr output
Using DFHJVMRO to modify the Language Environment enclave for a JVM
Rewriting user-replaceable programs
Assembling and link-editing user-replaceable programs

Related concepts
How CICS creates JVMs
Removal of support for CICS Transaction Server for OS/390, Version 1 Release 3 JVMs

Related reference
Defining the JVM options (JVM profiles and JVM properties files)
[[ Contents Previous Page | Next Page Index ]]