PK37843: JDK 5.0 SUPPORT IN JAVA DEPENDENT REGIONS (JDRS)

APAR status

• Closed as new function.

Error description

• This IMS Service enhancement provides the following:
  1. JDK 5.0 support in Java Dependent Regions (JDRs).
  2. JDR / COBOL Interoperability support.
  
  Note - addidtional sympton :
     "DFSJVM00: Exception: java.lang.NoClassDefFoundError:
  
  DCR KZ00046
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED: All IMS V9 users of Java Dependent Regions   *
  *                 who need JDK 5.0 support.                    *
  *                                                              *
  *                 This maintenance requires at least JDK 1.5.0 *
  *                 SR4 maintenance level.                       *
  ****************************************************************
  * PROBLEM DESCRIPTION: JDK 5.0 is not supported by IMS V9 Java *
  *                      Dependent Regions.  This SPE provides   *
  *                      for JDK 5.0 support in IMS V9 Java      *
  *                      Dependent Regions.                      *
  *                                                              *
  *                      This maintenance requires at least JDK  *
  *                      1.5.0 SR4 maintenance level which is    *
  *                      PTF UK21775.                            *
  ****************************************************************
  * RECOMMENDATION: INSTALL CORRECTIVE SERVICE FOR APAR/PTF      *
  ****************************************************************
  DCR KZ00046
  This maintenance requires at least JDK 1.5.0 SR4 maintenance
  level which is PTF UK21775.
  
  JDK 5.0 support in Java Dependent Regions (JDRs)
  ------------------------------------------------
  In order to support JDK 5.0, remove the master/worker JVM model
  that was supported by JDK 1.4.2 and instead support a standalone
  JVM model in JMP and JBP regions.
  
  JDR/COBOL Interoperability
  --------------------------
  Also, IMS message GU/CHKP processing was altered for Java
  Dependent Regions (JDRs) when JDRs were initially implemented.
  For JDRs, an IMS message GU means "get the message only, do not
  perform syncpoint processing" and CHKP processing means "perform
  syncpoint processing only, do not get the next message".  In the
  standard IMS model, message GU and CHKP mean "perform syncpoint
  AND get the next message".
  
  Due to this behavioral change in standard IMS model message
  GU/CHKP processing, users wishing to take advantage of
  transactions using IMS Java and OO COBOL executing in a JDR and
  invoking legacy business logic written in COBOL are unable to do
  so without changing their existing legacy COBOL applications.
  
  Thus, this SPE will restore the standard IMS model GU/CHKP
  processing for JDRs.  This change will be transparent to
  existing user applications with the exception of the following:
  
  - If an application uses a U118 to enforce a rollback (for
    example, it detects a rollback situation and instead of
    driving the rollback just ends without doing a commit), the
    application will need to be changed to properly issue
    IMSTransaction.getTransaction() .rollback Relying on the U118
    for rollback processing is not a recommended programming
    technique.  This affects only JMP applications.
  
  - If an application directly calls CHKP using the low level Java
    API, the application will now receive the next input message
    as part of CHKP processing.  This affects only JMP appls.
  
  * * * * * * * * * RAS MODIFICATION * * * * * * * * * * * *
  
  This SPE also implements changes to the ENVIRON= member for JDRs
  that will allow the user to specify any environment variables in
  the form X=Y instead of being restricted to only specifying the
  LIBPATH=, DEBUG=, and JLEOPT= options.  The environment
  variables are presented as Java system properties at runtime and
  are therefore accessible by a Java application running in the
  JDR.  This is a RAS modification.
  

Problem conclusion

Temporary fix

Comments

