IBM WebSphere Development Studio Client for iSeries, Version 6.0.1, Migration Guide


Contents

iSeries: Getting ready to migrate
Maintaining more than one product version
Locating your workspace
Locating your workspace in Version 5.1.2
Locating your workspace in Version 5.1
Locating your workspace in Version 5
Locating your workspace in Version 4
Specifying your post-installation workspace
Finding other important information
iSeries: Migrating specific types of projects
Migrating projects with files generated by Database Web Pages and Java Bean Web Pages wizards
Generated files require a Java package for JDK 1.4.
Migrating program call beans
Migrating program call beans in iSeries Java and Web projects from Version 5.1 or 5.1.2 to Version 6.0.1
Migrating program call beans in iSeries Java and Web projects from Version 5.0 to Version 6.0.1
Migrating program call beans in iSeries Java and Web projects from Version 4.0 to Version 6.0.1
Migrating WebFacing projects
Using the WebFacing Import wizard
Migrating iSeries Web projects
Migrating Version 5.1.x iSeries Web projects to Version 6.0.1
Migrating Version 5.0 iSeries Web projects to Version 6.0.1
Migrating Version 4.0 iSeries Web projects to Version 6.0.1
Warning and error messages for Web project migration
Notices
COPYRIGHT LICENSE
Programming interface information
Trademarks and service marks

iSeries: Getting ready to migrate

This information explains how to migrate your projects to WebSphere Development Studio Client for iSeries Version 6.0.1 and WebSphere Development Studio Client Advanced Edition for iSeries Version 6.0.1 from previous versions of IBM(R) WebSphere(R) Development Studio Client for iSeries(TM). The product supports migration from Versions 5.1 and 5.1.2. This guide also provides tips about migrating from earlier versions.

Migration is required most often because of a change in the underlying technology from one release to another. For example, new standards in Web application directory structure may require reorganization of your projects from one release to another.

In general, migration is seamless and transparent. All you need to do is use your existing workspace, and continue working with your projects with the new version or level of the product. In rare instances, migration is required after the application of a service pack.

For some special cases, related to Java(TM) tools, Web tools, and customization of WebFacing projects, you might need to use a migration tool or do extra manual steps.

In all cases, a message informs you when migration is necessary.

