[Version 5.0.2 and later]Migrating from V4.0.1

Before you begin

Determine whether you have an existing version of WebSphere Application Server installed on the machine where you plan to install your Version 5 product.

Why and when to perform this task

To migrate from Version 4.0.1 applications and configurations to Version 5, follow this procedure:

Steps for this task

  1. Prepare to migrate or update product prerequisites and corequisites to supported versions.

    If your existing configuration makes use of a non-390 Web server and associated AE plug-in, you should review the required Web server levels and update as appropriate. Refer to IBM WebSphere Application Server supported hardware, software, and APIs for current requirements.

    Functional dependencies on the 390 infrastructure have changed. See Prerequisites needed for WebSphere Application Server for z/OS comparing Version 3.5 SE, Version 4.0.1, Version 5.0, and Version 5 prerequisites.

    Version 4.0.1 must be at minimum service level W401501 to coexistence with Version 5.

  2. Review existing Version 4.0.1 environment for possible coexistence issues related to port definitions and placement of WebSphere Application Server modules in LPA.

    See Migrating and coexisting for more information.

  3. Install the Version 5 product, which requires the use of SMP/E 3.1.

    Installation instructions have been provided with your ServerPac or PDO order.

  4. Customize Version 5 utilizing the customization dialog provided with the product and verify success by running the Installation Verification Test.

    Note that the Version 5 default /install root directory on z/OS is WebSphere/V5R0M0/AppServer, and it does not conflict with mount points or directory structure of the existing Version 4.0.1 release.

  5. Run the Version 5 samples.

    With the introduction of Version 5, significant changes to Admin, system structure, etc. were introduced. For this reason, it is always recommended the new samples are run to experience the environment.. See Samples Gallery for more information.

  6. Define the new servers for applications being migrated.

    Version 5 requires the use of the HTTP transport, and HTTP listening ports must be selected so as to not conflict with the existing Version 4.0.1 configuration.

    • There is no tooling support for migrating server configurations because of the massive change in the Administration console support between Version 4.0.1 and Version 5. This process will need to be done manually. Use the Version 4.0.1 administrative console capability to to dump existing Version 4.0.1 settings for review. See Utilizing WebSphere administrative capabilities to support migration from V4.0.1 for more information.
    • Establish a naming convention that lends itself to changes and extensions when establishing server configurations.
    • Create copies of policies such as WLM and ARM and modify them for the Version 5 server configuration.

  7. Install resources into the Version 5 server.

    Prerequisites levels needed for WebSphere Application Server for z/OS may have changed from Version 4.0.1. Review these prerequisites at Prerequisites needed for WebSphere Application Server for z/OS.

  8. Move applications to Version 5 level tooling.

    Most Version 4.0.1 applications will continue to run in the new servers. However, applications generated in WSAD 4.0 and WSAD IE 4.1.1 are not formally supported for deployment into Version 5 runtimes. Formal support necessitates movement of the application to Version 5 level tooling. In the case of WSAD 5.1, this tool has the flexibility to generate both J2EE 1.2 and J2EE 1.3 applications allowing convergence to a single tool to support Version 4.0.1 and Version 5. In the case of WSAD IE 5.1, there are conflicts in tooling jars with WSAD IE 4.1.1. Customers will need to maintain both tooling levels until they have migrated everything to the latest levels.

  9. Review applications to be migrated to determine if any changes are required.

    The Class API checker tool can be used to analyze servlets and EJBs to determine if any APIs are unsupported or deprecated. The CACT tool can be found at WebSphere Developer Domain downloadable tools. If required changes are found, it will be necessary to modify them and then install into the Version 5 servers. If changes are not required, then the migration utility can be utilized.

    Key things to note that may cause a need for application changes include the following:

    • The default code page has changed to be consistent with the Version 5 family. In Version 5.0 and above, the JVM is started with a default file encoding of iso-8859-1 (US ASCII). This enables applications that rely on JVM behavior instead of explicit specification of encoding to execute unchanged on a WebSphere Application Server for z/OS Version 5 system. This should improves portability of applications across platforms.

      Even though the Java language allows programmers to explicitly specify the encoding of a file that is to be opened and read by the JVM, many programmers do not take advantage of this capability and rely on the default encoding. If you have applications which access EBCDIC encoded files, you must ensure that they explicitly specify this encoding in the application code, or you must change the encoding of the target file to match this new JVM setting.

    • JCA connector applications developed using WSAD IE 4.1.1 to create an atomic JCA connector Web service that communicates to a back-end resource manager should still be able to run under Version 5. To do so, however, one must first redeploy the application to Version 5. The redeploy can be done during the installation of the application. Although, these applications should run under Version 5 after redeploying, this should be viewed as a temporary method of operation. Customers should still eventually transition their WSAD IE 4.1.1 JCA connector applications to the WSAD IE 5 tooling.
    • There are cases where Web Applications may need to be modified. See Migrating Web application components for more information.

  10. Utilize the migration utility that was shipped in W401502 to process Version 4.0.1 EARs.

    This utility is being provided as an option on 390fy. In Version 4.0.1 it was required that EARs be processed through the 390 AAT or 390fy to condition them for deployment into Version 4.0.1. In Version 5, and higher, this conditioning is not required. This utility will remove the conditioning that was done for existing Version 4.0.1 EARs that are being migrated. It should be noted that if the application is being sent back through the WSAD 5.0, or later version tooling, that the resulting EAR is ready for installation into Version 5 and that the use of migration utility is not required. Support for migrating Version 4.0.1 applications to Version 5 has been shipped in Version 4.0.1 service (W401502). This support has been provided as a new -v5mp option for the 390fy tool. See Utilizing WebSphere administrative capabilities to support migration from V4.0.1 for more information.

  11. Address differences between Version 4.0.1 and Version 5 by use of the AAT.

    • Review the changes in the classloader options in Version 5 compared to Version 4.0.1. Determine the new option that is appropriate and utilize the AAT to make the change. See Migrating the class-loader Module Visibility Mode setting for more information.
    • A change was made in the web container behavior that was required by J2EE that involves the setting of content type. If a servlet writer does not set the content type it is no longer defaulted by the web container and it is returned as "null". This can cause some browsers to incorrectly display the resulting tags sent by the web container. This problem can be eliminated by using the AAT to set the autoResponseEncoding IBM extension to true for web modules while migrating enterprise applications.

  12. Install the application into the Version 5 server.

    For Web applications being migrated from Version 4.0.1 the following should be noted. In Version 4.0.1, the classes generated from JSP files are in a package based on the directory structure of the WAR. Any JSP at the top of the context root is in the unnamed package, and JSP files in subdirectories of the root are in packages named after the subdirectories. In Version 5, and higher, the classes generated from JSP files are all in the package org.apache.jsp. Therefore, the classfiles are not compatible between versions. When migrating an enterprise application from Version 4.0.1 to Version 5, the JSP files need to be recompiled so that the classfiles are regenerated into the correct packages. Use the -preCompileJSPs option of wsadmin tool during the installation of the application to force this recompiling.

  13. Migrate clients for the applications that have been migrated to the Version 5 server.

    Update clients that reference EJBs.
    The naming structure changed in Version 5. As a result the EJB references that were valid in previous versions no longer work in Version 5 or higher. Existing Version 4.0.1 clients will need to be changed appropriately. Alternatively, a name binding can be added to map the old name into the new name in Version 5. If you pick this alternative, you can find some helpful examples in the IBM Redbook, Migrating to WebSphere V5.0: An End-to-End Migration Guide, SG24-6910-00. There is a link to the book in the Resources for Learning topic.
    Update data resources for client enterprise applications.
    The client container supported by Version 4.0.1 utilized a WebSphere Configuration API model that is different from the one used by Version 5 and higher. As a result, data resources will need to be converted to run correctly with Version 5 or later versions.

  14. Update your Web server to the Version 5 prerequisite level and the appropriate plug-in.

    Most Version 4.0.1 configurations will include a Web server. This can be a 390 Web server or any Web server supported by Version 4.0.1 AE. If a Web server configuration is required, then the Web server to be used must be updated to the Version 5 prerequisite level and the appropriate plug-in must be installed. It should be noted that the Version 5 plug-in can support both Version 4.0.1 and Version 5 application servers. With this in mind, several migration configurations are possible:

    • Install the Version 5 plug-in into the existing Web server (the Version 4.0.1 plug-in and Version 5 plug-in coexist).
    • Create a unique Web server instance and install the Version 5 plug-in.
    • Replace the Version 4.0.1 plug-in with the Version 5 plug-in and setup to drive both the Version 4.0.1 and Version 5 images.
    See Setting up Version 4.0.x and Version 5.x coexistence for more information.

  15. Migrate the existing Version 4.0.1 security configuration for the applications that have been migrated.

    See Migrating security configurations from WebSphere Application Server Version 4.0.1 for more information.

  16. Make the necessary operational changes to support production.

    See the Operations and Administration Guide for more information.
  17. Post migration activities.

What to do next

Migration from Version 4.0.1 to Version 5 does not require extensive tuning.

Migration from Version 3.5 SE to Version 5 does require you to examine the migrating applications.

After planning for migration and coexistence, you are ready to continue the installation.


Related concepts
Migrating
Related reference
Migrating and coexisting
Coexistence port definitions



Searchable topic ID:   tins401z
Last updated: Jun 21, 2007 9:56:50 PM CDT    WebSphere Application Server for z/OS, Version 5.0.2
http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp?topic=/com.ibm.websphere.zseries.doc/info/zseries/ae/tins_401z.html

Library | Support | Terms of Use | Feedback