Migrating an EJB server to CICS TS for z/OS, Version 3.1

Upgrading a single-region CICS EJB/CORBA server

To migrate a single-region CICS® EJB/CORBA server from CICS TS for z/OS, Version 2.2 to CICS TS for z/OS, Version 3.1:

  1. Quiesce the workload.
  2. Shut down the region.
  3. Upgrade the region to CICS TS for z/OS, Version 3.1, following the standard migration procedures described in this book.
  4. Review Migration tips, which describes some of the changes in EJB/CORBA support between CICS TS for z/OS, Version 2.2 and CICS TS for z/OS, Version 3.1. You should also refer to the "Setting up a single-region EJB server" section in Java™ Applications in CICS, which describes in detail how to set up a single-region EJB server in CICS TS for z/OS, Version 3.1.
  5. Restart the region.
  6. Republish the Interoperable Object References (IORs) for all the enterprise beans and stateless CORBA objects processed by the server. To do this, issue a PERFORM CORBASERVER(CorbaServer_name) PUBLISH command. This command can be issued using EXEC CICS, CEMT, the Resource Manager for enterprise beans, or from a CICSPlex SM EUI or WUI view. Remember to issue a separate command for each CorbaServer in the region.

Upgrading a multi-region CICS EJB/CORBA server

To migrate a multi-region CICS EJB/CORBA server from CICS TS for z/OS, Version 2.2 to CICS TS for z/OS, Version 3.1, you can use any of the following methods:

  1. Shut down the server, upgrade all the regions, and restart the server.

    This approach is very similar to that described in Upgrading a single-region CICS EJB/CORBA server, except that:

    1. You must upgrade all the regions to CICS TS for z/OS, Version 3.1 before restarting the server. Again, follow the standard migration procedures described in this book.
    2. You should refer to the "Setting up a multi-region EJB server" section in Java Applications in CICS, which describes in detail how to set up a multi-region EJB server in CICS TS for z/OS, Version 3.1.
    3. To republish the IORs of enterprise beans and stateless CORBA objects, issue a PERFORM CORBASERVER(CorbaServer_name) PUBLISH command on at least one of the AORs. Remember to issue a separate command for each CorbaServer in the AOR.

    The advantage of this approach is its relative simplicity, compared to solutions 2 and 3. Its main disadvantage is that the server’s applications are unavailable during the upgrade process.

  2. Create a separate, CICS TS for z/OS, Version 3.1, logical server and gradually migrate applications from the old, CICS TS 2.2, server to the new one.

    The advantages of this approach are:

    1. Applications are kept available throughout the upgrade process.
    2. You can start with a minimal CICS TS for z/OS, Version 3.1 server, perhaps consisting of just two regions--one listener and one AOR. As more applications are migrated, you can expand the CICS TS for z/OS, Version 3.1 and simultaneously reduce the number of regions in the CICS TS 2.2 server, thereby conserving resources.
    3. It is probably easier to implement than solution 3.

    To set up a new CICS TS for z/OS, Version 3.1 multi-region EJB server, follow all the steps in the "Setting up an EJB server" chapter in Java Applications in CICS.

  3. Perform a "rolling upgrade".

    In a "rolling upgrade", one region at a time is upgraded from the previous to the current level of CICS, while keeping the server operational.

    The advantages of this approach are:

    1. Applications are kept available throughout the upgrade process.
    2. Unlike solution 2, at no stage is it necessary to set up additional CICS regions.

    This method is described in detail in Performing a "rolling upgrade".

Performing a "rolling upgrade"

Important

The mixed level of operation described in this section, in which different CICS regions in the same logical server are at different levels of CICS, is intended to be used only for rolling upgrades. It should not be used permanently, because it increases the risk of failure in some interoperability scenarios. The normal, recommended, mode of operation is that all the regions in a logical sever should be at the same level of CICS and Java.

This section describes how to perform a "rolling upgrade" of a multi-region CICS EJB/CORBA server from CICS TS for z/OS, Version 2.2 to CICS TS for z/OS, Version 3.1. The process consists of the following steps:

  1. Checking that your logical server meets the criteria for a "rolling upgrade". See Requirement.
  2. Preliminary steps
  3. Migrating the listener regions
  4. Migrating the AORs
  5. Tidying up
Requirement

Your server must consist of separate listener and application-owning regions. This is because the migration process requires all of the listener regions to be updated before any of the application-owning regions (AORs). If you run composite listener/AORs, which act both as request receivers and request processors, this cannot be done. And if you don’t upgrade all the listeners before any of the AORs, your IIOP client applications may receive transient failures during the migration window, depending on the CICS version of the listener region that receives the request.

