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.
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:
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,
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.
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.
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.
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.
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.
This section describes how to migrate Program Call beans created in Development Studio Client for iSeries Version 5.0 to Version 5.1.2.
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
This section describes how to migrate Program Call beans created in Development Studio Client for iSeries Version 5.0 to Version 5.1.2.
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
This section describes how to migrate Program Call beans created in Development Studio Client for iSeries Version 4.0 to Version 5.1.2.
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
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.
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:
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:
The following methods can be used to migrate iSeries Web projects:
This migration involves using your existing workspace in the IDE in Version 5.1.2 and running the iSeries Web Tools migration routine.
This migration involves using your existing workspace in the IDE in Version 5.1.2 and running the iSeries Web Tools migration routine. The routine converts your Web project to the latest J2EE level.
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:
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.
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.
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:
To migrate iSeries Web Tools project contents:
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.
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:
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:
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).
The IBM extensions file contains deprecated absolute paths. This can be auto-corrected... Would you like to autocorrect?
The following problems may occur if you attempt to migrate by opening a Version 4.0 workspace in the Version 5.1.2 product.
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.
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.
Team support has changed significantly between Eclipse 1.0 and 2.0. The method of sharing projects with the repository has changed as well.
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.
Note that the J2EE Migration Wizard can perform two functions:
To migrate to the J2EE project structure:
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:
The migration process performs the following actions:
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.
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:
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. |
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:
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.
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.
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.
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.
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 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.
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 | * | * 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.