The latest version of this document is available on the Web (ftp://ftp.software.ibm.com/as400/products/ad/wdt400/v601/migr/migrenu.html).

Table 1.
This information is also available in Spanish.
This information is also available in Simplified Chinese.
This information is also available in German.
This information is also available in French.
This information is also available in Japanese.
This information is also available in Korean.
This information is also available in Simplified Chinese.

The Readme file contains prerequisite information, limitations of the product, and information not included in the documentation. For information on installing WebSphere Development Studio Client for iSeries, see the Installation Guide.

Maintaining more than one product version

The installation process does not automatically uninstall Version 5.0, 5.1 or 5.1.2, but instead allows the two versions to coexist on a single system.

Before uninstalling Development Studio Client for iSeries Version 5.0, 5.1 or 5.1.2, we recommend that you note the location of your Version 5 workspace, and make a backup copy of it. If you do not back up your workspace, you might lose your Version 5 projects. (By default these projects are not uninstalled or deleted.)

In some instances, such as WebFacing, beginning in version 6.0.1, migration of version 4.0 and 5.0 projects is not supported because of additional features that have been added to the Development Studio Client. See Migrating WebFacing projects for more details.

Locating your workspace

Locating your workspace in Version 5.1.2

To find your Version 5.1.2 workspace:

Locating your workspace in Version 5.1

To find your Version 5.1 workspace:

Locating your workspace in Version 5

To find your Version 5 workspace:

Locating your workspace in Version 4

To find your Version 4 workspace:

Specifying your post-installation workspace

  1. When you start the Version 6.0 product (Start > Programs > IBM Rational(R) > WebSphere Development Studio Client for iSeries), a Workspace Launcher window opens in which you specify the directory to use for the session. Specify the directory location of your Version 5.1 or 5.1.2 workspace in this window.
  2. When prompted to confirm that you want to convert to the new workspace format, click OK.

Finding other important information

If you want specific information about how migration to Version 6.0 might affect your current version's workspace or projects, you can read the applicable sections of the migration guide supplied with your base Rational Software Developer Platform product. The location of the guide depends on which edition of WebSphere Development Studio Client for iSeries you have on your system.

Provided that you installed the product in its default location, the guide is also available after installation in, for example:

You can also find additional, newly documented information and technical support documents on migrating WebSphere Development Studio Client for iSeries projects on the Web.

iSeries: Migrating specific types of projects

When you are ready to migrate your V5.1.x workspace for good, start WebSphere Development Studio Client for iSeries with your old workspace. A progress indicator confirms that your projects are being automatically migrated.

Notes(R): During workspace migration a Problems dialog box opens with the message Could not restore workbench layout. Reason: Problems occurred restoring workbench. The error messages have no impact on the successful migration of the workspace. Note the name of perspective that could not be restored by clicking the Details button in the error dialog box, then click OK to close the dialog box.

To restore the perspective:

  1. Close the perspective by selecting Window -> Close Perspective.
  2. Reopen the perspective by selecting Window -> Open Perspective.

The following sections describe the steps required to deal with migration issues for different types of projects in WebSphere Development Studio Client for iSeries.

Migrating projects with files generated by Database Web Pages and Java Bean Web Pages wizards

Generated files require a Java package for JDK 1.4.

You must specify a Java package when working with projects that contain pages and .java files that were generated with the Database Web Pages and Java Bean Web Pages wizards, but did not specify a package during creation. For code that was previously generated, move the .java files to a package. Then update the JSP files, update the import statements and class information. In the web.xml file of the project, update the servlet-class entry.

Migrating program call beans

Migrating program call beans in iSeries Java and Web projects from Version 5.1 or 5.1.2 to Version 6.0.1

This section describes how to migrate program call beans created in Development Studio Client for iSeries Version 5.1 or 5.1.2 to Version 6.0.1.

In Version 6.0.1, the Program Call wizard puts the PCML file for a program call bean in the bean package. This is a change from previous versions. If you are recreating a program call bean from an existing PCML file that is not in the bean package, you can delete this PCML file after the wizard has finished recreating the program call bean.

Note:
In Version 6.0.1 you can create an iSeries Program Web Service out of ILE RPG or COBOL source or PCML files using the Web Service wizard directly. You do not have to run the Program Call wizard and the Web Service wizard.

Migrating program call beans in a Java project

  1. When you start the Version 6.0.1 product (Start > Programs > IBM Rational > WebSphere Development Studio Client for iSeries), a Workspace Launcher window opens in which you specify the directory to use for the session. Specify the directory location of your Version 5.x workspace.
  2. If you are prompted to confirm that you want to convert to the new user interface format, click OK.
  3. Remove runtime .jar files by changing the project's Java build path:.
    1. Right-click on the Java project and select Properties.
    2. In the left pane, select Java Build Path.
    3. Select the Libraries tab, then select the following JAR files and click Remove to remove them from the classpath:

      WDSC_HOME/plugins/com.ibm.etools.iseries.toolbox_5.1.0/runtime/jt400.jar
      WDSC_HOME/plugins/com.ibm.etools.iseries.webtools_5.1.0/lib/iwdtrt.jar
      WDSC_ECLIPSE_HOME/plugins/org.apache.xerces_4.1.3/xercesImpl.jar/
      j2ee.jar
    4. Rerun the Program Call wizard on all the PCML files. If you were using a default package, you must specify a package name in Version 6.0.1. The newly generated Java beans and the PCML file will be located in the specified package, you can delete the old Java beans and PCML file in the default package.

Migrating program call beans in a Web project

If you are a program call service bean user, you should know that in Version 6.0.1 the Program Call wizard always generates a .config file. This can be a user-specified one or the default, defaultPCW.config. You should no longer use the Runtime Configuration wizard. For any pre-Version 6.0.1 Web project, the Web tools project migration step outlined below will get information from the project's web.xml file and automatically create a defaultPCW.config if it doesn't already exist. From then on, the program call run time configuration will be based on the data in the .config file instead of the web.xml file.

  1. When you start the Version 6.0.1 product (Start > Programs > IBM Rational > WebSphere Development Studio Client for iSeries), a Workspace Launcher window opens in which you specify the directory to use for the session. Specify the directory location of your Version 5.1 or 5.1.2 workspace in this window.
  2. If prompted to confirm that you want to convert to the new user interface format, click OK.
  3. (Optional step: Use the J2EE Migration wizard to migrate from J2EE level 1.2 to a higher J2EE level.)
  4. Delete iwdtrt.jar and jt400.jar from the WEB-INF\lib folder.
  5. Rerun the Program Call wizard on all the PCML files. New Service bean and PCML files will be created in the specified package. Delete any old PCML files from the Web project.
  6. Rerun the Web Service wizard on the Service bean.

Code generated by the Web services wizard requires manual migration and cleanup. This migration applies only to the Web service beans themselves. Please refer to the Web services sections of the migration guide supplied with your base Rational Software Developer Platform product (see Finding other important information for links to this guide) on how to migrate your Web services.

Migrating program call beans in iSeries Java and Web projects from Version 5.0 to Version 6.0.1

This section describes how to migrate program call beans created in Development Studio Client for iSeries Version 5.0 to Version 6.0.1.

Note:
In Version 6.0.1 you can create an iSeries Program Web Service out of ILE RPG or COBOL source or PCML files using the Web Service wizard directly. You do not have to run the Program Call wizard and the Web Service wizard.

Migrating program call beans in a Java project

  1. When you start the Version 6.0.1 product (Start > Programs > IBM Rational > WebSphere Development Studio Client for iSeries), a Workspace Launcher window opens in which you specify the directory to use for the session. Specify the directory location of your Version 5.0 workspace in this window.
  2. If prompted to confirm that you want to convert to the new user interface format, click OK.
  3. Remove runtime .jar files by changing the project's Java build path:.
    1. Right-click on the Java project and select Properties.
    2. In the left pane, select Java Build Path.
    3. Select the Libraries tab, then select the following JAR files and click Remove to remove them from the classpath:

      WDSC_HOME/plugins/com.ibm.etools.iseries.toolbox_5.0.0/runtime/jt400.jar
      WDSC_HOME/plugins/com.ibm.etools.iseries.webtools_5.0.0/lib/iwdtrt.jar
      WDSC_ECLIPSE_HOME/plugins/org.apache.xerces_4.0.7/xercesImpl.jar/
      j2ee.jar
    4. Rerun the Program Call wizard on all the PCML files. On the Configure Authentication page of the wizard, deselect the Generate configuration file option.

Migrating program call beans in a Web project

The following sections will describe how to migrate the contents of the Web content, Java source, and Web project folders.

To migrate the contents of the Web content folder:

  1. When you start the Version 6.0.1 product (Start > Programs > IBM Rational > WebSphere Development Studio Client for iSeries), the Workspace Launcher window opens in which you specify the directory to use for the session. Use the default location as your workspace.
  2. Switch to the Resource perspective.
  3. Create a new Dynamic Web project with the same name and Servlet version as your existing 5.0 Web project. To find your Servlet version, look in the .websettings file of your existing 5.0 project and search for a jsp-level tag. If the jsp level is 1.2, set the Servlet version to be 2.3 otherwise set the Servlet version to be 2.2 Click Finish. Do not switch to the Web perspective when prompted.
  4. Select the Web content folder of the newly created project, right-click and select Import from the context menu.
  5. Choose File System as the import source and click Next. Click the Browse button and select the Web content folder (default name Web Content) of the existing 5.0 Web project. Click OK.
  6. Select the Web content folder but do not check the box. Click Select All. In the right panel, deselect one of the files and then re-select the same one. This has the effect of importing everything under the Web content folder but not the Web content folder itself.
  7. Select the options Create selected folders only and Overwrite existing resources without warnings and click Finish. The Web content folder of the newly created project should now contain similar resources and folder structure of the 5.0 Web content folder.

To migrate the contents of the Java source folder:

  1. Select the Java source folder of the newly created project, right-click and select Import from the context menu.
  2. Choose File System as the import source and click Next. Click the Browse button and select the Java source folder (default name: Java Source) of the existing 5.0 Web project. Click OK.
  3. Select the Java source folder but do not check the box. Click Select All. In the right panel, deselect one of the files and then re-select the same one. This has the effect of importing everything under the Java source folder but not the Java source folder itself.
  4. Select the options Create selected folders only and Overwrite existing resources without warnings and click Finish. The Java source folder of the newly created project should now contain similar resources and folder structure of the 5.0 Java source folder.

To migrate the contents of the Web project folder:

  1. Now select the newly created project, right-click and select Import from the context menu.
  2. Choose File System as the import source and click Next. Click the Browse button and select the existing 5.0 Web project.
  3. Select the project folder in the left panel and click Select All. In the right panel, deselect one of the files and then re-select the same file. In the left panel, deselect the Web contents and Java source folders. This has the effect of importing everything under the Web project folder except the Web contents and Java source folders as well as the Web project folder itself.
  4. In the right panel, deselect the following files if they appear in the list:

    These files contain information about the project that is required at design time. The information cannot be migrated to Version 6.0.1 so the files are re-created as necessary.

  5. Select the options Create selected folders only and Overwrite existing resources without warnings and click Finish. The newly created Web project folder should now contain similar resources and folder structure of the 5.0 Web project folder.

  1. (Optional step: Use the J2EE Migration wizard to migrate from J2EE level 1.2 to a higher J2EE level.)
  2. Delete iwdtrt.jar and jt400.jar from the WEB-INF\lib folder.
  3. Rerun the Program Call wizard on all the PCML files.

This migration applies only to service beans themselves. Please refer to the Web Services sections of the migration guide supplied with your base Rational Software Developer Platform product (see Finding other important information for links to this guide) on how to migrate your Web services.

Migrating program call beans in iSeries Java and Web projects from Version 4.0 to Version 6.0.1

This section describes how to migrate program call beans created in Development Studio Client for iSeries Version 4.0 to Version 6.0.1.

Note:
In Version 6.0.1 you can create an iSeries Program Web Service out of ILE RPG or COBOL source or PCML files using the Web Service wizard directly. You do not have to run the Program Call wizard and the Web Service wizard.

Migrating program call beans in a Java project

  1. When you start the Version 6.0.1 product (Start > Programs > IBM Rational > WebSphere Development Studio Client for iSeries), a Workspace Launcher window opens in which you specify the directory to use for the session. Specify the directory location of your Version 4.0 workspace in this window.
  2. When prompted to confirm that you want to convert to the new user interface format, click OK.
  3. Remove runtime .jar files by changing the project's Java build path:
    1. Right-click on the Java project and select Properties.
    2. In the left pane, select Java Build Path.
    3. Select the Libraries tab, then select the following JAR files and click Remove to remove them from the classpath:

         ECLIPSE_HOME/plugins/com.ibm.etools.iseries.toolbox/runtime/jt400.jar
         ECLIPSE_HOME/plugins/com.ibm.etools.iseries.webtools/lib/wdt400rt.jar
         ECLIPSE_HOME/plugins/com.ibm.etools.websphere.runtime/lib/j2ee.jar
         ECLIPSE_HOME/plugins/com.ibm.etools.websphere.runtime/lib/xerces.jar
  4. Rerun the Program Call wizard on all the PCML files. On the Configure Authentication page of the wizard, deselect the option Generate configuration file.

This migration applies only to the program call beans themselves. Code generated by the Program Call wizard requires manual migration and cleanup.

Migrating program call beans in a Web project

To migrate the contents of the Web content folder:

  1. When you start the Version 6.0.1 product (Start > Programs > IBM Rational > WebSphere Development Studio Client for iSeries), the Workspace Launcher window opens in which you specify the directory to use for the session. Use the default location as your workspace.
  2. Switch to the Resource perspective.
  3. Create a new Dynamic Web project with the same name and Servlet version as your existing 4.0 Web project. To find your Servlet version, look in the .websettings file of your existing 4.0 project and search for a jsp-level tag. If the jsp level is 1.2, set the Servlet version to be 2.3 otherwise set the Servlet version to be 2.2 Click Finish. Do not switch to the Web perspective when prompted.
  4. Select the Web content folder of the newly created project, right-click and select Import from the context menu.
  5. Choose File System as the import source and click Next. Click the Browse button and select the Web content folder (default name webApplication) of the existing 4.0 Web project. Click OK.
  6. Select the Web content folder but do not check the box. Click Select All. In the right panel, deselect one of the files and then re-select the same one. This has the effect of importing everything under the Web content folder but not the Web content folder itself.
  7. Select the options Create selected folders only and Overwrite existing resources without warnings and click Finish. The Web content folder of the newly created project should now contain similar resources and folder structure of the 4.0 Web content folder.

To migrate the contents of the Java source folder:

  1. Select the Java source folder of the newly created project, right-click and select Import from the context menu.
  2. Choose File System as the import source and click Next. Click the Browse button and select the Java source folder (default name: source) of the existing 4.0 Web project. Click OK.
  3. Select the Java source folder but do not check the box. Click Select All. In the right panel, deselect one of the files and then re-select the same one. This has the effect of importing everything under the Java source folder but not the Java source folder itself.
  4. Select the options Create selected folders only and Overwrite existing resources without warnings and click Finish. The Java source folder of the newly created project should now contain similar resources and folder structure of the 4.0 Java source folder.

To migrate the contents of the Web project folder:

  1. Now select the newly created project, right-click and select Import from the context menu.
  2. Choose File System as the import source and click Next. Click the Browse button and select the existing 4.0 Web project.
  3. Select the project folder in the left panel and click Select All. In the right panel, deselect one of the files and then re-select the same file. In the left panel, deselect the Web contents and Java source folders. This has the effect of importing everything under the Web project folder except the Web contents and Java source folders as well as the Web project folder itself.
  4. In the right panel, deselect the following files if they appear in the list:

    These files contain information about the project that is required at design time. The information cannot be migrated to Version 6.0.1 so the files are re-created as necessary.

  5. Select the options Create selected folders only and Overwrite existing resources without warnings and click Finish. The newly created Web project folder should now contain similar resources and folder structure of the 5.0 Web project folder.
  1. (Optional step: Use the J2EE Migration wizard to migrate from J2EE level 1.2 to a higher J2EE level.)
  2. Delete wdt400rt.jar and wdt400tb.jar from the WEB-INF\lib folder.
  3. Rerun the Program Call wizard on all the PCML files.
  4. This migration applies only to Service beans themselves.

From Version 5.1 onwards, the beans must be generated in a named package before you invoke the Web Services wizard. Code generated by the Web services wizard requires manual migration and cleanup.

This migration applies only to the Web service beans themselves. Please refer to the Web services sections of the migration guide supplied with your base Rational Software Developer Platform product (see Finding other important information for links to this guide) on how to migrate your Web services.

Migrating WebFacing projects

Version 6.0.1 of the IBM WebFacing Tool offers extensions for interoperability with 5250 applications that have not been Web-enabled. These 5250 applications run in a browser but are restricted to two runtime connections for testing purposes only. To deploy interoperating applications to production, you must acquire the IBM WebFacing Deployment Tool for WebSphere Development Studio version 6.0.1 (5725-N52).

Important:
From WebSphere Development Studio Client for iSeries, Version 6.0.1 onwards, migrating WebFacing 4.0 and 5.0 projects is no longer supported. See Using the WebFacing Import wizard and IBM technical support documents for information on migrating projects to Version 6.0.1.

If you have any existing workspace that was created using Versions 5.1 or newer, you can open them using Version 6.0.1 and the WebFacing projects can be run as-is. However, the display of the project may not be complete. For example, the record JSP files and some style files from some previous releases do not appear in a Version 6.0.1 tree view until you reconvert your projects. The first time you convert a DDS file, the project structure is updated to reflect a new layout that was established in 5.1.2. For example, new runtime jar files and template files are imported. This occurs in the same way that it would if you imported your project using the import wizard.

Using the WebFacing Import wizard

If you have WebFacing projects from WebSphere Development Studio Client, Version 5.1.x or later, you can migrate these to WebSphere Development Studio Client for iSeries Version 6.0.1 by using the Import wizard. Follow these steps:

  1. Select File > Import.
  2. Choose WebFacing Projects. Click Next.
  3. Browse to the folder that contains the WebFacing projects that you want to migrate to Version 6.0.1. Click Next.
    Note:
    When you upgrade to Version 6.0.1, WebFacing projects remain available in your original workspace directory.
  4. Any WebFacing projects that the wizard finds will be listed in the WebFacing projects found pane. Select the projects that you want to import. The wizard will create an EAR file for the project. An EAR file is a J2EE enterprise application archive file. By default, the EAR file uses the name of your WebFacing project and adds _EAR to the name. If you want to use a different name or you are consolidating several projects into a single EAR file, you can change the name in the Enterprise Application Project field.
  5. Click Finish to migrate the project to the Version 6.0.1 workspace.
  6. To see the project in the WebFacing perspective, select Window > Open Perspective > WebFacing.

Manual steps if your project has customized files

The original files have new names with the following format: filename +_601_bak.

If you customized your WebFacing project, then you may need to merge your customizations from the original files into the following:

Migrating iSeries Web projects

The following methods can be used to migrate iSeries Web projects:

Important:
Ensure all server instances are stopped before proceeding with migration.

Migrating Version 5.1.x iSeries Web projects to Version 6.0.1

The following information describes how to migrate iSeries Web projects from Development Studio Client for iSeries Version 5.1.x to WebSphere Development Studio Client for iSeries Version 6.0.1.

The migration activities involve the following stages:

  1. Migrating projects using an existing 5.1.x workspace
  2. Migrating iSeries Web project contents
  3. Addressing errors and warnings generated as a result of the migration

Stage 1: Migrating projects using an existing 5.1.x workspace

In Version 6.0.1, the default Web content and Java source folder names for new Web projects are configurable through a preference page. The default names are now WebContent and JavaSource. These default names will be used for new Web projects only. Web projects created in versions prior to Version 6.0.1 will continue to function using the old names.

  1. When you start the Version 6.0.1 product (Start > Programs > IBM Rational > WebSphere Development Studio Client for iSeries), the Rational Software Developer Platform window opens in which you specify the directory to use for the session. Specify the directory location of your Version 5.1.x workspace in this window.
  2. If prompted to confirm that you want to convert to the new user interface format, click OK.
  3. Optional: In the main menu, click Window > Preferences. In the left pane, expand Web Tools and select New J2EE Project. In the right pane, set the preferences for your default folder names.

You can manually change the source folder names for 5.1.x projects in Version 6.0.1 by right-clicking the folder name in the Project Explorer view and selecting Refactor then clicking Rename. The Rename action renames the folder names and fixes the Java build path for the 5.1.x Web projects. If you opt to rename the JavaSource and WebContent folder names in Version 6.0.1, then any automated build scripts you have must be manually updated with the new folder names.

Optional: Converting Web projects to Struts 1.1

If you created Struts 1.1 Beta 2 Web projects in IBM WebSphere Studio Application Developer Version 5, you can convert it to Struts 1.1, but this is not required as Struts 1.1 Beta 2 is still supported.

If you do have Struts 1.1 Beta 2 Web projects that you want to convert to Struts 1.1:

  1. Create a new Struts 1.1 Web project named Struts11. This provides convenient access to the Struts 1.1 artifacts we will need while we are converting our real projects. You can delete this project when you are done.
  2. For each Struts 1.1 Beta 2 project that you want to convert to Struts 1.1, do the following:
    1. Delete the following .jar files from your project's Web Content/WEB-INF/lib directory: commons-*.jar and struts.jar.
    2. Copy the following .jar files from Struts11/WebContent/WEB-INF/lib directory to your project's Web Content/WEB-INF/lib directory: commons-*.jar and struts.jar.
    3. Delete the following .tld files from your project's Web Content/WEB-INF directory: struts-*.tld.
    4. Copy the following .tld files from Struts11/WebContent/WEB-INF directory to your project's Web Content/WEB-INF directory: struts-*.tld.

Stage 2: Migrating iSeries Web project contents

To migrate iSeries Web Tools project contents:

  1. Right-click the project name in the Project Navigator view of the Web perspective and select Properties. Select Web Project Features in the left panel. From the list of Available Web Project Features, select Struts if it is not already selected. Click OK. Click Finish in the Web Project Features window to accept the default Struts version (1.1).
    Note:
    If you miss this step, a window appears requesting that you add Struts support.
  2. Important: Close and reopen the project at this point to avoid an exception related to deletion of resources and to ensure that the project is not running on any servers.
  3. Right-click the project name in the Web perspective and select Migrate > iSeries Web Tools project. The Confirm Migration window indicates that the project structure and contents will be migrated.
  4. To continue the process, click OK. The Progress Information window shows the progress of the migration.
  5. When the migration is finished, a message indicates the results.
  6. If the migration process completed successfully, no further action is required. If the migration process completed with errors or warnings, proceed to Stage 3: Addressing errors and warnings generated as a result of the migration.
  7. The migration process performs the following actions:

Stage 3: Addressing errors and warnings generated as a result of the migration

If the migration process encounters problems, a window opens indicating that errors or warnings occurred. The migration log file describing the problems, projectName_MigrationDetails.txt under the project name in the Web perspective, also opens up.

The Migration Result section at the top of the migration log file indicates the overall status of the migration and refers to an online version of the warning and error table below with descriptions and corrective actions. See Warning and error messages for Web project migration.

Migrating Version 5.0 iSeries Web projects to Version 6.0.1

The following information describes how to migrate iSeries Web projects from Development Studio Client for iSeries Version 5.0 to WebSphere Development Studio Client for iSeries Version 6.0.1.

The migration activities involve the following stages:

  1. Migrating projects using an existing 5.0 Web project on the file system
  2. Migrating iSeries Web project contents
  3. Addressing errors and warnings generated as a result of the migration

Stage 1: Migrating an existing 5.0 project on the file system to Version 6.0.1

In Version 6.0.1, the default Web content and Java source folder names for new Web projects are configurable through a preference page. The default names are now WebContent and JavaSource. These default names will be used for new Web projects only. Web projects created in versions prior to Version 6.0.1 will continue to function using the old names.

To migrate the contents of the Web content folder:

  1. When you start the Version 6.0.1 product (Start > Programs > IBM Rational > WebSphere Development Studio Client for iSeries), the Workspace Launcher window opens in which you specify the directory to use for the session. Use the default location as your workspace.
  2. Switch to the Resource perspective.
  3. Create a new Dynamic Web project with the same name and Servlet version as your existing 5.0 Web project. To find your Servlet version, look in the .websettings file of your existing 5.0 project and search for a jsp-level tag. If the jsp level is 1.2, set the Servlet version to be 2.3 otherwise set the Servlet version to be 2.2 Click Finish. Do not switch to the Web perspective when prompted.
  4. Select the Web content folder of the newly created project, right-click and select Import from the context menu.
  5. Choose File System as the import source and click Next. Click the Browse button and select the Web content folder (default name: Web Content) of the existing 5.0 Web project. Click OK.
  6. Select the Web content folder but do not check the box. Click Select All. In the right panel, deselect one of the files and then re-select the same one. This has the effect of importing everything under the Web content folder but not the Web content folder itself.
  7. In the right panel, deselect the following files if they appear in the list:
  8. Select the options Create selected folders only and Overwrite existing resources without warnings and click Finish. The Web content folder of the newly created project should now contain similar resources and folder structure of the 5.0 Web content folder.

To migrate the contents of the Java source folder:

  1. Select the Java source folder of the newly created project, right-click and select Import from the context menu.
  2. Choose File System as the import source and click Next. Click the Browse button and select the Java source folder (default name: Java Source) of the existing 5.0 Web project. Click OK.
  3. Select the Java source folder but do not check the box. Click Select All. In the right panel, deselect one of the files and then re-select the same one. This has the effect of importing everything under the Java source folder but not the Java source folder itself.
  4. Select the options Create selected folders only and Overwrite existing resources without warnings and click Finish. The Java source folder of the newly created project should now contain similar resources and folder structure of the 5.0 Java source folder.

To migrate the contents of the Web project folder:

  1. Now select the newly created project, right-click and select Import from the context menu.
  2. Choose File System as the import source and click Next. Click the Browse button and select the existing 5.0 Web project.
  3. Select the project folder in the left panel and click Select All. In the right panel, deselect one of the files and then re-select the same file. In the left panel, deselect the Web contents and Java source folders. This has the effect of importing everything under the Web project folder except the Web contents and Java source folders as well as the Web project folder itself.
  4. In the right panel, deselect the following files if they appear in the list:

    These files contain information about the project that is required at design time. The information cannot be migrated to Version 6.0.1 so the files are re-created as necessary.

  5. Select the options Create selected folders only and Overwrite existing resources without warnings and click Finish. The newly created Web project folder should now contain similar resources and folder structure of the 5.0 Web project folder.

Removing old Struts level artifacts

  1. Right-click on WebContent/WEB-INF/web.xml. Select Open with > Deployment Descriptor Editor.
  2. Go to the Servlets tab.
  3. Remove the Servlet entry that maps the servlet class org.apache.struts.action ActionServlet, default name action.

Stage 2: Migrating iSeries Web project contents

To migrate iSeries Web Tools project contents:

  1. Right-click the project name in the Project Navigator view of the Web perspective and select Properties. Select Web Project Features in the left panel. From the list of Available Web Project Features, select Struts if it is not already selected. Click OK. Click Finish in the Web Project Features window to accept the default Struts version (1.1).
    Note:
    If you miss this step, a window appears requesting that you add Struts support.
  2. Important: Close and reopen the project at this point to avoid an exception related to deletion of resources and to ensure that the project is not running on any servers.
  3. Right-click the project name in the Web perspective and select Migrate > iSeries Web Tools project. The Confirm Migration window indicates that the project structure and contents will be migrated.
  4. To continue the process, click OK. The Progress Information window shows the progress of the migration.
  5. When the migration is finished, a message indicates the results.
  6. If the migration process completed successfully, no further action is required. If the migration process completed with errors or warnings, proceed to Stage 3: Addressing errors and warnings generated as a result of the migration.
  7. The migration process performs the following actions:

Stage 3: Addressing errors and warnings generated as a result of the migration

If the migration process encounters problems, a window opens indicating that errors or warnings occurred. The migration log file describing the problems, projectName_MigrationDetails.txt under the project name in the Web perspective, also opens up.

The Migration Result section at the top of the migration log file indicates the overall status of the migration and refers to an online version of the warning and error table below with descriptions and corrective actions. See Warning and error messages for Web project migration.

For 5.0.x migration only, in addition to any migration warnings listed in the log file, you should be aware that the Maximum length (maxLength) attribute is no longer supported for the Text Entry Web Component. This might affect the visual appearance of your Web pages.

Migrating Version 4.0 iSeries Web projects to Version 6.0.1

The following information describes how to migrate iSeries Web projects from Development Studio Client for iSeries Version 4.0 to WebSphere Development Studio Client for iSeries Version 6.0.1.

The migration activities involve the following stages:

  1. Migrating projects using an existing 4.0 Web project on the file system
  2. Migrating iSeries Web project contents
  3. Addressing errors and warnings generated as a result of the migration

Stage 1: Migrating an existing 4.0 project on the file system to Version 6.0.1

In Version 6.0.1, the default Web content and Java source folder names for new Web projects are configurable through a preference page. The default names are now WebContent and JavaSource. These default names will be used for new Web projects only. Web projects created in versions prior to Version 6.0.1 will continue to function using the old names.

To migrate the contents of the Web content folder:

  1. When you start the Version 6.0.1 product (Start > Programs > IBM Rational > WebSphere Development Studio Client for iSeries), the Workspace Launcher window opens in which you specify the directory to use for the session. Use the default location as your workspace.
  2. Switch to the Resource perspective.
  3. Create a new Dynamic Web project with the same name and Servlet version as your existing 4.0 Web project. To find your Servlet version, look in the .websettings file of your existing 4.0 project and search for a jsp-level tag. If the jsp level is 1.2, set the Servlet version to be 2.3 otherwise set the Servlet version to be 2.2 Click Finish. Do not switch to the Web perspective when prompted.
  4. Select the Web content folder of the newly created project, right-click and select Import from the context menu.
  5. Choose File System as the import source and click Next. Click the Browse button and select the Web content folder (default name webApplication) of the existing 4.0 Web project. Click OK.
  6. Select the Web content folder but do not check the box. Click Select All. In the right panel, deselect one of the files and then re-select the same one. This has the effect of importing everything under the Web content folder but not the Web content folder itself.
  7. Select the options Create selected folders only and Overwrite existing resources without warnings and click Finish. The Web content folder of the newly created project should now contain similar resources and folder structure of the 4.0 Web content folder.

To migrate the contents of the Java source folder:

  1. Select the Java source folder of the newly created project, right-click and select Import from the context menu.
  2. Choose File System as the import source and click Next. Click the Browse button and select the Java source folder (default name: source) of the existing 4.0 Web project. Click OK.
  3. Select the Java source folder but do not check the box. Click Select All. In the right panel, deselect one of the files and then re-select the same one. This has the effect of importing everything under the Java source folder but not the Java source folder itself.
  4. Select the options Create selected folders only and Overwrite existing resources without warnings and click Finish. The Java source folder of the newly created project should now contain similar resources and folder structure of the 4.0 Java source folder.

To migrate the contents of the Web project folder:

  1. Now select the newly created project, right-click and select Import from the context menu.
  2. Choose File System as the import source and click Next. Click the Browse button and select the existing 4.0 Web project.
  3. Select the project folder in the left panel and click Select All. In the right panel, deselect one of the files and then re-select the same file. In the left panel, deselect the Web contents and Java source folders. This has the effect of importing everything under the Web project folder except the Web contents and Java source folders as well as the Web project folder itself.
  4. In the right panel, deselect the following files if they appear in the list:

    These files contain information about the project that is required at design time. The information cannot be migrated to Version 6.0.1 so the files are re-created as necessary.

  5. Select the options Create selected folders only and Overwrite existing resources without warnings and click Finish. The newly created Web project folder should now contain similar resources and folder structure of the 4.0 Web project folder.

Stage 2: Migrating iSeries Web project contents

To migrate iSeries Web Tools project contents:

  1. Right-click the project name in the Project Navigator view of the Web perspective and select Properties. Select Web Project Features in the left panel. From the list of Available Web Project Features, select Struts if it is not already selected. Click OK. Click Finish in the Web Project Features window to accept the default Struts version (1.1).
    Note:
    If you miss this step, a window appears requesting that you add Struts support.
  2. Important: Close and reopen the project at this point to avoid an exception related to deletion of resources and to ensure that the project is not running on any servers.
  3. Right-click the project name in the Web perspective and select Migrate > iSeries Web Tools project. The Confirm Migration window indicates that the project structure and contents will be migrated.
  4. To continue the process, click OK. The Progress Information window shows the progress of the migration.
  5. When the migration is finished, a message indicates the results.
  6. If the migration process completed successfully, no further action is required. If the migration process completed with errors or warnings, proceed to Stage 3: Addressing errors and warnings generated as a result of the migration.
  7. The migration process performs the following actions:

Stage 3: Addressing errors and warnings generated as a result of the migration

If the migration process encounters problems, a window opens indicating that errors or warnings occurred. The migration log file describing the problems, projectName_MigrationDetails.txt under the project name in the Web perspective, also opens up.

The Migration Result section at the top of the migration log file indicates the overall status of the migration and refers to an online version of the warning and error table below with descriptions and corrective actions. See Warning and error messages for Web project migration.

Additional migration considerations

In addition to any migration errors listed in the log file described above, you need to address the following items where applicable:

In addition to any migration warnings listed in the log file described in Stage 4 above, you should be aware of the following changes which may affect the visual appearance of your Web pages:

Warning and error messages for Web project migration

Error code Description Action
E100 An undetermined error occurred during the migration of the JSP file. Resolve or address all other errors or warnings in the migration log file and run the migration tool again.
E101 An iSeries Web component in the JSP file has an error. Resolve the iSeries Web component error.
E200 Processing the .wit file resulted in an undetermined error. Double-click the .wit file that is in error to invoke the Web Interaction wizard. Proceed through all of the pages of the wizard and make any necessary changes. Click Finish.
E201 One or more Web component names defined in the pages used in this interaction are invalid. Double-click the .wit file that is in error to invoke the Web Interaction wizard. A window opens indicating that Web component names are invalid and asks if you want to change them. Click Yes. Make any needed changes. For any Web components that have changes input or output parameters, complete the Name in Session, Save to session, and Link options. Proceed through all of the pages of the wizard and make any necessary changes. Click Finish.
E202 An output parameter defined in this interaction had the "Message Indicator" value set to true. Advanced message handling has changed significantly in this release. You need to redefine the message handling options. Double-click the .wit file that is in error to invoke the Web Interaction wizard. On the "Map and Link the Output Parameters to the Output Fields" page, set the Message Controller value to true, select the value "true". Now you can see the button; click it and define the message control specifications.
E300 An undetermined error occurred processing the design comtrol (DTC) and/or the resulting iSeries Web component. Resolve or address all other errors or warnings in the migration log file. Rename the migration log file and run the migration tool again.
E301-E302 The design control property for push buttons, Next/Previous, is no longer supported. The Button Web component Button type attribute will be defined as Submit. Use the Web Interaction wizard to create an interaction to specify the page that contained the Next/Previous button as the input JSP page, and to specify the target page of the Next button as the output JSP page. In version 4.0, the Next/Previous button was used with multiple input pages. Click Help > Help contents to open the help system, then click Reference > User interface reference > iSeries Web applications > Multiple input and output pages.
E400 An undetermined error occurred during the migration of the code generation template file. Make sure that the code generation templates are not read-only. Address all other errors or warnings in the migration log file and run the migration tool again.
E401 The code generation template file has been customized. Use the newer version of the template. Ensure that the customizations you made to the older version of the template have been made to the later version of the template. For example, customized content in <workspace_location>\metadata\ plugins\com.ibm.etools.iseries. webtools\iseriesPgmCallAction. template.bak needs to be correctly inserted into <workspace_location>\metadata\ plugins\com.ibm.etools.iseries. webtools\iseriesPgmCallAction. template
Warning code Description Action
W100 An iSeries Web component on the JSP page has a warning. Address the iSeries Web component warning.
W300 A list box or combination box contained more than one character for the delimiter property. The first character found in the delimiter property is used for the corresponding iSeries Web component delimiter attribute. Ensure that all options of the Selection Box or Combo Box Web component have their name and value attributes defined correctly.
W301-W302 A list box or combination box contained the preselect character *, in a Data property [key] or [value]. Ensure that all options of the Selection Box or Combo Box Web component have their name and value attributes defined correctly.
W303 All radio button design controls in a JSP file that have the same Group name property now appear as an option of a Radio Button Group Web component. The properties defined on the Font tab and Color tab for the first radio button found in the JSP page are used as the Color and Font attributes for the Radio Button Group. That is, Color tab and Font tab properties are lost for subsequent radio buttons in the same group. Ensure that the Radio Button Group appears visually as desired within the JSP page by selecting the associated JSP file and running the file on the server. Ensure that Radio Button Group Font and Color attributes looks the way you want by selecting the associated JSP file and running on the server.
W304 The Pushbutton property Label is no longer supported. The Pushbutton property Value has been mapped to the Label attribute of the corresponding Button Web component. The text that appears on the Button Web component is different than that for the Pushbutton design control. Change the value of the Label attribute if the text shown on the Button Web component is not suitable.
W305 The Subfile or Table design control now appears visually outside of the HTML FORM tag. A Table Web component cannot appear inside an HTML FORM tag. If the design control type was Subfile, the corresponding iSeries Web component is the Table Web component. Ensure that the Table Web component looks the way you want it on the JSP page.
W306-W320 A design control event property is no longer supported.
  • W306 - OnDblClick
  • W307 - OnMouseDown
  • W308 - OnMouseOut
  • W309 - OnMouseOver
  • W310 - OnSelect
  • W312 - OnChange for radio buttons
  • W313 - OnChange for check boxes
  • W314 - OnMouseUp
  • W315 - OnKeyDown for radio buttons
  • W316 - OnKeyPress for radio buttons
  • W317 - OnKeyUp for radio buttons
  • W318 - OnKeyDown for push buttons
  • W319 - OnKeyPress for push buttons
  • W320 - OnKeyUp for push buttons
If required, define the associated action with a different event.
W321 The Web component had an attribute defined that is no longer supported because 1) the associated CSS attribute is not supported by most browsers 2) the associated HTML attribute is already deprecated in HTML 4.0 and is not supported by most browsers None.

Notices

Note to U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this Documentation in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this Documentation. The furnishing of this Documentation does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing
 IBM Corporation 
North Castle Drive
Armonk, NY 10504-1785 
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OR CONDITIONS OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

Lab Director
IBM Canada Ltd. Laboratory
8200 Warden Avenue
Markham, Ontario, Canada L6G 1C7

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this Documentation and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples may include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

COPYRIGHT LICENSE

This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM's application programming interfaces.

Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows:

(C) (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. (C) Copyright IBM Corp. 2000, 2005. All rights reserved.

Programming interface information

Programming interface information is intended to help you create application software using this program.

General-use programming interfaces allow you to write application software that obtain the services of this program's tools.

However, this information may also contain diagnosis, modification, and tuning information. Diagnosis, modification and tuning information is provided to help you debug your application software.

Warning: Do not use this diagnosis, modification, and tuning information as a programming interface because it is subject to change.

Trademarks and service marks

The following terms are trademarks of International Business Machines Corporation in the United States, other countries, or both:

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both

Rational is a trademark of International Business Machines Corporation and Rational Software Corporation(R), in the United States, other countries or both.

Other company, product, and service names may be trademarks or service marks of others.