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

Contents

iSeries: Getting ready to migrate

iSeries: Migrating specific types of projects

Notices

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.

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:

• If you accepted the default location when you installed Version 5.1.2, your workspace is in the directory X:\Documents & Settings\your userid\My Documents\IBM\wdsc\workspace, where X is the drive where your Windows installation directory is located.
• Otherwise, search for a directory called .metadata. Every workspace directory contains a metadata directory; the directory in which .metadata appears is usually your workspace.
• To find the location of an individual resource, such as a project (read further in this guide for more information about migrating different types of projects):
  1. In the Version 5.1.2 workbench, switch to the Navigator view: click Window > Show View > Other. Expand Basic and select Navigator. Click OK.
  2. Right-click the name of the resource and select Properties.
  3. In the left pane, click Info.
  The location of the resource appears in the right pane.

Locating your workspace in Version 5.1

To find your Version 5.1 workspace:

• If you accepted the default location when you installed Version 5.1, your workspace is in the directory X:\Documents & Settings\your userid\My Documents\IBM\wdsc\workspace, where X is the drive where your Windows installation directory is located.
• Otherwise, search for a directory called .metadata. Every workspace directory contains a metadata directory; the directory in which .metadata appears is usually your workspace.
• To find the location of an individual resource, such as a project (read further in this guide for more information about migrating different types of projects):
  1. In the Version 5.1 workbench, switch to the Navigator view: click Window > Show View > Other. Expand Basic and select Navigator. Click OK.
  2. Right-click the name of the resource and select Properties.
  3. In the left pane, click Info.
  The location of the resource appears in the right pane.

Locating your workspace in Version 5

To find your Version 5 workspace:

• If you accepted the default location when you installed Version 5, your workspace is in the directory X:\Documents & Settings\your userid\My Documents\IBM\wdsc\workspace, where X is the drive where your Windows installation directory is located.
• Otherwise, search for a directory called .metadata. Every workspace directory contains a metadata directory; the directory in which .metadata appears is usually your workspace.
• To find the location of an individual resource, such as a project (read further in this guide for more information about migrating different types of projects):
  1. In the Version 5 workbench, switch to the Navigator view: click Window > Show View > Other. Expand Basic and select Navigator. Click OK.
  2. Right-click the name of the resource and select Properties.
  3. In the left pane, click Info.
  The location of the resource appears in the right pane.

Locating your workspace in Version 4

To find your Version 4 workspace:

• If you accepted the default location when you installed Version 4.0, your workspace is in the directory X:\WDSC\WSSD\workspace, where X is the drive where you installed the product.
• Otherwise, search (from the Start menu) for a directory called .metadata; every workspace directory contains a metadata directory. Once you find a .metadata directory, check the directory in which it appears; that directory is a candidate for your workspace.
• To find the location of an individual resource, such as a project (read further in this guide for more information about migrating different types of projects):
  1. In the Version 4.0 workbench, switch to the Navigator view: Click Perspective > Show View > Other. Expand Basic and select Navigator. Click OK.
  2. Right-click the name of the resource and select Properties.
  3. In the left pane, click Info.
  The location of the resource appears in the right pane.

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.

• If you have the Advanced Edition, the Rational Application Developer Migration Guide is migrate.html or migrate.pdf in the rad directory on CD 1.
• If you have the standard edition, the Rational Web Developer Migration Guide is migrate.html or migrate.pdf in the rwd directory on CD 1.

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

• C:\Program Files\IBM\Rational\SDP\6.0\radi_prod\migrate.html
• C:\Program Files\IBM\Rational\SDP\6.0\rwdi_prod\migrate.html

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:
   • \WebContent\.classpath
   • \WebContent\.project
   • \WebContent\.websettings
   • \WebContent\.serverPreference

   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:
   • \WebContent\.classpath
   • \WebContent\.project
   • \WebContent\.websettings
   • \WebContent\.serverPreference

   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.

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.

   • If you are migrating from Development Studio Client 5.1 or 5.1.2, see the sections on finding your workspace under Maintaining more than one product version.

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:

