IBM WebSphere Development Studio Client for iSeries Version 5.1.2 Migration Guide


Contents

About this information
Before you begin
Moving from Version 5.0 or 5.1 to Version 5.1.2
Pre-requisite migration steps
Advanced Edition only: Migrating J2EE projects to use EJB Client JAR support
Advanced Edition only: Migrating J2EE projects to use Server Targeting support
Backward compatibility with Server Targeting support enabled
Advanced Edition only: Upgrading the embedded messaging and queuing feature from Version 5.1
Wizard generation requires 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 to Version 5.1.2
For Program Call beans in a Java project:
For Program Call beans in a Web project:
Migrating Program Call beans in iSeries Java and Web projects from Version 5.0 to Version 5.1.2
For Program Call beans in a Java project:
For Program Call beans in a Web project:
Migrating Program Call beans in iSeries Java and Web projects from Version 4.0 to Version 5.1.2
For Program Call beans in a Java project:
For Program Call beans in a Web project:
Migrating Remote System Explorer settings
Migrating from Version 4.0 to Version 5.1.2
Migrating WebFacing projects
Using the WebFacing Import wizard
Manual steps if you had customized files in your project
Migrating iSeries Web projects
Migrating Version 5.0.x and 5.1 iSeries Web projects to Version 5.1.2
Stage 1: Migrating projects using an existing 5.0.x or 5.1 workspace
Stage 2: Migrating iSeries Web project contents
Stage 3: Addressing errors and warnings generated as a result of the migration
Migrating Version 4.0 iSeries Web projects to Version 5.1.2
Stage 1: Migrating projects using an existing V4.0.x workspace
Stage 2: Migrating the Web project structure to the J2EE 1.3 project structure
Stage 3: Migrating iSeries Web Tools project contents
Stage 4: Addressing errors and warnings generated as a result of the migration
Warning and Error messages for Web projects migration
Migrating iSeries projects
Migrating iSeries projects from Version 5.0 to Version 5.1.2:
Migrating iSeries projects from Version 4.0 to Version 5.1.2:
If you still have Development Studio Client for iSeries Version 4.0 installed:
If you have already installed Development Studio Client for iSeries Version 5.1.2 and you know that you have not uploaded your projects to the remote host
Notices
COPYRIGHT LICENSE:
Programming interface information
Trademarks and service marks

About this information

This information describes how to migrate your projects from IBM WebSphere Development Studio Client for iSeries, Version 4.0, 5.0 or 5.1.

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 of the product.

For some special cases, related to Java Tools, Web Tools, and customization of WebFacing projects, you may need use a migration tool or do extra manual steps.

The latest version of this document is available on the Web.

Before you begin

Important: If you currently have Development Studio Client for iSeries Version 4.0 or Version 5.0 or 5.1 and want to install WebSphere Development Studio Client Version 5.1.2, the installation process uninstalls your previous version of the product. Before uninstalling Development Studio Client for iSeries Version 4.0, 5.0 or 5.1, we recommend that you note the location of your Version 4.0, 5.0 or 5.1 workspace, and also make a backup copy of it. If you do not back up your workspace, you might lose your Version 4.0, 5.0 or 5.1 projects. (By default these projects are not uninstalled or deleted.)

To find out where your Version 5.0 or 5.1 workspace is:

To find out where your Version 4.0 workspace is:

Moving from Version 5.0 or 5.1 to Version 5.1.2

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

This guide contains other information you should read before installing Version 5.1.2. However, if you have already installed, you can find the guide in, for example, X:\WDSC\install\help\migrate.htm.

If you want specific information about how migration to Version 5.1.2 might affect your workspace or projects, you can read the applicable sections of the migration guide supplied with your base WebSphere Studio product. The location of the guide depends on which edition of Development Studio Client you have on your system.

The guide is also available after installation in, for example,

Pre-requisite migration steps

Advanced Edition only: Migrating J2EE projects to use EJB Client JAR support

In Version 5.1.x, the EJB Client JAR function is available. This function by default is disabled and you need to enable the function in the J2EE preferences page by selecting Window > Preferences > J2EE. Functional details about the EJB Client JAR support function can be found in the product documentation.

