Setting up CICS to run Java applications
In this chapter, we describe the necessary tasks to set up the environment for running Java applications in CICS and some of the commands to control your CICS Java setup after it is up and running. We aim the information in this chapter at CICS systems programmers, although it might be useful background information for Java application developers too.
In the first section, we give a brief overview of how to access the z/OS UNIX shell, and then we describe how you can build and run one of the Java application samples that shipped with CICS. This section is useful if you are setting up a Java application in CICS for the first time. You can skip this section if you already have some experience with setting up a Java application in CICS.
In the second section, we provide more detailed information about setting up CICS to run Java applications. We discuss how to configure z/OS, UNIX System Services, Language Environment, and CICS, and describe some of the options that you can specify in the JVM profile and JVM properties file.
In the third section, we describe some of the commands you can use to manage your CICS Java setup after it is up and running.
3.1 Running a simple Java application in CICS
In this section, we describe how you can set up and run a simple Java application in CICS. We aim this section at systems programmers who are new to Java.
We included a brief overview of accessing the z/OS UNIX shell. If you are already familiar with this, you can go straight to 3.1.2, “Setting up the CICS sample Java application” on page 40.
3.1.1 Accessing the z/OS UNIX shell
The z/OS UNIX shell is the interactive interface to z/OS UNIX. You must access the shell to configure CICS to run Java applications, invoke shell commands and utilities, and also run shell scripts.
There are several ways to access the z/OS UNIX shell. You can choose between a UNIX-like interface, a TSO interface, and an ISPF interface. You can choose the interface with which you are most familiar and get a quicker start on z/OS UNIX.
We describe three ways to access the shell in this book, as shown in Figure 3-1. See ABCs of z/OS System Programming Volume 9, SG24-6989, for more information about accessing the shell and UNIX System Services in general.
Figure 3-1 Accessing the z/OS UNIX shell
If you are an experienced TSO user and new to UNIX, we recommend that you use the ISPF shell, which is a menu-driven interface that allows you to work with the zFS and to enter some UNIX commands. You can use the ISPF editor to modify files in the zFS. If you need to type a UNIX command that is not available on the menus, then you can open a command prompt from the Tools option on the action bar (see Table 3-2 on page 45).
To start the ISPF shell, at the ISPF command prompt enter TSO ISHELL or ISHELL from ISPF option 6, as shown in Figure 3-2.
File Directory Special_file Tools File_systems Options Setup Help
ssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss
UNIX System Services ISPF Shell
Enter a pathname and do one of these:
- Press Enter.
- Select an action bar choice.
- Specify an action code or command on the command line.
Return to this panel to work with a different pathname.
More: +
/usr/lpp/cicsts/cicsts32
________________________________________________________________
________________________________________________________________
________________________________________________________________
EUID=2231
Command ===> ____________________________________________________________
Figure 3-2 ISPF Shell
The other choice that is available from TSO is to use the OMVS command, which starts a UNIX-like interface with a command prompt. You can toggle between OMVS and the TSO/E command line. However, you cannot use the ISPF editor, nor can you use other ISPF functions, such as the split panel.
To start OMVS, at the ISPF command prompt enter TSO OMVS or enter OMVS from ISPF option 6. Figure 3-3 on page 40 shows the OMVS shell.
IBM
Licensed Material - Property of IBM
5694-A01 (C) Copyright IBM Corp. 1993, 2007
(C) Copyright Mortice Kern Systems, Inc., 1985, 1996.
(C) Copyright Software Development Group, University of Waterloo, 1989.
All Rights Reserved.
U.S. Government users - RESTRICTED RIGHTS - Use, Duplication, or
Disclosure restricted by GSA-ADP schedule contract with IBM Corp.
IBM is a registered trademark of the IBM Corp.
----------------------------------------------------------------
Set up environment variables for Java
----------------------------------------------------------------
PATH reset to /usr/lpp/java/J5.0/bin:/bin:.
JAVA_HOME reset to /usr/lpp/java/J5.0
CHRISR @ SC66:/>
===>
RUNNING
ESC=¢ 1=Help 2=SubCmd 3=HlpRetrn 4=Top 5=Bottom 6=TSO
7=BackScr 8=Scroll 9=NextSess 10=Refresh 11=FwdRetr 12=Retrieve
Figure 3-3 OMVS shell
If you are familiar with UNIX, you might choose to log in directly to the shell. You can use the telnet, rlogin, or ssh command to log in. You then enter commands at the prompt. You cannot use the ISPF editor, and you cannot switch to TSO. However, you can use the TSO command to run a TSO command from your shell. If you want to modify the contents of a file, you must be familiar with a UNIX editor, such as vi or emacs.
You must know the host name or IP address of the z/OS LPAR to log in. You might also need to know the port number for the service you are using if it differs from the well known port number for that service.
We used direct login to the UNIX shell using telnet while writing this book. Any screen shots or figures that show the z/OS UNIX shell in this book are from a telnet session.
3.1.2 Setting up the CICS sample Java application
In this section, we provide steps to set up and run one of the CICS sample Java applications. The Java application that we selected is the HelloCICSWorld JCICS application, which is supplied with CICS TS Version 3.2. A fuller explanation of how to set up and run this and the other sample Java applications is in Java Applications in CICS, SC34-6825.
You:
1. Build the sample application using a makefile.
2. Create directories and files in the HFS.or zFS
3. Modify the JVM profile.
4. Tailor the CICS system initialization parameters.
5. Install the required CICS resource definitions.
6. Run the Java application.
We assume that the following components are already installed, configured, and operational, and that no further configuration is necessary:
•CICS Transaction Server Version 3.2
•IBM SDK for z/OS, Java Technology Edition Version 5 Release 0
•Language Environment for z/OS
•z/OS UNIX System Services
Building the sample application using a makefile
CICS supplies makefiles that contain instructions to compile the sample Java application source code. The UNIX make command executes the instructions in the makefile.
You must set these three environment variables before running the make command:
PATH Unix System Services search path.
CICS_HOME The installation directory for CICS Transaction Server Version 3.2. Typically this is /usr/lpp/cicsts/cicsts32.
cicsts32 is defined by the USSDIR installation parameter when you installed CICS Transaction Server Version 3.2 (cicsts32 is the default).
JAVA_HOME The installation directory for IBM SDK for z/OS, Java Technology Edition Version 5 Release 0. In our environment, the SDK is installed in /usr/lpp/java/J5.0.
The environment variables might be set in one or more of the following places:
•In the RACF® user profile
•In the file /etc/profile
•In the file .profile in the shell user’s home directory
•In the file named in the ENV environment variable in the user’s .profile
•At the shell prompt
•In a shell script
These environment variables might already be set. You can use the echo command to check whether they were set, as shown in Example 3-1.
Example 3-1 Displaying the environment variables
$ [SC66] /u/cicsrs1: echo $PATH
/usr/lpp/java/J5.0/bin:/bin:.
$ [SC66] /u/cicsrs1: echo $JAVA_HOME
/usr/lpp/java/J5.0
$ [SC66] /u/cicsrs1: echo $CICS_HOME
 