• PageBuilder.jsp
• CmdKeys.jsp
• logon.jsp
• index.html
• If the previous project was Struts-enabled, then the Struts configuration files (struts-config.xml) must be updated.
• If the previous project used Web Site Designer, then the following files must be updated:
  • \WebContent\index.jsp
  • \WebContent\INV1.jsp
  • \WebContent\INV2.jsp
  • \WebContent\theme\WFB_blue.jtpl

Migrating iSeries Web projects

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

• Migrating iSeries Web projects using an existing WebSphere Development Studio Client Version 5.1.x workspace

  This migration involves using your existing workspace in the workbench in Version 6.0.1 and running the iSeries Web Tools migration routine.

• Migrating iSeries Web projects using an existing WebSphere Development Studio Client Version 5.0 project

  This migration involves importing project contents from the file system then running the iSeries Web Tools migration routine.

• Migrating iSeries Web projects using an existing WebSphere Development Studio Client Version 4.0 project

  This migration involves importing project contents from the file system then running the iSeries Web Tools migration routine.

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:
   • Updates iSeries Web components, Tag Libraries, and JavaScript^(TM) files (updating all JSP files accordingly).
   • Regenerates Web-interaction-related files based on struts-framework from the .wit files, and updates Web interaction runtime files.
   • Adds support for new iSeries Web tools function available in Version 6.0.1

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:
   • \WebContent\WEB-INF\struts-*.tld
   • \WebContent\WEB-INF\lib\struts.jar
   • \WebContent\WEB-INF\lib\commons-*.jar
   • \WebContent\WEB-INF\lib\jdbc2_0-stdext.jar
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:
   • \WebContent\.classpath
   • \WebContent\.project
   • \WebContent\.websettings
   • \WebContent\.serverPreference

   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:
   • Updates iSeries Web components, Tag Libraries, and JavaScript files (updating all JSP files accordingly).
   • Regenerates Web-interaction-related files based on struts-framework from the .wit files, and updates Web interaction runtime files.
   • Adds support for new iSeries Web tools function available in Version 6.0

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:
   • \WebContent\.classpath
   • \WebContent\.project
   • \WebContent\.websettings
   • \WebContent\.serverPreference

   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:
   • Updates iSeries Web components, Tag Libraries, and JavaScript files (updating all JSP files accordingly).
   • Regenerates Web-interaction-related files based on struts-framework from the .wit files, and updates Web interaction runtime files.
   • Adds support for new iSeries Web tools function available in Version 6.0

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:

• Ensure that you restore a new version of the QDTSSFL subfile service program on your iSeries host. This service program is required for manipulating the subfile user space with the subfile APIs. For the instructions to restore the service program, see the "Subfile service program QDTSSFL" help topic. Click Help > Help contents, then click Reference > User interface reference > iSeries Web applications > iSeries Web components > Subfile APIs.
• The data format array returned from a host program for a Combo Box Web component can now be in one of two formats. As a result, you may need to change your program to obtain the desired data format result in the combo box. For more information about data formats, see the "Data tab" section in the online help under Reference > User interface reference > iSeries Web applications > iSeries Web components > Combo Box Web component.

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:

• The following Table design-time control (DTC) properties are no longer supported in the equivalent Table Web component:
  • Cell padding
  • Cell spacing
  • Border size
  • Alignment
  • Table width
  • Table height
• The Cell Foreground and Cell Background properties of a Table DTC do not apply individually to the Column colors of a Table Web component. The color that is used for all columns is the color that is defined for the first column of the table.
• The Visible width, Caps Lock, and Read only properties associated with an Entryfield column in a Table DTC are not supported in the equivalent Text Entry column in a Table Web component.
• The Page Up button, Page Down button, and Selection Column button in the Subfile DTC are not supported in the equivalent Table Web component.
• Field name values specified in DTCs are migrated to Name values in the equivalent Web components. All periods (the . character) are replaced with underscores (the _ character) in the Name value. Also, the first character of the Field name for a DTC may be converted to lowercase in the Name value for the equivalent Web component.
• You can no longer change a Web component attribute at run time when a specified condition occurs. If you used the DTC Runtime attributes tab to define a condition that, when met, changes a DTC attribute at run time (for example, a change in the font size), the corresponding Web component attribute no longer changes when this condition occurs.

Warning and error messages for Web project migration

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:

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

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:

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:

• iSeries
• IBM
• WebSphere

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.