Preliminary steps

  1. Review Migration tips.
  2. Ensure that APAR PQ 79565 is installed in all your CICS TS 2.2 regions. This APAR improves CICS TS 2.2 diagnostics, should CICS TS 3.1 workload arrive at a CICS TS 2.2 region. It also allows a CICS TS 2.2 request processor (AOR) to receive work from a CICS TS 3.1 request receiver (listener).
  3. Set the AUTOPUBLISH option on all your CORBASERVER definitions to NO. Setting a CorbaServer to autopublish IORs into the JNDI name spaces could disrupt the migration process.
  4. If you use a distributed routing program to balance method requests for enterprise beans and CORBA stateless objects across the AORs of your logical server, customize your routing program to use the DYRLEVEL parameter. DYRLEVEL is a migration aid. It contains the level of CICS required in the target AOR to successfully process the routed request. (Note that this is the specific--not the minimum--level of CICS required to process the request successfully.) In a mixed-level logical server, when your routing program is invoked for route selection (or route selection error), it can use the value of DYRLEVEL to determine whether to route the request to a CICS TS 2.2 or CICS TS 3.1 AOR.

    For details of how to use DYRLEVEL, and definitive information about writing a distributed routing program, see the CICS Customization Guide.

    Install your customized program on all the regions (both listeners and AORs) of the EJB server.

    If you use CICSPlex SM to workload-balance method requests you can skip this step. The CICSPlex SM routing program supplied with CICS TS for z/OS, Version 3.1 checks the DYRLEVEL field and routes requests accordingly.

Migrating the listener regions

  1. Quiesce a listener region and bring it down.
  2. Upgrade this single listener region to CICS TS for z/OS, Version 3.1, following the standard migration procedures described in this book.
    Important
    1. When you upgrade the CSD from CICS TS 2.2 to CICS TS 3.1 level, if it is shared by any CICS TS 2.2 regions other than that being upgraded, include the DFHCOMPA resource group (supplied with CICS TS 3.1) in the startup group list of these regions. DFHCOMPA is a compatibility group that provides a definition of DFJIIRP, the default request processor program, that can be used by a CICS TS 2.2 region when sharing a CICS TS 3.1 CSD.

      This step is necessary because, in CICS TS 3.1, the JVM profile used by DFJIIRP is DFHJVMCD. In CICS TS 2.2, it is DFHJVMPR.

    2. At this stage, don’t enable any new, CICS TS 3.1-specific, options on resource definitions, because they won’t be understood by the CICS TS 2.2 AORs. Use of these new features must wait until the whole logical server--both listener regions and AORs--has been upgraded.

    For definitive information about setting up a listener region in CICS TS 3.1, refer to Java Applications in CICS.

  3. Bring the listener back up. This region is now at the newer version of CICS but may continue to participate as part of the back-level logical server.
  4. Repeat steps 1 through 3 for all of the listener regions in the logical server.
Migrating the AORs

  1. Quiesce an AOR and bring it down.
  2. Update this single AOR to CICS TS for z/OS, Version 3.1, following the standard migration procedures described in this book. Part of this will involve updating the JVM profile used by the CorbaServers. Note the changes to JVM profiles and property files described in Migration tips.
    Important
    1. When you upgrade the CSD from CICS TS 2.2 to CICS TS 3.1 level, if it is shared by any CICS TS 2.2 regions other than that being upgraded, include the DFHCOMPA resource group (supplied with CICS TS 3.1) in the startup group list of these regions.
    2. At this stage, don’t enable any new, CICS TS 3.1-specific, options on resource definitions.
  3. Bring the AOR back up again.
  4. Ensure that all TCPIPSERVICEs are open both in this AOR and in the listener regions.
  5. Use the CEMT PERFORM DJAR PUBLISH command to re-publish the IORs of one or more enterprise beans in CICS TS 3.1 format. For each CorbaServer, select one or more deployed JAR files to re-publish. When choosing deployed JAR files to re-publish, bear the following in mind:

    Re-publish the selected DJARs to the JNDI name space, in the same location as that used by the CICS TS 2.2 AORs.

    At this point :

  6. Repeat steps 1 through 5 for all of the AORs in the logical server. As each AOR is upgraded: Eventually, all the AORs will be running CICS TS 3.1 and processing 100% of the workload.
