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:
- Quiesce the workload.
- Shut down the region.
- Upgrade the region to CICS TS for z/OS, Version 3.1, following the standard migration
procedures described in this book.
- 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.
- Restart the region.
- 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.
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:
- 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:
- 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.
- 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.
- 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.
- 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:
- Applications are kept available throughout the upgrade process.
- 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.
- 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.
- 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:
- Applications are kept available throughout the upgrade process.
- 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:
- Checking that your logical server meets the criteria for a "rolling
upgrade". See Requirement.
- Preliminary steps
- Migrating the listener regions
- Migrating the AORs
- 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
- Review Migration tips.
- 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).
- 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.
- 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
- Quiesce a listener region and bring it down.
- Upgrade this single listener region to CICS TS for z/OS, Version 3.1, following the standard
migration procedures described in this book.
Important
- 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.
- 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.
- 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.
- Repeat steps 1 through 3 for all of the listener regions in the logical
server.
Migrating the AORs
- Quiesce an AOR and bring it down.
- 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
- 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.
- At this stage, don’t enable any new, CICS TS 3.1-specific,
options on resource definitions.
- Bring the AOR back up again.
- Ensure that all TCPIPSERVICEs are open both in this AOR and in the listener
regions.
- 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:
- Try to pick DJARs whose entire work load can be processed by a single
region.
- Wherever possible, all the beans used by an application should be migrated
at the same time. For example, if bean A is known to call bean B the two beans
should be migrated together. If this is not possible, bean A should be migrated
first.
This is particularly important if the beans are installed in the
same CorbaServer but in different AORs that are at different levels of CICS. This is because a CICS TS 2.2 region cannot do a JNDI look up of an object
in a CICS TS 3.1 region if both objects are in the same CorbaServer.
For example, bean A in CorbaServer EJB1 in a CICS TS 2.2 AOR cannot look up bean B in CorbaServer
EJB1 in a CICS TS 3.1 AOR.
Note:
If A and B are installed
in different CorbaServers, or in AORs that are at the same level of CICS, they can be
migrated separately.
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 :
- This AOR is ready to accept workload.
- The logical server contains a pool of CICS TS 2.2 AORs and a pool (currently containing
only one region) of CICS TS 3.1 AORs.
- Any clients that look up the IOR of a re-published bean in the name space
get the new IOR in CICS TS 3.1 format. Your customized routing program
or CICSPlex SM directs such requests to the CICS TS 3.1 AOR.
- Any clients that have a stale, cached, IOR for a bean that’s been
re-published are still able to use the bean. Your customized routing program
or CICSPlex SM directs such CICS TS 2.2-format requests to one of the CICS TS 2.2 AORs.
Note:
Many application servers cache the results
of JNDI lookups locally to increase performance, so you may find that these
caches have to be purged before the new IORs are used. Over a period of time,
requests for re-published enterprise beans should move gradually from the
pool of CICS TS 2.2 AORs to the pool of CICS TS 3.1 AORs.
- Repeat steps 1 through 5 for all of the AORs in the logical server. As
each AOR is upgraded:
- Re-publish a different set of enterprise beans, so that gradually more
and more beans are supported by the pool of CICS TS 3.1 regions.
- It becomes less important, when selecting deployed JAR files to re-publish,
to choose those whose entire work load can be processed by a single region--because
there are more AORs in the CICS TS 3.1 pool.
Eventually, all the AORs will be running CICS TS 3.1 and processing
100% of the workload.
Tidying up
- If required, reset the AUTOPUBLISH option on your CORBASERVER definitions
to YES.
- Enable any CICS TS 3.1-specific resource definition options that
you want to use.
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.
- 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.
- The default JVM profile used by CorbaServers in CICS TS 2.2 was DFHJVMPR. In CICS TS 3.1 it
is DFHJVMCD.
- 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.
- 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.
- 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:
- Retract the deployed JAR file from a CICS TS 3.1 AOR
- 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
- 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.
- 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.
- 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 ]]