$ [SC66] /u/cicsrs1:
 
Tip: In the UNIX shell, prefix the environment variable with the dollar sign ($) to substitute the value of the variable. The echo command then displays the values of the variables on the panel.
We already have PATH and JAVA_HOME set correctly because the commands to set them are in the file /etc/profile, as shown in Example 3-2.
Example 3-2 Commands to set the environment variables in /etc/profile
PATH=/usr/lpp/java/J5.0/bin:$PATH
export PATH
export JAVA_HOME=/usr/lpp/java/J5.0
 
Note: Example 3-2 shows two ways to export the environment variable. You can set the variable and then export it using two separate commands, or you can set and export the variable using one command.
Exporting a variable makes it available to the current process (in this case the shell) and any other processes that were created by the current process.
The null response to echo $CICS_HOME shows that it is not set. You can either add the commands to set and export CICS_HOME to /etc/profile or your own .profile file, or on the command line, you can enter the command export CICS_HOME=/usr/lpp/cicsts/cicsts32.
 
Note: Adding the command to /etc/profile affects all users. Any changes made in /etc/profile takes effect the next time a user invokes the shell.
To build the Java samples, you need write permission for the HFS or zFS directory in which the samples are stored and for its subdirectories. These directories are part of the directory structure that includes the other CICS files that were installed on HFS or zFS. Alternatively, you can copy the samples directory and its subdirectories into another directory to which you have write permissions. If you do this, use your own directory in place of the $CICS_HOME/cicsts32/samples directory in the following steps:
1. Type cd $CICS_HOME/samples/dfjcics to change directory.
2. Type make -f Helloworld.mak jvm to build the sample.
Example 3-3 shows the code for building the sample application.
Example 3-3 Building the sample application
$ [SC66] /u/cicsrs1: export CICS_HOME=/usr/lpp/cicsts/cicsts32
$ [SC66] /u/cicsrs1: cd $CICS_HOME/samples/dfjcics
$ [SC66] /cicsts32/samples/dfjcics: make -f HelloWorld.mak jvm
javac -deprecation -classpath .:/usr/lpp/cicsts/cicsts32/lib/dfjcics.jar examples/HelloWorld/HelloWorld.java
javac -deprecation -classpath .:/usr/lpp/cicsts/cicsts32/lib/dfjcics.jar examples/HelloWorld/HelloCICSWorld.java
$ [SC66] /cicsts32/samples/dfjcics:
You created two Java classes, HelloWorld and HelloCICSWorld that are stored in the $CICS_HOME/samples/dfjcics/examples/HelloWorld directory.
Creating directories and files in the HFS or zFS
In this section, you copy the supplied JVM profile and JVM properties file that the HelloCICSWorld application uses to a newly created directory. JVM profiles and JVM system properties are explained in more detail in “Setting up JVM profiles” on page 49, and “JVM system properties files” on page 51. Note that, in CICS Transaction Server Version 3.2, the JVM system properties files are optional, so you can omit the steps to create the props directory and to copy the sample properties files.
You also create a new working directory for the JVM. The CICS JVM uses this directory when creating the stdin, stdout, and stderr files for the JVM. The working directory is specified in the JVM profile.
First you create new directories under the CICS region user ID’s home directory to hold the JVM profiles and properties files. You also create a new working directory. Example 3-4 shows the commands that we entered.
Example 3-4 Creating the new directories and copying files
$ [SC66] /u/cicsts32: export CICS_HOME=/usr/lpp/cicsts/cicsts32
$ [SC66] /u/cicsts32: mkdir JVMProfiles
$ [SC66] /u/cicsts32: cd JVMProfiles
$ [SC66] /u/cicsts32/JVMProfiles: cp $CICS_HOME/JVMProfiles/* .
$ [SC66] /u/cicsts32/JVMProfiles: cd ..
$ [SC66] /u/cicsts32: mkdir props
$ [SC66] /u/cicsts32: cd props
$ [SC66] /u/cicsts32/props: cp $CICS_HOME/props/* .
$ [SC66] /u/cicsts32/props: cd ..
$ [SC66] /u/cicsts32: mkdir workdir
 
Tip: The cp commands in Example 3-4 specify a period (.) as the target directory. In UNIX, this denotes the current directory.
Modifying the JVM profile
You need to check and possibly modify the values shown in Table 3-1 in the sample JVM profile DFHJVMPR.
Table 3-1 DFHJVMPR options
Option
Description
What we coded
WORK_DIR
Working directory for JVM
WORK_DIR=/u/cicsts32/workdir
CICS_HOME
CICS TS installation path
CICS_HOME=/usr/lpp/cicsts/cicsts32
JAVA_HOME
SDK installation path
JAVA_HOME=/usr/lpp/java/J5.0/
JVMPROPS
Path and name of JVM properties file
JVMPROPS=/u/cicsts32/props/dfjjvmpr.props
CLASSPATH_SUFFIX
Directory search path for Java classes
CLASSPATH_SUFFIX=/usr/lpp/cicsts/cicsts32/samples/dfjcics
If you are using ISHELL to access the shell, then you can use the ISPF editor to update the profile. If you are using OMVS or direct login to the shell, you must use a UNIX editor, such as vi.
Tailoring the CICS system initialization parameters
You need to add the system initialization parameter JVMPROFILEDIR. This is the path to the directory that holds the JVM profiles. Remember that case is significant when coding this parameter. We coded JVMPROFILEDIR=/u/cicsts32/JVMProfiles.
Restart CICS to pick up the change.
Installing the required CICS resource definitions
After CICS is back up, you can log on and install the CICS resource definitions.
The definitions for the CICS Java sample applications are in group DFH$JVM. The transaction for the HelloCICSWorld Java application is JHE2 and the program is DFJ$JHE2.
Use CEDA to install the group.
Running the Java application
Enter JHE2 at your CICS terminal. Example 3-5 shows the response.
Example 3-5 Running JHE2
JHE2Hello from a Java CICS application
The HelloCICSWorld class uses the JCICS Task class to send text to the terminal.
 
Note: The first time that you run JHE2, it takes a second or two to complete because of the time spent initializing the JVM. This delay does not occur the second time that you run the transaction. The JVM is reused.
You just saw one of the benefits of using a reusable JVM.
3.2 System configuration
In this section, we look at tailoring your UNIX System Services, Language Environment and the CICS Transaction Server configuration that is required to support CICS Java applications.
Java application programs are executed inside a Java Virtual Machine (JVM) within CICS.
A JVM in CICS runs as a UNIX System Services process in an Language Environment enclave created using the Language Environment pre-initialization module, CEEPIPI, which means that you must review and possibly modify your UNIX System Services and Language Environment configuration in addition to tailoring your CICS configuration to support running Java applications in CICS.
3.2.1 UNIX System Services
You specify UNIX System Services parameters in the BPXPRMxx members of SYS1.PARMLIB. The default values might not be sufficient when using the CICS JVM. Installation Guide, GC34-6812, suggests that you start with the following values and adjust them based on your experiences.
IPCSEMNSEMS 1000
MAXPROCSYS 500
MAXPROCUSER 512
MAXUIDS 500
MAXASSIZE 2000000000
MAXFILEPROC 512
MAXPTYS 256
MAXTHREADS 10000
MAXTHREADTASKS 5000
MAXCPUTIME 2147483647
z/OS V1R9.0 UNIX System Services Planning, GA22-7800 discusses the settings of some of these parameters. A description of all of the BPXPRMxx parameters are in z/OS MVS Initialization and Tuning Reference, SA22-7592.
You can change these values dynamically without re-IPLing using the SETOMVS or SET OMVS commands, for example: SETOMVS MAXPROCUSER=256
You must edit the BPXPRMxx member to pick up the changes on the next IPL.
Pay special attention to the setting of MAXPROCUSER if you have several CICS regions with the same region user ID running multiple JVMs. There is a large number of UNIX processes that run under the CICS region user ID. You might need to increase MAXPROCUSER further. Message BPXI040 is issued when the process limit is reached.
You set system-wide limits when you specify the values in BPXPRMxx. You might want to set a lower system-wide limit and then set a higher limit for individual users (such as your CICS region user ID). You can do this by specifying limits in the OMVS segment of the user’s profile. Table 3-2 shows the RACF OMVS segment attribute names and the corresponding BPXPRMxx parameter names.
Table 3-2 RACF OMVS segment attributes
RACF OMVS segment attribute name
BPXPRMxx parameter name
ASSIZEMAX
MAXASSIZE
CPUTIMEMAX
MAXCPUTIME
FILEPROCMAX
MAXFILEPROC
PROCUSERMAX
MAXPROCUSER
THREADSMAX
MAXTHREADS
Use the RACF ADDUSER or ALTUSER command to specify these attributes on a per-user basis:
ALTUSER userid OMVS(PROCUSERMAX(nnnn)
3.2.2 Language Environment
Language Environment is a prerequisite for CICS JVM programs. However, unlike other languages, JVM programs do not require the CICS Language Environment interface. JVM programs run with Language Environment support using MVS services (not CICS services). JVM programs require the Language Environment support that is provided by the SCEERUN and SCEERUN2 libraries only.
You can either define SCEERUN and SCEERUN2 in the CICS STEPLIB or include them in the MVS linklist. You also must add SCEERUN to DFHRPL.
You can get the Language Environment runtime options for the enclave in which the JVM runs from:
•CEEDEOPT
•DFHJVMRO
•CICS JVM Launcher program
The options in Example 3-6 cannot be overridden and are set by the CICS JVM launcher program.
Example 3-6 Language Environment runtime options that cannot be over-ridden
POS(ON)
XPLINK(ON)
ABTERMENC(ABEND)
You can override all other runtime options for the JVM by assembling and linking a module called DFHJVMRO. The source code for a sample DFHJVMRO is provided in SDFHSAMP. A DFHJVMRO load module is not shipped.
 
Note: When coding options in DFHJVMRO, remember to add a trailing blank.
If you assemble and link a new version of DFHJVMRO while CICS is running, you must use the command CEMT SET PROG(DFHJVMRO) NEW to load the new version of the program.
If DFHJVMRO cannot be loaded by the JVM launcher program, CICS builds the default runtime options programmatically. Example 3-7 shows the default runtime options.
Example 3-7 Default Language Environment runtime options for the CICS JVM
ALL31(ON)
LIBSTACK(8,900,FREE)
STACK(128K,128K,ANY,KEEP,128k,128k)
HEAP(4M,1M,ANY,FREE,0K,4080)
BELOWHEAP(4096,2048,FREE)
ANYHEAP(4K,8176,ANY,FREE)
STORAGE(NONE,NONE,NONE,0K)
MSGFILE(CEEMSG)
ENVAR(“_EDC_STOR_INITIAL=4K”)
TRAP(ON,NOSPIE)
3.2.3 CICS Transaction Server
In this section, we describe the tasks to configure CICS to run Java applications.
Security settings for the CICS region user ID
To create JVMs, CICS requires access to directories and files in the UNIX System Services HFS or zSF. You must give your CICS region user permission to access these resources in the HFS or zFS, which is covered in detail in “Setting up Java Support and JVMs” in Java Applications in CICS, SC34-6825. We summarize the key points in this section:
•Assign a suitable UNIX user identifier (UID) and suitable UNIX group identifier (GID) for your CICS region user.
•Specify a home directory for your CICS region user.
•Ensure that the zFS that contains the home directory is mounted. We recommend that you use the automount facility of UNIX System Services. Refer to z/OS V1R9.0 UNIX System Services Planning, GA22-7800, for further information about the automount facility.
•Give the CICS region user read and execute access to the directories and files that every CICS region needs to create JVMs. These files and directories are in $CICS_HOME and its sub-directories and in /usr/lpp/java/J5.0/bin and /usr/lpp/java/J5.0/bin/classic.
•Give the CICS region user read, write, and execute access to the working directories that you specified for stdin, stdout, and stderr for the JVMs in each CICS region. The WORK_DIR option in the JVM profile specifies the working directory. If you redirect the output using the USEROUTPUTCLASS option in the JVM profile, the CICS region user needs access to the directories to which the output is redirected.
•Give the CICS region user read and execute access to directories and files that you:
 – Specified on the CLASSPATH_SUFFIX option in the JVM profile.
 – Added to the LIBPATH in the JVM profile.
 – Are holding any JVM profiles or JVM properties files you created.
CICS startup JCL
Add the SDFJAUTH library to STEPLIB of your CICS startup JCL. This library must be APF authorized. The load modules in SDFJAUTH contain the CICS Java launcher code.
The storage that the CICS JVM uses does not come from the CICS Dynamic Storage Areas (DSAs). You must specify a region size for your CICS region that is sufficient both to accommodate the CICS DSAs and the storage that is required for your planned Java workload. CICS Performance Guide, SC34-6833, contains guidance on calculating and tuning the storage requirements for your Java workload. As a starting point, we recommend that you set a region size of at least 400 MB.
CICS system initialization parameters
Review the CICS system initialization parameters that we discussed in this section when you set up CICS to run Java applications.
There are some additional system initialization parameters that control CICS tracing for the JVM. You might need to set these parameters for debugging purposes. We discuss these parameters in Chapter 8, “Problem determination and debugging” on page 193.
There is more information about the system initialization parameters in CICS System Definition Guide, SC34-6813.
JVMPROFILEDIR
JVMPROFILEDIR specifies the name (up to 240 characters long) of an HFS or zFS directory that contains the JVM profiles for CICS. CICS searches this directory for the profiles that it needs to configure JVMs. The default value of JVMPROFILEDIR is /usr/lpp/cicsts/cicsts32/JVMProfiles.
If you chose a different name during CICS installation for the cicsts32 directory beneath which the sample JVM profiles are stored (that is, if you chose a non-default value for the CICS_HOME variable used by the DFHIJVMJ job), or if you want CICS to load the JVM profiles from a directory other than the samples directory, do one of the following:
•Change the value of the JVMPROFILEDIR system initialization parameter.
•Link to your JVM profiles from the directory that JVMPROFILEDIR specified using UNIX soft links. Using this method, you can store your JVM profiles in any place in the HFS or zFS file system. Use the ln -s command to create a soft link.
 
 
JVM profiles DFHJVMPR and DFHJVMCD:
The JVM profiles DFHJVMPR and DFHJVMCD and their associated JVM properties files, must always be available to CICS:
•DFHJVMPR is used if a Java program is defined as using a JVM, but no JVM profile is specified, and it is used for sample programs.
•DFHJVMCD is used by CICS-defined programs, which includes the default request processor program, the program that CICS uses to publish and retract deployed JAR files, and the program that CICS uses to manage the Shared Class Cache.
Both of these JVM profiles must therefore be present in the directory that is specified. If JVMPROPS is not specified, the properties files are not required.
JVMCCPROFILE
JVMCCPROFILE specifies the JVM profile to be used for the Java 1.4.2 master JVM that initializes the Shared Class Cache. It is not used when running Java 5.
JVMCCSIZE
JVMCCSIZE specifies the size of the Shared Class Cache on an initial or cold start of CICS. The size of the Shared Class Cache can be between 1 MB and 2047 MB. You can specify the number:
•In bytes
•As a whole number of kilobytes followed by the letter K
•As a whole number of megabytes followed by the letter M
The default value is 24 MB (specified as 24M).You can use the CEMT PERFORM CLASSCACHE START or RELOAD command (or the equivalent EXEC CICS command) to change the size of the Shared Class Cache while CICS is running.
 
Attention: On subsequent restarts, the value from the last CICS execution is used unless you provide JVMCCSIZE as a SIT override.
JVMCCSTART
JVMCCSTART determines whether the Shared Class Cache is started during CICS initialization and sets the status of autostart for the Shared Class Cache. The Java 5 Shared Class Cache persists across CICS restarts, so this parameter only applies if the cache was destroyed.
When autostart is enabled for the Shared Class Cache, if the Shared Class Cache was stopped or is not yet started, it is started when CICS receives a request to run a Java application in a JVM whose profile requires the use of the Shared Class Cache.
When autostart is disabled, the Shared Class Cache can only be started by a CEMT PERFORM CLASSCACHE START command (or the equivalent EXEC CICS command).
Using CEMT, you can change the status of autostart while CICS is running.
 
Attention: If you do this, subsequent CICS restarts use the changed setting unless the system is INITIAL or COLD started or the JVMCCSTART system-initialization parameter is specified as an override at startup. In these cases, the setting from the system-initialization parameter is used.
MAXJVMTCBS
CICS JVMs run on their own TCBs. MAXJVMTCBS limits the total number of TCBs in the pool of open TCBs that CICS uses for JVMs. Each JVM runs on a J8 or J9 TCB, so MAXJVMTCBS limits the number of JVMs that can be active in the CICS region.
The default is five. The minimum permitted value is 1, meaning that CICS can always create at least one open TCB for a JVM to use, of either J8 or J9 mode.
In Chapter 9, “Performance for Java in CICS Transaction Server Version 3” on page 221, we provide information about setting MAXJVMCTBS. Refer to CICS Performance Guide, SC34-6833, for definitive guidance on setting and tuning your setting of MAXJVMTCBS.
You can change the setting for MAXJVMTCBS without restarting CICS by using the CEMT SET DISPATCHER MAXJVMCTBS command.
 
Note: JM TCBs, used to initialize and terminate the Shared Class Cache, do not count towards the MAXJVMTCBS limit.
Setting up JVM profiles
The JVM is started by the CICS Java launcher, which uses a set of options known as a JVM profile. A JVM profile determines the characteristics of a JVM. You specify the JVM profile that a Java application uses in the CEDA PROGRAM definition for that Java program. You can set up several JVM profiles that use different options to cater to the needs of different applications. JVM profiles are text files that are stored on HFS or zFS.
The IBM JVM that CICS uses has a set of standard options that are supported in the z/OS Runtime Environment. An additional set of nonstandard options is specific to the z/OS virtual machine implementation. The IBM SDK for z/OS platforms, Java Technology Edition Version 5.0 SDK Guide contains detailed descriptions of all the options that you can specify.
 
Tip: If you need to set environment variables to control the behavior of the CICS JVM, specify them in the JVM profile.
Typically, you set options in the profile that specifies:
•Whether the JVM runs in continuous, or single-use mode
•Whether the JVM uses the Shared Class Cache or not
•Directory path names, such as CICS_HOME and JAVA_HOME
•The location of the JVM systems properties file, if there is one
•The Class paths for application classes
•Stack and heap size settings for the JVM
•Where output from the JVM (System.out and System.in) is written
 
Tip: You can use the symbol &APPLID; in any value to indicate that the APPLID of the CICS region must be substituted at runtime. This symbol allows the use of the same profile for all regions, even if a different WORK_DIR (for example) is required. APPLIDs are always upper case.You can also use the symbol &JVM_NUM; in any value to indicate that the unique JVM number, which is its UNIX System Services Process Id (pid) must be substituted at runtime. This allows for JVM-unique file naming.
CICS System Definition Guide, SC34-6813, lists the options that are of particular relevance to CICS. Table 3-3 on page 50 shows the options that you are most likely to set. Each entry in the table shows the default value if not specified in the profile. It also shows, for each type of JVM, whether the option is required (must be specified), OK (might be specified), or ignored (CICS ignores the option if specified). If a particular setting for the option is required for a certain type of JVM (Classcache or Standalone) or if the option is only applicable to a certain type of JVM, this information is given instead.
Refer to CICS System Definition Guide, SC34-6813 and IBM SDK for z/OS platforms, Java Technology Edition Version 5.0 SDK Guide, for descriptions of the options.
Table 3-3 JVM profile options
Option
Default
Classcache
Standalone
CLASSCACHE
NO
YES
NO
REUSE
YES
YES or NO
YES or NO
CICS_HOME
None
Required
Required
JAVA_HOME
None
Required
Required
WORK_DIR
/tmp
OK
OK
CLASSPATH_SUFFIX
None
OK
OK
LIBPATH_SUFFIX
None
OK
OK
JVMPROPS
None
OK
OK
DISPLAY_JAVA_VERSION
NO
YES or NO
YES or NO
GC_HEAP_THRESHOLD
85
50-100
50-100
IDLE_TIMEOUT
30
0-10080
0-10080
PRINT_JVM_OPTIONS
NO
YES or NO
YES or NO
STDERR
dfhjvmerr
OK
Ok
STDIN
dfhjvmin
OK
OK
STDOUT
dfhjvmout
OK
OK
Options to be passed to the JVM at startup are prefixed with a hyphen '-', for example, -Xmx32M sets the maximum JVM heap size to 32 megabytes. CICS does not check options that are prefixed with a hyphen; instead, CICS simply passes them to the JVM, which means that you can specify system properties for the JVM in the JVM Profile by using '-Dpropertyname=value'
PRINT_JVM_OPTIONS=YES causes every option that is passed to the JVM to be printed.
If you have a pre-CICS Transaction Server Version 3.2 JVM Profile, you can still use it, unless it specifies REUSE=RESET as the resettable mode of the JVM, which is no longer supported. Any other obsolete options are identified with a message that suggests the best replacement option.
CICS supplies sample JVM profiles in /usr/lpp/cicsts/$CICS_HOME/JVMProfiles. You can use these profiles for your own applications, only adding your classes to the CLASSPATH_SUFFIX options. The CICS installation job, DFHIJVMJ, substitutes your values for the symbols &CICS_HOME and &JAVA_HOME in the sample JVM profiles.
The supplied sample JVM profiles are:
DFHJVMPR Reusable JVM. Shared Class Cache is not used. This is the default JVM profile for a CICS PROGRAM definition.
DFHJVMPC Reusable JVM using the Shared Class Cache.
DFHJVMPS Single-use JVM. We do not recommend using this profile for Java applications running in production systems.
DFHJVMCC Java 1.4.2 Master JVM that initializes the Shared Class Cache. It is not used when running Java 5.
DFHJVMCD Profile for CICS-supplied system programs written in Java. Do not use this profile for your own programs. Only make changes so that it is set up correctly for your CICS region to allow the CICS-supplied programs to run, for example, you might need to change JAVA_HOME.
Java Applications in CICS, SC34-6825, contains detailed information about the CICS-supplied JVM profiles.
JVM system properties files
Each JVM profile can optionally reference a JVM properties file, which is another text file containing the system properties for the JVM. The JVMPROPS option in the profile specifies the path of the systems properties file. System properties are key name and value pairs.
IBM SDK for z/OS platforms, Java Technology Edition Version 5.0 SDK Guide, contains a list of system properties that you might need to specify. IBM Developer Kit and Runtime Environment, Version 5.0 Diagnostics Guide, SC34-6650 describes system properties that you might need to set to gather diagnostic materials when working with IBM support personnel.
 
Note: Any system property that you specify using the -D option when launching a JVM from the command line can go in the JVM systems property file, with or without the -D prefix or with the -D prefix in the JVM profile.
CICS supplies sample JVM system properties files in /usr/lpp/cicsts/&CICS_HOME/props to get you started. There is a corresponding system properties file for each supplied JVM profile.
Table 3-4 Supplied JVM system properties file
Supplied JVM profile name
Corresponding JVM systems property file
DFHJVMPC
dfjjvmpc.props
DFHJVMPR
dfjjvmpr.props
DFHJVMPS
dfjjvmps.props
DFHJVMCD
dfjjvmcd.props
 
Note: Because JVM profiles and JVM properties files are HFS or zFS files, case is important whenever you use their names in CICS. You must enter the name using the same combination of upper and lower case characters that is present in the HFS or zFS file name.
In the CEDA panels, any field where you enter an HFS or zFS file name accepts mixed case characters. This is not true if you enter the name in a CEDA command line or in another CICS transaction, such as CEMT or CECI. Therefore, you might to temporarily suppress upper case translation for your terminal when working with HFS or zFS file names. Enter CEOT NOUCTR at a CICS terminal to do this. CEOT UCTR restores upper case translation for your terminal.
Pay attention to case when specifying HFS or zFS file names in the source for your system initialization table (SIT) or SIT overrides.
CICS PROGRAM definition attributes
You use a PROGRAM resource definition to specify the control information that CICS requires to load and run an application program. Some attributes of the PROGRAM resource definition are applicable only to Java application programs, and other attributes require fixed values for Java application programs. There is more information about PROGRAM attributes in CICS Resource Definition Guide, SC34-6815.
JVM
You must specify JVM(YES) for a Java application.
JVMCLASS
JVMCLASS specifies the fully qualified name of the main class in a Java program to be run in a CICS JVM. The fully qualified name is the class name qualified by the package name. The name is case-sensitive and must be entered with the correct combination of upper and lower case letters.
 
Tip: The package name describes a hierarchical directory structure. Specify the path to the directory structure (which might be within a Java archive (JAR) file) in CLASSPATH_SUFFIX. The JVMCLASS attribute then specifies how to locate the class within the directory structure, for example, the CICS-supplied HelloCICSWorld class is in package examples.HelloWorld. The supplied sample creates the directory structure examples/HelloWorld below /usr/lpp/cicsts/cicsts32/samples/dfjcics. The HelloCICSWorld class file is created in /usr/lpp/cicsts/cicsts32/samples/dfjcics/examples/HelloWorld.
So you specify /usr/lpp/cicsts/cicsts32/samples/dfjcics on your classpath and examples.HelloWorld.HelloCICSWorld as your JVMCLASS attribute in the program definition.
JVMPROFILE
JVMPROFILE specifies the name of a JVM profile to use for this program. The JVM profile must be in the directory that is specified by the system initialization parameter JVMPROFILEDIR.
LANGUAGE
This attribute is ignored for JVM programs. Specifying JVM(YES) tells CICS that this is a Java program.
CONCURRENCY
JVM programs must be defined as threadsafe.
3.3 Managing your CICS Java environment
The CICS CEMT transaction provides several commands to manage your CICS Java environment. In this section, we list and briefly describe the commands that you are most likely to use. For more information about each of the commands, refer to CICS Supplied Transactions, SC34-6817.
All of these commands are available in the system programming interface (SPI). You can write your own programs to use EXEC CICS commands to manage. Refer to CICS System Programming Reference, SC34-6820, for more information.
If you use CICSPlex® System Manager (CPSM) to manage your CICSplex, some of these commands are available using the CPSM Web User Interface (WUI) or CPSM Application Programming Interface (API). There is more information about using the WUI in CICSPlex SM Web User Interface Guide, SC34-6841.
3.3.1 CEMT INQUIRE CLASSCACHE
INQUIRE CLASSCACHE, shown in Example 3-8, returns information about the Shared Class Cache in the CICS region and reports the presence of any old Shared Class Caches that are awaiting deletion.
Example 3-8 CEMT INQUIRE CLASSCACHE
I CL
STATUS: RESULT - OVERTYPE TO MODIFY
Classcache
Autostartst( Enabled )
Status(Started)
Profile()
Datestarted(04/06/05)
Timestarted(10:08:38)
Totaljvms(0000)
Oldcaches(0000)
Phasingout(0000)
Reusest(Reuse)
Cachesize(24M )
Cachefree(24M)
 
Attention: The Java 5 JVM does not provide CICS with information about how full the cache is, so the Cachefree value always shows the same as Cachesize.
You can modify the autostart status of the Shared Class Cache. Autostartst takes one of two values:
Enabled If the Shared Class Cache was stopped or is not yet started on this CICS execution, the Shared Class Cache is started as soon as CICS receives a request to run a Java application in a JVM whose profile requires the use of the Shared Class Cache.
Disabled If the Shared Class Cache was stopped or is not yet started on this CICS execution, an explicit CEMT PERFORM CLASSCACHE START command is required to start it. If the status of the Shared Class Cache is Stopped and autostart is disabled and CICS receives a request to run a Java application in a JVM whose profile requires the use of the Shared Class Cache, the request fails.
3.3.2 CEMT INQUIRE DISPATCHER
INQUIRE DISPATCHER returns information about the current state of the dispatcher. You can see the current number of active JVM TCBs (Actjvmtcbs). The value that is displayed includes both J8 and J9 TCBs, but not the JM TCBs that are used for Shared Class Cache managment. You can also view and update the maximum number of JVM TCBs from this panel (Maxjvmtcbs). Example 3-9 shows the syntax for CEMT INQUIRE DISPATCHER.
Example 3-9 CEMT INQUIRE DISPATCHER
I DIS
STATUS: RESULTS - OVERTYPE TO MODIFY
Actjvmtcbs(000)
Actopentcbs(0000)
Actssltcbs(0000)
Actxptcbs(000)
Aging( 00500 )
Maxhptcbs( 005 )
Maxjvmtcbs( 005 )
Maxopentcbs( 0130 )
Maxssltcbs( 0008 )
Maxxptcbs( 005 )
Mrobatch( 001 )
Runaway( 0015000 )
Scandelay( 0100 )
Subtasks(000)
Time( 0001000 )
 
 
3.3.3 CEMT INQUIRE JVM
INQUIRE JVM displays all of the JVMs in the CICS region. You cannot change the displayed values. You can also enter CEMT INQUIRE JVM with one of the values listed below to display all of the JVMs in the CICS region with a particular status, for example, you can enter CEMT INQUIRE JVM UEXECKEY to display all of the JVMs that execute in user key or CEMT INQUIRE JVM PROFILE(DFHJVMPC) to display all of the JVMs that were created with the JVM profile DFHJVMPC.
Example 3-10 CEMT INQUIRE JVM
I JVM
STATUS: RESULTS - OVERTYPE TO MODIFY
Jvm(0017171306) Age(0000001810) Allo(0000000000) Cla Reu
Uex Pro(DFHJVMPC) Tas(0000000)
Jvm(0050725839) Age(0000001804) Allo(0000000000) Reu
Uex Pro(DFHJVMPR) Tas(0000000)
Jvm(0020525217) Age(0000001711) Allo(0000000000) Reu
Uex Pro(DFHJVMPR) Tas(0000000)
 
Note: The number that is associated with the JVM is the UNIX System Services process id that is executing the JVM and can be used for diagnostic information in UNIX System Services.
3.3.4 CEMT INQUIRE JVMPOOL
INQUIRE JVMPOOL displays information about the JVM pool (if any JVMs exist) in the CICS region. There is no identifier on this command. A CICS region supports only one pool of JVMs.
You can see the number of JVMs that were initialized and are available for use or allocated to tasks. This total includes JVMs that are in the process of being terminated and removed from the region and included in the PHASINGOUT count.
You can enable or disable the JVM pool. A disabled JVM pool cannot accept new requests to service JVM programs. Programs can still execute if they were started before the JVM pool became disabled. Example 3-11 shows the CEMT INQUIRE JVMPOOL.
Example 3-11 CEMT INQUIRE JVMPOOL
I JVMPO
STATUS: RESULT - OVERTYPE TO MODIFY
Status( Enabled )
Total(0001)
Phasingout(0000)
Terminate( )
3.3.5 CEMT INQUIRE PROGRAM
INQUIRE PROGRAM returns information about an installed program definition, as shown in Example 3-12.
Example 3-12 CEMT INQUIRE PROGRAM
I PROG(TRADERPJ)
STATUS: RESULTS - OVERTYPE TO MODIFY
Prog(TRADERPJ) Jav Pro Ena Ced
Res(000) Use(0000000001) Bel Uex Ful Thr Cic Jvm
The expanded display shows the class name and JVM profile. You can change the class name and JVM profile from this display. You might need to disable upper case translation before specifying a new class name. Example 3-13 on page 56 shows the CEMT INQUIRE PROGRAM.
Example 3-13 CEMT INQUIRE PROGRAM (expanded display)
I PROG(TRADERPJ)
RESULT - OVERTYPE TO MODIFY
Program(TRADERPJ)
Length()
Language(Java)
Progtype(Program)
Status( Enabled )
Sharestatus( )
Copystatus( Notrequired )
Cedfstatus( Cedf )
Dynamstatus(Notdynamic)
Rescount(000)
Usecount(0000000001)
Dataloc(Below)
Execkey(Uexeckey)
Executionset( Fullapi )
Concurrency(Threadsafe)
Apist(Cicsapi)
Remotesystem()
Runtime( Jvm )
Library()
Librarydsn()
Jvmclass( com.ibm.itso.sg245275.trader.SimpleTraderPL )
Jvmclass( )
Jvmclass( )
Jvmclass( )
Jvmclass( )
Jvmprofile( DFHJVMPR )
3.3.6 CEMT PERFORM CLASSCACHE
You can use the PERFORM CLASSCACHE command to initialize (start or reload) or terminate (phase out, purge, or forcepurge) the Shared Class Cache. Although you are performing one of these operations, you can use other options on the command to set attributes of the Shared Class Cache:
• When you initialize the Shared Class Cache (PERFORM CLASSCACHE START or RELOAD), you can change its size (Cachesize option).
• When you are terminating the Shared Class Cache (PERFORM CLASSCACHE PHASEOUT, PURGE, or FORCEPURGE), you can set the status of autostart (Autostartst option). If you do not want the Shared Class Cache to start up again until you enter an explicit command, you can use this option to ensure that autostart is disabled.
Subsequent CICS restarts use the most recent settings that you made using the PERFORM CLASSCACHE command (or the SET CLASSCACHE command), unless the system is INITIAL or COLD started or the system initialization parameters are specified as overrides at startup. In these cases, the settings from the system initialization parameters are used. Example 3-14 on page 57 shows the CEMT PERFORM CLASSCACHE.
Example 3-14 CEMT PERFORM CLASSCACHE
PER CL
STATUS: COMMAND SYNTAX CHECK
CEMT Perform CLasscache
( Reload | Start )
( Forcepurge | PHaseout | PUrge )
< ( Disabled | Enabled > )
< PRofile() >
< Cachesize() >
Use one of the following options to terminate the Shared Class Cache.
Forcepurge All tasks that use JVMs that are dependent on the Shared Class Cache are terminated by the SET TASK FORCEPURGE mechanism, and the JVMs are terminated. No more JVMs can use the Shared Class Cache, and it is deleted when all the JVMs that were dependent on it are terminated.
Phaseout All JVMs that use the Shared Class Cache are marked for deletion. The JVMs are actually deleted when they finish running their current Java programs. No more JVMs can use the Shared Class Cache, and it is deleted when all of the JVMs that were dependent on it were terminated.
Purge All tasks that use JVMs that are dependent on the Shared Class Cache are terminated by the SET TASK PURGE mechanism, and the JVMs are terminated. No more JVMs can use the Shared Class Cache, and it is deleted when all of the JVMs that were dependent on it were terminated.
 
Note: The Phaseout, Purge, and Forcepurge operations also act on any old Shared Class Caches that are still present in the region because they are waiting for JVMs that are dependent on them to be phased out, for example, if you issue a CEMT PERFORM CLASSCACHE Forcepurge command, all tasks that use JVMs that are dependent on a Shared Class Cache are forcepurged (both those dependent on the current Shared Class Cache and those dependent on old Shared Class Caches).
 
Note: The Profile option refers to the Java 1.4.2 master JVM Profile. Any value that is entered there is ignored when running Java 5.
3.3.7 CEMT PERFORM JVMPOOL
You can use the PERFORM JVMPOOL command to start JVMs without running an application program. You specify the number of JVMs that are required, the execution key, and the JVM profile to be used by them.
You can also use the command to terminate all or some of the JVMs in the pool to implement profile changes or add new application classes. Example 3-15 shows the CEMT PERFORM JVMPOOL.
Example 3-15 CEMT PERFORM JVMPOOL
P JVMPOOL START JVMC(2) UEX JVMPROF(DFHJVMPR)
STATUS: RESULTS
Initialize( Start )
Jvmcount( 002 )
Execkey( Uexeckey )
Terminate( )
Jvmprofile( DFHJVMPR )
 
3.3.8 CEMT SET DISPATCHER
You can use the SET DISPATCHER command to specify the maximum number of J8 and J9 mode open TCBs that can exist concurrently in the CICS region. The value specified is in the range of 1 to 999. If you reduce MAXJVMTCBS from its previously defined value, and the new value is less than the number of open TCBs that are currently allocated. CICS detaches TCBs to achieve the new limit only when they are freed by user tasks. Transactions are not abended to allow TCBs to be detached to achieve the new limit. If there are tasks that are queued waiting for a J8 mode, TCB and you increase MAXJVMTCBS from its previously defined value, and CICS attaches a new TCB to resume each queued task, up to the new limit. Example 3-16 shows the CEMT SET DISPATCHER.
Example 3-16 CEMT SET DISPATCHER
SET DIS MAXJVMTCBS(6)
STATUS: RESULTS - OVERTYPE TO MODIFY NORMAL
Actjvmtcbs(000)
Actopentcbs(0000)
Actssltcbs(0000)
Actxptcbs(000)
Aging( 00500 )
Maxjvmtcbs( 006 )
Maxopentcbs( 0130 )
Maxssltcbs( 0008 )
Maxxptcbs( 005 )
Mrobatch( 001 )
Runaway( 0015000 )
Scandelay( 0100 )
Subtasks(000)
Time( 0001000 )
3.3.9 CEMT SET JVMPOOL
Using the SET JVMPOOL command, shown in Example 3-17, you can enable or disable the JVM pool or to terminate the pool altogether.
Example 3-17 CEMT SET JVMPOOL
SET JVMPO PHASE
STATUS: RESULTS - OVERTYPE TO MODIFY NORMAL
Status( Enabled )
Total(0000)
Phasingout(0000)
Terminate( Phaseout )
Use one of the following options to terminate a pool:
Forcepurge All tasks that use JVMs in the pool are terminated by the SET TASK FORCEPURGE mechanism. The Shared Class Cache is deleted when all of the JVMs that were dependent on it were terminated.
Phaseout All JVMs in the pool are marked for deletion. The JVMs are actually deleted when they finish running their current Java program. The Shared Class Cache is deleted when all of the JVMs that were dependent on it were terminated.
Purge All tasks that use JVMs in the pool are terminated by the SET TASK PURGE mechanism, and the JVMs are terminated. The Shared Class Cache is deleted when all of the JVMs that were dependent on it were terminated.
Tip: If you change the JVM profile or JVM system properties file for a JVM that is currently in the pool, and you want the changes to take effect, you need not terminate the whole JVM pool; instead, you can use the PERFORM JVMPOOL command to terminate only those JVMs with that profile.
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset