Migrating from V3.5 Standard Edition (SE)

Before you begin

Determine whether you have WebSphere Application Server for OS/390 V3.5 Standard Edition installed on the system where you plan to install your Version 5 product. If you are interested in utilizing the Simple Configuration Option for V4.0.1, then the content in this article will apply to you.

Why and when to perform this task

To migrate V3.5 Standard Edition (hereafter referred to as V3.5SE) 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.
    Significant functional dependencies on the z/OS infrastructure have been added to the new product over those that had been required for V3.5SE. See Prerequisites needed for WebSphere Application Server for z/OS comparing V3.5SE, V4.0.1, V5 prerequisites. Review the PSP bucket for the latest PTF information.

    Unlike V3.5SE, V5 and higher for the z/OS platform allows distributed platform Web servers for distributed platforms to communicate with the WebSphere Application Server for z/OS product. Refer to IBM WebSphere Application Server supported hardware, software, and APIs for supported distributed platform Web servers.

  2. Install the new Application Server product.

    Note: V5, and higher, requires the use of SMP/E 3.1. Installation instructions have been provided with your ServerPac or PDO order.

  3. Customize the product by utilizing the customization dialog, which is provided, and verify success by running the Installation Verification Test.
    The customization dialog will prompt you for various TCP/IP ports that the Application Server should listen on for requests. You should ensure that you configure the new application server not to make use of the same ports as an existing server on that same image.

    Note: V5, and higher, does not conflict with the mount points or directory structure of the existing V3.5SE release.

  4. Run the samples provided with the new product.
    There have been significant changes to Admin, system structure, etc. and for this reason, it is recommended to run the samples. See Samples Gallery for more information.
  5. Define the new servers for applications being migrated.

    There is no tooling support for migrating Server configurations because of the massive differences in application packaging/deployment, server structure/architecture, application administration compared to V3.5SE. This process will need to be done manually. Some key differences that should be noted:

    • The servlet engine provided by V3.5SE has been replaced by a full J2EE WebContainer.
    • The WAS.CONF file has been eliminated. All configuration that was previously done through the WAS.CONF is now done through the J2EE tooling (WSAD, Application Assembly Tool, and the adminstrative console). See Migrating your existing was.conf file settings for more information.
    • The configuration is no longer restricted to running as a GWAPI out of the IBM HTTP Server for z/OS and OS/390. V5 and higher include HTTP Transport function as part of the server structure. A default internal transport is provided, but a specific HTTP transport can also be configured using the administrative console. HTTP listening ports must be selected so as to not conflict with existing V3.5SE configuration. Because of the HTTP Transport function, customers now have three configuration options:
      1. Allow direct HTTP access to the J2EE server via the HTTP transport
      2. Utilize IBM HTTP Server V5.3 for z/OS and OS/390 with the WebSphere HTTP Plug-in for z/OS to front end the HTTP transport. This option requires new ServerInit, Service, and ServerTerm directives to be added to the HTTP server httpd.conf file. See The WebSphere Application Server for z/OS HTTP internal transport for more information.
      3. Utilize any V5 and higher supported distributed platform Web server, along with the appropriate WebSphere plug-in for Web servers, to front end the HTTP transport.

      Note: HTTP Transport is not a complete replacement for the IBM HTTP Server for z/OS. HTTP Transport has limited function when compared to IBM HTTP Server for z/OS.

    • When establishing server configuration, care should be taken to establish a naming convention that lends itself to changes and extensions.
    • Create WLM and ARM policies for the Servers as part of the server configuration.

  6. Install resources into the new server.

    Note: Prerequisites levels needed for WebSphere Application Server for z/OS may have changed from V3.5SE. Review these prerequisites at Prerequisites needed for WebSphere Application Server for z/OS.

  7. Create new DB2 tables if your application uses HTTP Session State Persistence.
    The format of the DB2 tables needed to support HTTP Session State persistence has changed in V5. Consequently HTTP sessions can not be shared between V3.5SE and V5 and higher. If your application uses HTTP Session State Persistence using DB2, you must create new tables. See Creating a DB2 table for session persistence for more information.
  8. Review the existing security configuration for Web applications.
    The authentication and authorization policy for URLs within J2EE Web applications has the ability to be fully described by the web.xml deployment descriptor. The web.xml file is contained in the Web application archive (.war) file. The war file is deployed into the WebSphere Application Server for z/OS J2EE Server. The enforcement of the rules at runtime is carried out by the Web container in the J2EE Server in conjunction with the configured user registry, such as SAF or LDAP. Implementing a security policy for the installation consists of the deployer granting permission for users and groups to be in various ROLEs that are described in the deployment descriptor of the application. At runtime, the Web container will authenticate the user using the means in the deployment descriptor and will subsequently insure that either the authenticated user, or a group in which he is a member, has been granted access to the necessary J2EE Roles by the deployer. For more information on J2EE Security, please see Migrating security configurations from WebSphere Application Server Version 4.0.1.

    The V3.5SE server executes as a GWAPI plug-in within the address space of an IBM HTTP Server for z/OS. Security policy for URLs (including those that get serviced by the WASv3.5SE plugin) that are served from the Web server are configured using the security directives in the httpd.conf file of that Web server. At runtime, the Web server is able to authenticate the user to the configured security server such as RACF or LDAP and determine if the user or a group that the user is a member of has been granted access to the specified URL before allowing access.

    In order to migrate Web applications and their security policy from V3.5SE, as well as execute the server independent of the existing Web server, you need to insure that the deployment descriptor for the Web applications being migrated contains security constraints that match what currently exists within the httpd.conf. It is recommended to make use of the deployment descriptors within the Web application as a means for describing the security policy of the application.

    V3.5SE does provide extended capability to supplement the Web server authorization processing by performing SAF checks against resources profiles that are defined in the SOMDOBJS facility class. If your existing V3.5SE servers use this capability, you will need to insure that you understand the policy and configure the equivalent within the deployment descriptor.

  9. Move applications to the new product level tooling.
    WSAD 4.0 and WSAD IE 4.1.1 generated applications are not supported for deployment into V5 and higher runtimes. This necessitates movement of the application to V5 and higher level tooling. You can also find information about migrating to the V5 tooling levels in the IBM Redbook, Migrating to WebSphere V5: An End-to-End Migration Guide, SG24-6910-00. There is a link to the book in the Resources for Learning topic.
  10. Review applications to be migrated to determine if any changes are required. See Migrating Web application components for more information.
    Some of the areas to review are:
    • Update application to supported specification level. V3.5SE provided a compatibility option allowing the use of Servlet 2.1/JSP 1.0 levels. Servlets/JSPs must be brought up to at least the minimal level that is supported by J2EE 1.4.1 (Servlet 2.2/JSP 1.1). The MigrateWC tool has been provided to assist in conversion of JSPs and Servlets coded at specification levels of previous WebSphere versions. The MigrateWC tool can be found on the WebSphere Developer Domain downloadable tools Web site at http://www.ibm.com/software/.
    • Repackage application as a J2EE application. V3.5SE did not require J2EE packaging. In V5 and higher, Web applications must be packaged as WAR/EAR files for deployment into a V5, and higher, webcontainer. J2EE packaging includes the declaration of application properties through deployment descriptors that are contained in a separate xml file. WSAD/WSAD IE tooling provides this packaging capability.
    • Migrate Common Connector Framework (CCF) into a J2C connector application, if applicable. The CCF function is a deprecated function, but is still supported in the V5 runtime only. The intent is to support users in a migration to J2C. The WebSphere Developer Domain has a series of 3 part articles that address the tooling, the Application Server, and the migration path from CCF to J2C, entitled CCF to J2C migration.
    • Review classloader options. V3.5SE provided a single class loader and it was highly recommended that a web application only reference entities contained within the web application. Review the changes in the classloader options compared to V3.5SE and change as appropriate. See Class loader options for more information.
    • Review servlet for change related to content type setting. A change was made in the web container behavior (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 either modifying the servlet to set the content type, or by setting the autoResponseEncoding IBM extension to true for web modules.
    • Indicate external resources. Web applications that use JDBC must include a deployment descriptor indicating that JDBC is an external resource that needs to be accessed.
    • Modify JNDI calls. The com.ibm.ejs.ns.jndi.CNInitialContext Factory class can not be used for a V5, or higher, Web application to obtain an initial context factory for gaining access to the JNDI name space. Change the application to obtain JNDI access through the J2EE defined mechanism.
    • Remove any usage of Connection Manager APIs. These APIs were deprecated in V3.5SE and are not supported.
    • Review application resource authentication for possible changes.
      • Existing application components that specify a user ID and password on the getConnection method must be reassembled with a resource authentication property of Application to maintain the current behavior of the application. Otherwise, the J2EE server ignores the user ID passed on the method.
      • Application code dependent on the ACEE being placed on the thread of execution will need to change. An example of this is the CTG best practice recommendation to not provide a password/ID on the getConnection call for applications running in V3.5SE. This type of application must be changed.
    • Convert to J2EE Connector Architecture. Customers should recode, reassemble, and reinstall existing applications to work with WebSphere for z/OS-supported connectors that are designed to implement the J2EE Connector Architecture.
    • Make code page related changes. The JVM default code page has changed from EBCDIC to ASCII to be consistent with the WebSphere Application Server family. Application changes may be required. See Code page changes for more information.
  11. Install the application into the new server using the adminstrative console tool.
  12. Choose your Web server.
    Existing V3.5SE configurations include a V3.5 SE plug-in running as a GWAPI out of the IBM HTTP Server for z/OS and OS/390. V5, or higher, does not require the use of the IBM HTTP Server for z/OS and OS/390. You can choose to either:
    • Use a distributed platform Web server, in which a V5, or higher WebSphere plug-in for Web servers has been installed, or
    • Run without a Web server fronting the HTTP transport provided as part of the new J2EE server

    Either of these alternatives can coexist with the existing V3.5SE configuration. Alternatively, you may choose to continue to use an IBM HTTP Server for z/OS and OS/390, in which the V5 WebSphere HTTP Plug-in for z/OS has been installed. In this case, the IBM HTTP Server for z/OS and OS/390 you are using must be at a V5.3 level.

    With this in mind, several migration configurations are possible:

    • Install the WebSphere HTTP Plug-in for z/OS into the existing IBM HTTP Server V5.3 for z/OS and OS/390 (V3.5SE plug-in and V5 and higher WebSphere HTTP Plug-in for z/OS can coexist).
    • Install the WebSphere HTTP Plug-in for z/OS into a separate IBM HTTP Server V5.3 for z/OS and OS/390.
  13. Make necessary operational changes to support production.
    • Scripting capability that can be used for automation.
    • ARM policies should be updated based on the new topology/infrastructure.
    See WebSphere Application Server for z/OS V5 Operations and Administration for more information.

What to do next

Migration from Version 4.x to Version 5, or higher, does not require extensive tuning.

Migration from Version 3.5.x to Version 5, or higher 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 your existing was.conf file settings
Class loader options
Code page changes
Migrating and coexisting
Specification level summary of WebSphere Application Server
Coexistence port definitions
Migrating from V4.0.1



Searchable topic ID:   tins35sez
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_35sez.html

Library | Support | Terms of Use | Feedback