Tidying up
  1. If required, reset the AUTOPUBLISH option on your CORBASERVER definitions to YES.
  2. Enable any CICS TS 3.1-specific resource definition options that you want to use.

Migration tips

This section briefly lists some of the ways in which EJB and Java support has changed between CICS TS for z/OS, Version 2.2 and CICS TS for z/OS, Version 3.1. All these changes are described in detail in Java Applications in CICS. They are listed here, together with some general tips, as a reminder of things to be aware of when migrating an EJB server from CICS TS 2.2 to CICS TS 3.1.

  1. In CICS TS 2.2, JVM profiles were stored in a PDS member. In CICS TS 3.1, they are stored in the HFS directory pointed to by the JVMPROFILEDIR system initialization parameter.
  2. The default JVM profile used by CorbaServers in CICS TS 2.2 was DFHJVMPR. In CICS TS 3.1 it is DFHJVMCD.
  3. The default JVM properties file used by CorbaServers in CICS TS 2.2 was dfjjvmpr.props. In CICS TS 3.1 it is dfjjvmcd.props.
  4. Don’t enable any new, CICS TS 3.1-specific, attributes on resource definitions during a "rolling upgrade". For example, on a CORBASERVER definition don’t specify the ASSERTED option. (For a complete list of new, CICS TS 3.1-specific, attributes on CORBASERVER, DJAR, REQUESTMODEL, and TCPIPSERVICE resource definitions, see New resource definition types and new attributes.) Use of these new features must wait until the whole logical server--both listener regions and AORs--has been upgraded.
  5. From a CICS TS 3.1 AOR, you can re-publish a deployed JAR file that has previously been published from a CICS TS 2.2 AOR without first retracting it. The IORs of the beans are updated to CICS TS 3.1 format. However, you cannot do the reverse. From a CICS TS 2.2 AOR, before re-publishing a deployed JAR file that has previously been published from a CICS TS 3.1 AOR you must first retract it; furthermore, because CICS TS 2.2 does not understand the format of CICS TS 3.1 IORs, you must retract it from a CICS TS 3.1 AOR.

    Bear this in mind if, for any reason, you need to back out the upgrade of one or more AORs. If you ever need to revert the IORs of enterprise beans that have been published from a CICS TS 3.1 AOR to CICS TS 2.2 level (so that they can be routed to a CICS TS 2.2 AOR once more) you must:

    1. Retract the deployed JAR file from a CICS TS 3.1 AOR
    2. Publish the deployed JAR file from a CICS TS 2.2 AOR

    Trying to re-publish the beans without retracting them first, or trying to retract them from the wrong level of CICS, results in an InvalidUserKeyException: Bad version number exception.

Potential problems

  1. After the EJB server has been migrated to CICS TS 3.1, some clients may have stale, cached, IORs that point to the old server. This is because some application servers cache the results of JNDI lookups locally to increase performance. You may find that these caches have to be purged before the new IORs are used.
  2. CICS TS 3.1 supports GIOP 1.2, whereas CICS TS 2.2 supported only GIOP 1.1. If a GIOP 1.2 message is received in a CICS TS 2.2 region it will be rejected. Under normal conditions this should never happen, because the maximum version of GIOP supported by CICS is stored in the IORs that CICS publishes. If a client knows that a given server only supports GIOP 1.1, it will never attempt to use anything more recent when communicating with that server. This means that CICS TS 3.1 can send GIOP messages to CICS TS 2.2.

    The problem will only occur if the client thinks it is talking to CICS TS 3.1 but its message is routed to a CICS TS 2.2 region. This will only happen if CICS TS 2.2 and CICS TS 3.1 regions are set up as sibling request processors (AORs) in the same logical server. (This is one reason why mixed-level logical servers are not recommended in CICS.) During a "rolling upgrade", the logical server does, of course, contain mixed-level request processors. However, if you follow the steps in Performing a "rolling upgrade", the problem (of a GIOP 1.2 message being received in a CICS TS 2.2 region) will not occur.

  3. CICS TS 3.1 uses a different format of IOR from CICS TS 2.2. If a GIOP 1.1 message intended for CICS TS 3.1 is routed to a CICS TS 2.2 region, the CICS TS 2.2 region will reject the request due to a unknown IOR format being in use. If all the regions in an EJB/CORBA server are at the same level of CICS and Java, this error cannot occur.

    During a "rolling upgrade", the logical server does, of course, contain mixed-level regions. However, if you follow the steps in Performing a "rolling upgrade", this problem will not occur.

[[ Contents Previous Page | Next Page Index ]]