When the function is enabled you have an option to create an EJB Client JAR project when you create an EJB 1.1 or EJB 2.0 project. EJB projects that take advantage of the EJB Client JAR support are not backward compatible with earlier versions, hence cannot be shared with users working on earlier versions. The reason for this is that all interface classes, key, and supporting classes are created (case of new EJB projects) or moved (case of existing EJB projects) to the EJB Client JAR Java(TM) project which is added as a utility jar project to the EAR project the EJB project belongs to.

Advanced Edition only: Migrating J2EE projects to use Server Targeting support

In Version 5.1.x, the Server Targeting function is available. This function by default is disabled and you need to enable the function in the J2EE preferences page by selecting Window > Preferences > J2EE. Functional details about the Server Targeting function can be found in the product documentation.

When the function is enabled you have the option to target a particular application server. This feature has been implemented to support JDK 1.4, which is the JRE for WebSphere(R) Application Server Version 5.1 that is shipped with the product. J2EE projects that take advantage of the Server Targeting support are not backward compatible with earlier versions of the product, hence cannot be shared with users working on earlier versions. The product provides a way to get backward compatibility with this feature enabled and is described in Backward compatibility with Server Targeting support enabled. The reason for this incompatibility is that the Server Targeting function changes the .classpath file on a J2EE project and the new .classpath file entries cannot be recognized by earlier versions of the product.

Backward compatibility with Server Targeting support enabled

With the Server Targeting support enabled, J2EE projects targeted to a server can be reverted back to not use the Server Targeting support by modifying the target server to a No target server specified option available in the Modify Target Server dialog. The Modify Target Server dialog is launched from the pop-up menu (Target Server > Modify) on a J2EE project in the Resource Navigator or the J2EE Perspective view. The target server can also be modified to a No target server specified from the J2EE properties page (Properties > J2EE) for EAR, EJB, Application Client and Connector projects. For a Web project the target server setting is in the Web properties page (Properties > WEB). Functional details about the Server Target modify function can be found in the product documentation.

When the No target server specified option is used the .classpath file is reverted back to the style that is compatible with earlier versions of the product and the .server is removed from the project.

Note:
Only Server Targeted J2EE projects can be deployed on WebSphere Application Server Version 5.1 and take advantage of JDK 1.4 support.

Advanced Edition only: Upgrading the embedded messaging and queuing feature from Version 5.1

If you are upgrading the embedded messaging and queuing feature from Version 5.1 to Version 5.1.x, you must reinstall the embedded messaging and queuing feature using the installation program that is packaged with Version 5.1.x. This installation program will re-configure the WebSphere MQ and WebSphere Messaging Publish and Subscribe components correctly, but will not reinstall them.

Wizard generation requires a Java package for JDK 1.4

Due to a change in the JDK 1.4, you must specify a Java package when using the Database Web Pages and Java Bean Web Pages wizards to generate pages to run on Version 5.1.x. This problem occurs if the View Bean template is used for the Java Bean Web Pages wizard or the IBM(R) Database Access Java Beans-Master Details Pattern. This also applies to projects that contain pages and .java files previously generated with these wizards that 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 to Version 5.1.2

This section describes how to migrate Program Call beans created in Development Studio Client for iSeries Version 5.0 to Version 5.1.2.

For Program Call beans in a Java project:

After installation:
  1. When you start the Version 5.1.2 product (Start > Programs > IBM WebSphere Studio > Development Studio Client for iSeries), a WebSphere Studio 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 the old classpath 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. Re-run the Program Call wizard on all the PCML files.

For Program Call beans in a Web project:

