Setting up a PROGRAM resource definition for a Java program to run in a JVM

When an application makes a request to run a Java program, it can make the request in various ways: for example, it can make an enterprise bean request, start a transaction, or link to or call the program by name. How CICS creates JVMs explains how CICS locates the PROGRAM resource definition in each case. That topic also gives fuller information about some of the attributes mentioned in this topic. Only standard Java programs need their own individual PROGRAM resource definitions, so if you are setting up CORBA stateless objects or enterprise beans, skip this section and move on to Adding application classes to the class paths for a JVM.

The CICS® Resource Definition Guide tells you how to set up a PROGRAM resource definition for a program. The attributes you need to specify on the PROGRAM resource definition to enable a Java program to run in a JVM are as follows:
EXECKEY
Specify EXECKEY(USER) if you want the program to run in a JVM that executes in user key. The default for the EXECKEY parameter is USER. Before CICS Transaction Server for z/OS®, Version 2 Release 3, the EXECKEY parameter was ignored for Java programs, so you might find that in most cases, the PROGRAM resource definitions for any Java programs that you created for earlier releases of CICS are still set to the default of EXECKEY(USER). EXECKEY(USER) is suitable for most Java programs, because it improves storage protection. However, if the program is part of a transaction that specifies TASKDATAKEY(CICS), the program needs to run in a JVM in CICS key, so in this case, specify EXECKEY(CICS). Execution key (EXECKEY attribute) explains more about the effects of setting the execution key.
JVM
Specify YES to state that the program is a Java program that has to run in a JVM.
JVMCLASS
Specify the name of the main class in the Java program that is to run in the JVM. If the program has been built as a package (that is, compiled using a Java package statement), you need to specify the fully qualified name, which is the Java class name qualified by the package name, with a period (.) used as a separator. For example, the package example.HelloWorld contains the class HelloCICSWorld; in this case, the fully qualified class name is example.HelloWorld.HelloCICSWorld. If the program has not been built as a package, you only need to specify the class name, with no qualifiers.

The names are case-sensitive and must be entered with the correct combination of upper and lower case letters. For example, com.ibm.cics.iiop.RequestProcessor is the class specified for the CICS IIOP request processor program, DFJIIRP. The CEDA panels accept mixed case input for the JVMCLASS field irrespective of your terminal's UCTRAN setting. However, this does not apply when values for this field are supplied on the CEDA command line, or by using another CICS transaction such as CEMT or CECI. If you need to enter a class name in mixed case when you use CEDA from the command line or when you use another CICS transaction, ensure that the terminal you use is correctly configured, with upper case translation suppressed.

You can use the CEMT SET PROGRAM JVMCLASS command or the EXEC CICS SET PROGRAM JVMCLASS command to change the name of the main class from that specified on the installed PROGRAM resource definition. (If you use an EXEC CICS command to set the JVMCLASS field, the value is always accepted in mixed case.) If the program uses a single-use JVM (that is, with a JVM profile that specifies the option REUSE=NO), you can also use the user-replaceable program DFHJVMAT to override the JVMCLASS specified on the installed PROGRAM resource definition. On 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.

JVMPROFILE
Specify the name (up to eight characters) of the profile that CICS is to use for the JVM that will run this program. The default is DFHJVMPR. Setting up JVM profiles and JVM properties files tells you how to select or create JVM profiles and their associated JVM properties files.

As JVM profiles are HFS files, case is important. When you specify the name of the JVM profile, you must enter it using the same combination of upper and lower case characters that is present in the HFS file name. As for the JVMCLASS field, the CEDA panels accept mixed case input for the JVMPROFILE field irrespective of your terminal's UCTRAN setting. However, this does not apply when values for this field are supplied on the CEDA command line, or by using another CICS transaction such as CEMT or CECI. If you need to enter the name of a JVM profile in mixed case when you use CEDA from the command line or when you use another CICS transaction, ensure that the terminal you use is correctly configured, with upper case translation suppressed.

You can use the CEMT SET PROGRAM JVMPROFILE command or the EXEC CICS SET PROGRAM JVMPROFILE command to change the JVM profile from that specified on the installed PROGRAM resource definition. (If you use an EXEC CICS command to set the JVMPROFILE field, the value is always accepted in mixed case.) This enables you to change the JVM profile that a program uses during a CICS run, without having to re-install the PROGRAM resource definition. Any instances of the program that are currently running in a JVM with the old JVM profile are unaffected, and are allowed to finish running their current Java program. New instances of the program will use a JVM with the new JVM profile that you have specified.