SJ domain: Design overview

The process by which CICS creates JVMs and allocates them to requests is described in "About JVMs" in Java™ Applications in CICS®. This design overview looks at that process from a more technical viewpoint.

The actions that CICS takes when a Java program is invoked are as follows:

  1. When the Java program is started, the Program Manager (PG) domain recognizes from the PROGRAM resource definition that it is a Java program. It calls the APLJ gate's START_PROGRAM function, which calls the SJIN gate's INVOKE_JAVA_PROGRAM function in the JVM domain.
  2. The INVOKE_JAVA_PROGRAM function determines if the program is to run in CICS key or in user key (from the EXEC_KEY input parameter), and calls the Dispatcher (DS) domain's CHANGE_MODE function to move the task to either a J8 TCB (for CICS key) or a J9 TCB (for user key).
  3. The Dispatcher domain looks for an existing J8 or J9 TCB, in the pool of JVM TCBs (the JVM pool), that matches the execution key and the JVM profile (JVM_PROFILE_NAME input parameter) requested by the program. "How CICS allocates JVMs to applications" in Java Applications in CICS explains the selection mechanism that the Dispatcher domain uses to decide whether to assign the request an existing, matching TCB, or to assign the request a new TCB, or to destroy and re-create an existing, mismatching TCB, or to make the request wait. If the Dispatcher domain assigns the request a new TCB or a re-created TCB, steps 4 and 5 of this process must now be performed. If the Dispatcher domain assigns the program request an existing, matching TCB, steps 4 and 5 are omitted, and the request re-enters the process at step 6.
  4. If the Dispatcher domain assigns the request a new TCB or a re-created TCB, the JVM (SJ) domain must build a JVM on the TCB. To do this, it obtains storage in the appropriate key from the Storage Manager (SM) domain to keep its representation of the TCB. The address of this storage is used as a token, and returned to the Dispatcher domain for it to track. The SJ domain calls Language Environment using the Language Environment preinitialization module CEEPIPI (in the Application (AP) domain). CEEPIPI starts a Language Environment enclave on the TCB. "The structure of a JVM" in Java Applications in CICS explains more about the relationship between the Language Environment enclave and the JVM.
  5. The SJCS program (a CICS program written in C) runs in the Language Environment enclave. It processes the JVM profile (JVM_PROFILE_NAME input parameter) and the associated JVM properties file for the request, to build a JVM with the appropriate attributes. "How CICS creates JVMs" in Java Applications in CICS explains what attributes of a JVM can be specified in its JVM profile and JVM properties file. If the JVM profile indicates that this JVM is to use the shared class cache (that is, it is a worker JVM), a call is made to the shared class cache to obtain the token for the currently active JVMset. "The shared class cache" in Java Applications in CICS explains more about the relationship between worker JVMs and the shared class cache. The JNI function JNI_StartJavaVM is then used to start the JVM, and this call returns two JVM tokens, which are stored in a SJ control block for later use. The JVM has now been created, and the SJCS program returns to SJIN.
  6. If the Dispatcher domain assigned the program request an existing, matching TCB, which has a JVM that has already been created, the request re-enters the process at this point. The SJ domain now calls another C subroutine to invoke the Wrapper class. The wrapper loads required DLLs (to support CICS' native methods) and output redirection classes, then it calls our user class (the Java program), as specified by the USER_CLASS input parameter.
  7. When the user class (the Java program) returns, if the option REUSE=RESET was specified in the JVM profile, creating a resettable JVM, a JVM reset is attempted. "How JVMs can be reset for reuse" in Java Applications in CICS has more information about the conditions that must be met for a JVM to be reset, and why sometimes they cannot be reset. If the JVM reset is attempted but fails, the JVM and the Language Environment enclave are destroyed, but the TCB is not destroyed (unless the JVM failed with an abend). If the JVM reset succeeds, the JVM and TCB are ready for reuse, and the Dispatcher domain can assign them to another program request (as described in step 3). If the option REUSE=YES was specified in the JVM profile, creating a continuous JVM, a JVM reset is not attempted, and the JVM and TCB are ready for reuse as soon as the user class returns (unless garbage collection is taking place in the JVM). If the option REUSE=NO was specified in the JVM profile, creating a single-use JVM, the JVM is not made available for reuse, but instead the JVM and the Language Environment enclave are destroyed as soon as the user class returns.

The other functions provided by the JVM domain are to do with the management of the JVM pool (the pool of J8 and J9 TCBs that are used to build JVMs to service Java program requests), and of the shared class cache. "How CICS manages JVMs in the JVM pool" in Java Applications in CICS explains the part CICS plays in this process, and "Managing the shared class cache" and "Managing your JVMs" in Java Applications in CICS describe the functions that system administrators can use.

[[ Contents Previous Page | Next Page Index ]]