After installation:
  1. When you start the Version 5.1.2 product (Start > Programs > IBM WebSphere Studio > Development Studio Client for iSeries), a WebSphere Studio 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. Use the J2EE Migration wizard to:
    • Convert the project structure to Version 5.1.2
    • Optionally migrate from J2EE level 1.2 to level 1.3.
  4. Right-click the project name in the Web perspective and select Migrate > iSeries Web Tools project.
  5. The Confirm Migration window indicates that the project structure and contents will be migrated. To continue the process, click OK.
  6. The migration will replace iwdtrt.jar and jt400.jar in the WEB-INF\lib folder with the Version 5.1.2 jar files.
  7. Re-run the Program Call wizard on all the PCML files.
  8. Re-run the Web Services wizard on all the Web Services beans.
  9. This migration applies only to the Web Services beans themselves. Code generated by the Web Services wizard requires manual migration and cleanup.

Migrating Program Call beans in iSeries Java and Web projects from Version 5.0 to Version 5.1.2

This section describes how to migrate Program Call beans created in Development Studio Client for iSeries Version 5.0 to Version 5.1.2.

For Program Call beans in a Java project:

After installation:
  1. When you start the Version 5.1.2 product (Start > Programs > IBM WebSphere Studio > Development Studio Client for iSeries), a WebSphere Studio 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 the old classpath 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. Re-run the Program Call wizard on all the PCML files.

For Program Call beans in a Web project:

After installation:
  1. When you start the Version 5.1.2 product (Start > Programs > IBM WebSphere Studio > Development Studio Client for iSeries), a WebSphere Studio 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. Use the J2EE Migration wizard to:
    • Convert the project structure to Version 5.1.2
    • Optionally migrate from J2EE level 1.2 to level 1.3.
  4. Right-click the project name in the Web perspective and select Migrate > iSeries Web Tools project.
  5. The Confirm Migration window indicates that the project structure and contents will be migrated. To continue the process, click OK.
  6. The migration will replace iwdtrt.jar and jt400.jar in the WEB-INF\lib folder with the Version 5.1.2 jar files.
  7. Re-run the Program Call wizard on all the PCML files.
  8. Re-run the Web Services wizard on all the Web Services beans.

Migrating Program Call beans in iSeries Java and Web projects from Version 4.0 to Version 5.1.2

This section describes how to migrate Program Call beans created in Development Studio Client for iSeries Version 4.0 to Version 5.1.2.

For Program Call beans in a Java project:

After installation:
  1. When you start the Version 5.1.2 product (Start > Programs > IBM WebSphere Studio > Development Studio Client for iSeries), a WebSphere Studio 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 want you to convert to the new user interface format, click OK.
  3. Remove the old classpath 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. Re-run the Program Call wizard on all the PCML files.
  5. This migration applies only to the Program Call beans themselves. Code generated by the Program Call wizard requires manual migration and cleanup.

For Program Call beans in a Web project:

After installation:
  1. When you start the Version 5.1.2 product (Start > Programs > IBM WebSphere Studio > Development Studio Client for iSeries), a WebSphere Studio 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 workspace format, click OK.
  3. Use the J2EE Migration wizard to:
    • Convert the project structure to Version 5.1.2
    • Optionally migrate from J2EE level 1.2 to level 1.3.
  4. Right-click the project name in the Web perspective and select Migrate > iSeries Web Tools project.
  5. Important: Close and reopen the project at this point, to avoid an exception related to deletion of resources.
  6. The Confirm Migration window indicates that the project structure and contents will be migrated. To continue the process, click OK.
  7. The migration will remove the wdt400rt.jar and wdt400tb.jar from the WEB-INF\lib folder and copy the Version 5.1.2 iwdtrt.jar and jt400.jar into the folder.
  8. Re-run the Program Call wizard on all the PCML files.
  9. Re-run the Web Services wizard on all the Web service beans.
  10. In Version 5.0, Web Services beans could be generated in the default package. Since Version 5.1, the beans must be generated in a named package before you invoke the Web Services wizard.
  11. This migration applies only to the Web Services beans themselves. Code generated by the Web Services wizard requires manual migration and cleanup.

Migrating Remote System Explorer settings

Migrating from Version 4.0 to Version 5.1.2