• This maintenance requires at least JDK 1.5.0 SR4 maintenance
  level.
  -------------------------------
  The IMS JVM launcher, DFSJVM00, has been modified to remove the
  master/worker JVM support and provide a standalone JVM in order
  to support JDK 5.0.
  
  The program controllers and region controller for JBP/JMP
  regions have been modified to remove master/worker JVM support
  in order to support JDK 5.0 (DFSPCJB0, DFSPCJM0, DFSRCJM0) .
  
  DFSTMS00 has been modified to remove ABENDU0118.
  
  DFSFXC30, DFSCPY00 and DFSDLA00 have been modified to support
  the changes described under the JDR/COBOL Interoperability
  section above.
  
  DFSJJAR was modified to perform SYNC instead of CHKP for the IMS
  Java commit method.
  
  ****************** USER REFERENCES ***********************
  
  You can refer to the following user guide for more information
  on the SDK V5 JVM and to determine which JVM options are
  appropriate for your installation:
  
  "IBM 31-bit and 64-bit SDKs for z/OS, Java 2 Technology Edition,
  Version 5 SDK and Runtime Environment User Guide"
  
  Link to JDK V5 restrictions and other considerations doc:
  ---------------------------------------------------------
  http://www-03.ibm.com/servers/eserver/zseries/software/java/
  j5restrict31.html
  
  
  Link to JDK V5 doc that describes all the JVM options:
  ------------------------------------------------------
  http://www-03.ibm.com/servers/eserver/zseries/software/java/pdf/
  sdkguide.zos.pdf
  
  
  ****************** PUBS CHANGES **************************
  
  ---------------------------------------------------------------
  GC17-7831
  BOOK: Release Planning Guide
  ---------------------------------------------------------------
  Add a couple of statements indicating the behavior change of
  GU/CHKP processing for a JMP application and the removal of the
  U118 abend as follows:
  
  - If an application uses a U118 to enforce a rollback (for
  example, it detects a rollback situation and instead of driving
  the rollback just ends without doing a commit), the application
  will need to be changed to properly issue
  IMSTransaction.getTransaction() .rollback Relying on the U118
  for rollback processing is not a recommended programming
  technique.  This affects only JMP applications.
  
  - If an application directly calls CHKP using the low level Java
  API, the application will now receive the next input message as
  part of CHKP processing.  This affects only JMP applications.
  
  ---------------------------------------------------------------
  GC18-7827
  BOOK: Messages and Codes Volume 1
  ---------------------------------------------------------------
  Delete abend code 0118 (ABENDU0118)
  
  ---------------------------------------------------------------
  SC18-7821
  BOOK: Java Guide and Reference - section
  "Enterprise COBOL interoperability w/ JMP and JBP applications"
  ---------------------------------------------------------------
  Add the following statement:
  
  Users wishing to take advantage of transactions using IMS Java
  and OO COBOL executing in a Java Dependent Region and invoking
  legacy business logic written in COBOL can do so without
  changing their existing legacy COBOL applications.
  
  
  Delete ALL of the following lines:
  
  When Java is the front-end language, you must perform all
  message-queue and message-synchronization processing in Java.
  
  For example, you must call both the
  IMSMessageQueue.getUniqueMessage method (to read messages from
  the queue) and the IMSTransaction.getTransaction() .commit()
  method (to commit changes) before reading subsequent messages
  from the message queue or exiting the application.
  
  Important:
  Do not mix the languages that are used to read messages from the
  message queue or to commit resources.  The IMS Java library
  tracks the calls that are made in Java to ensure that the
  syncpoint rules are followed, but it does not track calls made
  in COBOL.
  
  The COBOL application must commit resources before reading
  subsequent messages or exiting the application.  A COBOL GU call
  does not implicitly commit resources when the program is running
  in a JMP or JBP region as it does when the program is running in
  an MPP region.
  
  Use Dl/I calls for message processing (GU and GN) and
  transaction synchronization (CHKP) . A CHKP call in a JMP or JBP
  region does not automatically retrieve a message from the
  message queue.
  
  ---------------------------------------------------------------
  GC18-7823
  BOOK: Installation Volume 2 - System Definition and Tailoring
  "Parameter descriptions for IMS supplied procedures"
  ---------------------------------------------------------------
  Delete JVMOPWKR= description and state this parm is now obsolete
  and ignored if specified.
  ===
  Delete DEBUG= parameter.  There is no debug version of
  JDK 5.0 like there was for JDK 1.4 (libjvm_g.so)
  ===
  Replace the description of JVMOPMAS= with the following:
  
  Sets the name of the member in IMS.PROCLIB that contains the JVM
  options for the standalone JVM for Java Dependent Regions (JBPs
  and JMPs) . member name is a maximum of 8 uppercase characters.
  
  This JVM options member must contain the following:
  
  o Specify -Xoptionsfile=<HFS JVM properties file> and then
    specify the -Djava.class.path=<application class path> option
    in the options file. -Xoptionsfile allows you to specify
    pathnames greater than 255 characters in length on the
    -Djava.class.path option.
  
    OR
  
  o Specify -Djava.class.path=<application class path> directly in
    this member.
  
  Specify the path name (or path names) of your IMS Java
  application class files.  If your .class files are contained in
  a .jar file, the path name to the .jar file must be fully
  qualified, including the name of the .jar file.
  
  Comments are supported for this options member.  The comments
  begin with an asterisk (*) in the first column.
  
  Each line in the options file must not be longer than 72 bytes,
  including the continuation mark.  Use a greater-than symbol (>)
  at the end of the line as a continuation character.
  
  If you do not use the -Xoptionsfile JVM option, path strings can
  be a maximum of 255 bytes in length (any characters over 255
  bytes will be ignored) . A path string can be one path name or
  several path names.  If you are specifying multiple path names,
  separate each by a colon (:) .
  
  The sample member, DFSJVMMS, demonstrates how to specify the JVM
  options for Java Dependent Regions (JBPs and JMPs)
  
  ====
  Add following to description of ENVIRON=:
  
  Environment variables in the form X=Y can be specified where X
  is the environment variable and Y is the value of the
  environment variable.  For example, you can specify
  JAVA_DUMP_OPTS=ONINTERRUPT(ALL),ONANYSIGNAL(ALL) in the member
  and IMS will set the environment variable "JAVA_DUMP_OPTS" to
  the value "ONINTERRUPT(ALL),ONANYSIGNAL(ALL)".
  

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

  PK56409 UK32054 UK32055

Modules/Macros

• DFSCPY00 DFSDLA00 DFSFXC30 DFSJJAR  DFSJVM00
  DFSPCJB0 DFSPCJM0 DFSRCJM0 DFSTMS00 PARMBLK
  

Fix information

• Fixed component name

  IMS V9

• Fixed component ID

  5655J3800

Applicable component levels

• R900 PSY UK32054

     UP07/12/14 P F712