After installation:
  1. When you start the Version 5.1.2 product (Start > Programs > IBM WebSphere Studio > Development Studio Client for iSeries), a WebSphere Studio 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 workspace format, click OK.
  3. In the main menu, click Window > Preferences.
  4. In the left pane, expand LPEX Editor and select Parsers.
  5. In the right pane, select ILErpg. In the Class name field at the bottom, change the class name to com.ibm.etools.iseries.editor.ISeriesEditorRPGILEParser. Click Set.
  6. In the right pane, select rpg. In the Class name field at the bottom, change the class name to com.ibm.etools.iseries.editor.ISeriesEditorRPGOPMParser. Click Set.
  7. Click Apply. Click OK.

Migrating WebFacing projects

If you have existing projects from Version 4.0, 5.0.x, or 5.1.x, you can specify the older workspace when you start the 5.1.2 workbench and the 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 previous releases do not appear in a 5.1.2 tree view.

The first time you convert a DDS file, the project structure is updated to reflect the new 5.1.2 layout. For example, new runtime jar files and template files are imported. This occurs in the same way that it would if you specifically selected the Import wizard.

Using the WebFacing Import wizard

If you have WebFacing projects from WebSphere Development Studio Client, Version 4.0, 5.0 or 5.1, you can migrate these to Development Studio Client Version 5.1.2 by using the Import wizard. Follow these steps:

After installation:
  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 5.1.2. Click Next.
    Note:
    When you upgrade to Version 5.1.2, WebFacing projects remain available in your original workspace directory.
    • If you are migrating from Development Studio Client 5.0 or 5.1, see the sections on finding your workspace under Before you begin.
  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 5.1.2 workspace.
  6. To see the project in the WebFacing perspective, select Window > Open Perspective > WebFacing.

Manual steps if you had customized files in your project

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

If you customized your WebFacing project, the 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.0.x and 5.1 iSeries Web projects to Version 5.1.2

The following information describes how to migrate iSeries Web projects from Development Studio Client for iSeries Version 5.0.x and 5.1 to Development Studio Client for iSeries Version 5.1.2.

The migration activities involve the following stages:

  1. Migrating projects using an existing 5.0.x or 5.1 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.0.x or 5.1 workspace

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

After installation:
  1. When you start the Version 5.1.2 product (Start > Programs > IBM WebSphere Studio > Development Studio Client for iSeries), a WebSphere Studio window opens in which you specify the directory to use for the session. Specify the directory location of your Version 5.0.x or 5.1 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 Project. In the right pane, set the preferences for your default folder names.

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

Optional: Converting Web projects to Struts 1.1

The Struts tools run-time has stepped up from Version 1.1 Beta 2 in Version 5 to Version 1.1. In IBM WebSphere Studio Application Developer Version 5 (General Availability) when you create a Web project, you have the option to add Struts support to your project. You can choose either Struts 1.0.2 or Struts 1.1 Beta 2. In IBM WebSphere Studio Application Developer Version 5.1.x, the latter choice is replaced by 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 wish to convert to Struts 1.1, you will need to do the following:

  1. Load your Struts 1.1 Beta 2 projects into a IBM WebSphere Studio Application Developer Version 5.1.2 workspace.
  2. 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.
  3. 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 Add Struts support 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.
  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 and that they are in migration log file projectName_MigrationDetails.txt under the project name in the Web perspective.

The Migration Result section at the top of the migration log file indicates the overall status of the migration and refers to a file in the online information that describes the errors and warnings and the action required to correct them. See Warning and Error messages for Web projects 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 5.1.2

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

The migration activities involve the following stages:

  1. Migrating projects using an existing V4.0.x workspace
  2. Migrating the Web project structure and optionally the J2EE version of the project
    Note:
    Migrating the Web project to J2EE 1.3 is optional. However, J2EE 1.2 does not support JCA (Java Connector Architecture).
  3. Migrating iSeries Web Tools project contents
  4. Addressing errors and warnings generated as a result of the migration

Stage 1: Migrating projects using an existing V4.0.x workspace

This approach is partially supported, and results in an incomplete migration. User interface settings, debug settings, and most preferences are all lost. Project names, project source files, and project Java build path (class path) are retained, but nothing else is guaranteed. Take this approach only if no supported software configuration management (SCM) system is being used and if it is critical to retain project build path information, which is lost when you import projects to Version 5.1.2 that have been exported from Version 4.0. You can use the existing Version 4.0.x workspace by doing the following:

Before installation:
  1. Commit (release) any pending changes to the repository.
  2. Close all perspectives and shut down the Version 4.0 product.
  3. Back up the contents of workspace_directory, where workspace_directory is the fully qualified directory name that contains the Version 4.0.x workspace. By default, the Version 4.0.x workspace subdirectory is located in the same directory where the product is installed. You will need this backup if you ever want to work with the Version 4.0.x product again. Once you have pointed to a Version 4.0.x workspace from a Version 5.1.2 IDE, you can no longer go back to using that workspace in the Version 4.0.x product.
  4. Install Development Studio Client for iSeries Version 5.1.2.
After installation:
  1. When you start the Version 5.1.2 product (Start > Programs > IBM WebSphere Studio > Development Studio Client for iSeries), a WebSphere Studio window opens in which you specify the directory to use for the session. Specify the directory location of your Version 4.0.x workspace in this window.
  2. When prompted to confirm that you want to update the workspace created with a previous version of the product, click OK.
  3. Before doing any rebuilds or validating any projects that are in the workspace, select all of the projects in the Navigator view within the Resource perspective and then select Refresh from the pop-up menu. This ensures that all files are synchronized with their appropriate metadata.
  4. Open any closed projects (see Known problems and limitations).
  5. Verify your class path variables (see Known problems and limitations).
  6. Some builders and validators have been added, removed, or modified in this version. To ensure that the correct errors and warnings are shown, you must rebuild all the projects by selecting Project > Rebuild All, and then select Run Validation for each Java project.
  7. Some user preferences might be maintained, but many others will not be. Check your preference settings in Version 5.1.2 to be sure that they are as you want them.

Post-migration removal of EAR and Server Configuration absolute path references

Version 4.0 EAR application.xml files and server configuration files contained absolute path references. After you have migrated them into Version 5.1.2, you need to open them with their editor (which automatically changes their old absolute path references into new relative references).

  1. For each EAR project, update the application.xml file.
    1. In a Navigator view, right-click META-INF/application.xml and select Open with > Deployment Descriptor Editor.
    2. Click Yes for the message
      The IBM extensions file contains deprecated absolute paths.
      This can be auto-corrected... Would you like to autocorrect?
    3. Save and then close the editor window.
  2. For each server configuration, update the configuration file.
    1. In the Server Configuration view of a Server perspective, right-click the server name and select Open.
    2. A similar autocorrect window opens.
    3. Click Yes.
    4. Save and then close the editor window.

Known problems and limitations

The following problems may occur if you attempt to migrate by opening a Version 4.0 workspace in the Version 5.1.2 product.

Incorrect value in the JRE_LIB class path variable

To reset your JRE_LIB class path variable to a valid location, follow these steps. Do this even if the value seems correct when you first open the Preferences window.

  1. Select Window > Preferences > Java > Installed JREs.
  2. In the list, select the check box for the default JRE location that you have your JRE_LIB set to.
  3. Choose Edit, and then click OK to close the Edit JRE dialog box.

If you do not do this, the value for JRE_LIB might be incorrect, causing many build errors in Java files.

As a general check, verify the value of all your other class path variables.

For previously SCM shared projects, the Team menu contains Share Project

Team support has changed significantly between Eclipse 1.0 and 2.0. The method of sharing projects with the repository has changed as well.

Projects created outside the workspace directory

By default, projects are created in the workspace directory. If you overrode the default to create projects elsewhere, open all of your projects now before closing the workbench. This allows the .project file for that project to be written in the proper location. Failure to open a closed project whose directory is outside of the workspace results in a project that masks the actual project, with only a .project file existing within it.

Stage 2: Migrating the Web project structure to the J2EE 1.3 project structure

Note that the J2EE Migration Wizard can perform two functions:

To migrate to the J2EE project structure:

  1. If not already open, open the Version 5.1.2 IDE by selecting the product from the Start > Programs menu.
  2. In the IDE, select Window > Open Perspective > Web to open the Web perspective.
  3. Right-click the project name in the Project Navigator view of the Web perspective and select Migrate > J2EE Migration Wizard.
  4. Follow the instructions on the wizard pages. If you intend to use the JCA (Java Connector Architecture) support, ensure that you select the check box Migrate project from version level J2EE 1.2 to J2EE 1.3.
  5. Click Finish to migrate the selected Web project.

Stage 3: Migrating iSeries Web Tools project contents

The following migration process is dependent on successful migration of the Web project to the J2EE project structure described in the preceding section.

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 Add Struts support if it is not already selected. Press OK. Press 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 you to add Struts support.
  2. Important: Close and reopen the project at this point, to avoid an exception related to deletion of resources.
  3. Right-click the project name in the Project Navigator view of the Web perspective and select Migrate > iSeries Web Tools project.
  4. The Confirm Migration window indicates that the project structure and contents will be migrated. To continue the process, click OK.
  5. The Progress Information window opens indicating that the migration operation is taking place, and shows the progress of the migration.
  6. On completion of the migration process, a Warning, Error, or Success message window indicates the results of the migration.
  7. To ensure that the correct errors and warnings are shown, you must rebuild the project. Select the project, then rebuild by selecting Project > Rebuild Project.
  8. If the migration process completed successfully, no further action is required. If the migration process completed with errors or warnings, proceed to Stage 4: Addressing errors and warnings generated as a result of the migration.

The migration process performs the following actions:

Stage 4: 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 and that they are in migration log file projectName_MigrationDetails.txt under the project name in the Web perspective.

The Migration Result section at the top of the migration log file indicates the overall status of the migration and refers to a file in the online information that describes the errors and warnings and the action required to correct them. See also the online help under Development Studio Client for iSeries > Web applications > iSeries Web Development > Reference > Migration error and warning details.

Additional migration considerations

In addition to any migration errors listed in the log file described in Stage 4 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 projects 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 ask if you want them changed. Click "Yes". Proceed to the wizard page "Map and Link the Input Parameters to the Input Fields" (making any necessary changes in preceding wizard pages). Specify the "Name In Session", "Save to Session", and "Link" Options for any Web components (Input fields) whose name has changed. Proceed to the wizard page "Map and Link the Output Parameters to the Output Fields". Specify the "Name In Session", "Restore from Session", and "Link" Options for any Web components (Output fields) whose name has changed. 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. Proceed to the wizard page called "Map and Link the Output Parameters to the Output Fields". In the properties window for the Output Parameter, with "Message Controller" value set to "true", select the value "true". This makes a button become visible -- click on this button to define the message control specifications.
E300 An undetermined error occurred processing the 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 Pushbutton DTC property 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. See the information under Help > Help contents then in the help system at Reference > User interface reference > iSeries Web applications > Multiple input and output pages.
Warning code Description Action
W100 An iSeries Web component on the JSP page has a warning. Address the iSeries Web component warning.
W300 A Listbox or Combobox 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 Listbox or Combobox 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 DTC's within 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 appear as desired 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 DTC. Change the value of the Label attribute if the text shown on the Button Web component is not suitable.
W305 The Subfile or Table DTC now appears visually outside of the HTML FORM tag. A Table Web component cannot appear inside an HTML FORM tag. If the DTC type was Subfile, the corresponding iSeries Web component is the Table Web component. Ensure that the Table Web component appears visually as desired on the JSP page.
W306-W320 A DTC event property is no longer supported. If required, define the associated action with a different event.
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
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.

Migrating iSeries projects

Migrating iSeries projects from Version 5.0 to Version 5.1.2:

After installation:
  1. When you start the Version 5.1.2 product (Start > Programs > IBM WebSphere Studio > Development Studio Client for iSeries), a WebSphere Studio 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. When prompted to confirm that you want to convert to the new user interface format, click OK.

If you had left the 5.0 Build Status view open in your 5.0 workbench, the following error occurs in 5.1.2:

Could not restore workbench layout

Click OK to continue. This is related to the replacement of the Build Status view in the iSeries Projects perspective with the iSeries Job Status view in the Remote System Explorer perspective. Any builds listed in the original Build Status view do not appear in the new view. When you rebuild the associated iSeries project, the new build appears in the Job Status view and ongoing function is unaffected.

After migrating, if you get a red flag on an iSeries project, this could be due to the fact that the Remote System Explorer connection associated with your project does not exist any more. To resolve this:

  1. Right-click on the iSeries project, and select Properties > iSeries Project.
  2. Set the missing connection, and click OK.

Migrating iSeries projects from Version 4.0 to Version 5.1.2:

If you still have Development Studio Client for iSeries Version 4.0 installed:

Before uninstalling Development Studio Client Version 4.0, you should export your project content to the host machine. Then, install Development Studio Client Version 5.1.2. After installation, the projects can be recreated by running an action from the Remote System Explorer.

Before installation:

If you have already installed Development Studio Client for iSeries Version 5.1.2 and you know that you have not uploaded your projects to the remote host, skip this section.

  1. In Version 4.0, right-click the iSeries project, and select Push Changes. This should upload all your code changes to the associated library of that project. (If you are not sure which host and library this project is targeting, right-click the project and select Properties > iSeries Project.)
  2. Close Version 4.0 and uninstall it.
  3. Continue with the installation of Development Studio Client for iSeries Version 5.1.2.
After installation:
  1. In Version 5.1.2, open the Remote System Explorer perspective: Click Window > Open Perspective > Remote System Explorer.
  2. Navigate to the associated library of your iSeries project. This library contains all the source that you uploaded from the iSeries project.
  3. Select the source physical files in this library that were part of your iSeries project, right-click on them and select Make Available Offline. This recreates the iSeries project that maps to this library and downloads all the source members locally into your project. You can now continue development.

    Note: selecting Create iSeries Project from a library in the Remote System Explorer is another quick way to recreate your project, but it does not download any source members from that library. It simply creates and sets up an iSeries project that maps to that library and host.

If you have already installed Development Studio Client for iSeries Version 5.1.2 and you know that you have not uploaded your projects to the remote host

After installation:
  1. In the main menu, click Window > Open Perspective > Resource. Click OK.
  2. Create a simple project by clicking File > New > Other > Simple > Project, and call it Temp. This project is a container for importing your Version 4.0 project into the Version 5.1.2 workspace.
  3. Select File > Import > File System. Click Next.
  4. Navigate to your old workspace and import the project you want to recreate. (See the sections on finding your workspace under Before you begin.)
  5. Create an iSeries project that maps to the library and host of the Version 4.0 project you just imported.
    • Right-click anywhere in the Navigator view and select New > Project > iSeries > Local > iSeries Project.
    • If you do not remember the library and host, you can find this information in an XML file called .iseries_project_properties under the Temp project.
  6. Recreate the source physical files that existed in your Version 4.0 project:
    • Click File > New > Other > iSeries > Local > iSeries Source Physical File.
    • If you are not sure what the CCSID and record length of your files were, you can find this information in an XML file called .iseries_srcpf_properties directly under each source physical file.
  7. Now drag and drop source members from the old project to the new Version 5.1.2 project.
  8. Delete the Temp project, which you no longer need, and open the iSeries Projects perspective: Click Window > Open Perspective > iSeries Projects.

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. 1992, 2002. 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:

* AIX * DB2 Extenders * Operating System/400
* AIX windows * DB2 Universal Database * OS/2
* Application System/400 * eserver graphic * Open Class
* AS/400 * IBM * OS/390
* AS/400e * IBMLink * OS/400
* C Set ++ * Integrated Language Environment * RPG/400
* COBOL/2 * iSeries * SQL/400
* COBOL/400 * Language Environment * VisualAge
* DB2 * MQSeries * WebSphere

InstallShield is a trademark of InstallShield Corporation.

Intel and Pentium are trademarks of Intel 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, in the United States, other countries or both.

ActiveX, Microsoft, SourceSafe, Visual C++, Visual SourceSafe, Windows, Windows NT, Win32, Win32s and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group.

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