IBM WebSphere Development Studio Client for iSeries, Version 6.0, Migration Guide
iSeries: Getting ready to migrate
iSeries: Migrating specific types of projects
Notices
This information explains how to migrate your projects to WebSphere
Development Studio Client for iSeries Version 6.0 and WebSphere
Development Studio Client Advanced Edition for iSeries Version 6.0 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/v6/migr/migrenu.html).
This file is available in the following national languages:
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.
Important: If you currently have Development Studio Client
for iSeries Version 4.x and want to install WebSphere Development
Studio Client for iSeries Version 6.0, the installation process
uninstalls your previous version of the product. Locating your
workspace in Version 4.0 should be done before the installation of
Version 6.0. All other sections may be done
post-installation.
The installation process does not automatically uninstall Version
5.x 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.x or 5.1.2, we recommend that you note the location of
your Version 5.x or 5.1.2 workspace, and also make a
backup copy of it. If you do not back up your workspace, you might lose
your Version 5.x or 5.1.2 projects. (By default
these projects are not uninstalled or deleted.)
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 you
installed the product.
- 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):
- In the Version 5.1.2 workbench, switch to the Navigator
view: click Window > Show View > Other. Expand
Basic and select Navigator. Click
OK.
- Right-click the name of the resource and select
Properties.
- In the left pane, click Info.
The location of the resource appears in the right pane.
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 you installed the product.
- 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):
- In the Version 5.1 workbench, switch to the Navigator view:
click Window > Show View > Other. Expand Basic
and select Navigator. Click OK.
- Right-click the name of the resource and select
Properties.
- In the left pane, click Info.
The location of the resource appears in the right pane.
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 you installed the product.
- 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):
- In the Version 5 workbench, switch to the Navigator view: click
Window > Show View > Other. Expand Basic and
select Navigator. Click OK.
- Right-click the name of the resource and select
Properties.
- In the left pane, click Info.
The location of the resource appears in the right pane.
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):
- In the Version 4.0 workbench, switch to the Navigator view:
Click Perspective > Show View > Other. Expand
Basic and select Navigator. Click
OK.
- Right-click the name of the resource and select
Properties.
- In the left pane, click Info.
The location of the resource appears in the right pane.
- 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.
- When prompted to confirm that you want to convert to the new workspace
format, click OK.
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.
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
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: 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:
- Close the perspective by selecting Window -> Close
Perspective.
- 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.
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.
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.
In Version 6.0, 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.
- When you start the Version 6.0 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.
- If you are prompted to confirm that you want to convert to the new user
interface format, click OK.
- Remove runtime .jar files by changing the project's Java build
path:.
- Right-click on the Java project and select Properties.
- In the left pane, select Java Build Path.
- 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. 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.
If you are a program call service bean user, you should know that in
Version 6.0 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 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.
- When you start the Version 6.0 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.
- If prompted to confirm that you want to convert to the new user interface
format, click OK.
- (Optional step: Use the J2EE Migration wizard to migrate from J2EE
level 1.2 to a higher J2EE level.)
- Delete iwdtrt.jar and jt400.jar from the WEB-INF\lib
folder.
- 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.
- 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 on
how to migrate your Web services.
This section describes how to migrate program call beans created in
Development Studio Client for iSeries Version 5.0 to Version
6.0.
- When you start the Version 6.0 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.
- If prompted to confirm that you want to convert to the new user interface
format, click OK.
- Remove runtime .jar files by changing the project's Java build
path:.
- Right-click on the Java project and select Properties.
- In the left pane, select Java Build Path.
- 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.
To migrate the contents of the Web content folder:
- When you start the Version 6.0 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.
- Switch to the Resource perspective.
- 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.
- Select the Web content folder of the newly created project, right-click
and select Import from the context menu.
- 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.
- 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.
- 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:
- Select the Java source folder of the newly created project, right-click
and select Import from the context menu.
- 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.
- 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.
- 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:
- Now select the newly created project, right-click and select
Import from the context menu.
- Choose File System as the import source and click
Next. Click the Browse button and select the
existing 5.0 Web project.
- 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.
- 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
so the files are re-created as necessary.
- 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.
- (Optional step: Use the J2EE Migration wizard to migrate from J2EE
level 1.2 to a higher J2EE level.)
- Delete iwdtrt.jar and jt400.jar from the WEB-INF\lib
folder.
- 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 on how to migrate your Web
services.
This section describes how to migrate program call beans created in
Development Studio Client for iSeries Version 4.0 to Version
6.0.
- When you start the Version 6.0 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.
- When prompted to confirm that you want to convert to the new user
interface format, click OK.
- Remove runtime .jar files by changing the project's Java build
path:
- Right-click on the Java project and select Properties.
- In the left pane, select Java Build Path.
- 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
- 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.
To migrate the contents of the Web content folder:
- When you start the Version 6.0 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.
- Switch to the Resource perspective.
- 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.
- Select the Web content folder of the newly created project, right-click
and select Import from the context menu.
- 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.
- 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.
- 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:
- Select the Java source folder of the newly created project, right-click
and select Import from the context menu.
- 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.
- 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.
- 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:
- Now select the newly created project, right-click and select
Import from the context menu.
- Choose File System as the import source and click
Next. Click the Browse button and select the
existing 4.0 Web project.
- 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.
- 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
so the files are re-created as necessary.
- 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.
- (Optional step: Use the J2EE Migration wizard to migrate from J2EE
level 1.2 to a higher J2EE level.)
- Delete wdt400rt.jar and wdt400tb.jar from the WEB-INF\lib
folder.
- Rerun the Program Call wizard on all the PCML files.
- This migration applies only to Service beans themselves.
Ever since Version 5.1, 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 on how to migrate your
Web services.
If you have existing projects from Version 5.1.x, you
can specify the older workspace when you start the Version 6.0
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 some previous releases do not appear in a
Version 6.0 tree view.
The first time you convert a DDS file, the project structure is updated to
reflect a new layout that was established in 5.1.2. For
example, new runtime jar files and template files are imported. This
occurs in the same way that it would if you specifically selected the Import
wizard.
You cannot open a 4.0 or 5.0 workspace without using the
WebFacing import wizard.
If you have WebFacing projects from WebSphere Development Studio
Client, Version 5.1 or 5.1.2, you can migrate these to
WebSphere Development Studio Client for iSeries Version 6.0 by using
the Import wizard. Follow these steps:
- Select File > Import.
- Choose WebFacing Projects. Click Next.
- Browse to the folder that contains the WebFacing projects that
you want to migrate to Version 6.0. Click
Next.
- Note:
- When you upgrade to Version 6.0, WebFacing projects remain available
in your original workspace directory.
- 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.
- Click Finish to migrate the project to the Version 6.0
workspace.
- To see the project in the WebFacing perspective, select Window > Open
Perspective > WebFacing.
The original files have new names with the following format:
filename +_60_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
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 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.
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.
The migration activities involve the following stages:
- Migrating projects using an existing 5.1.x
workspace
- Migrating iSeries Web project contents
- Addressing errors and warnings generated as a result of the migration
In Version 6.0, 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 will continue to function using the old
names.
- When you start the Version 6.0 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.
- If prompted to confirm that you want to convert to the new user interface
format, click OK.
- 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 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, then any automated build scripts you have must be manually updated
with the new folder names.
If you created Struts 1.1 Beta 2 Web projects 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:
- 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.
- For each Struts 1.1 Beta 2 project that you want to convert to
Struts 1.1, do the following:
- Delete the following .jar files from your project's Web
Content/WEB-INF/lib directory: commons-*.jar and
struts.jar.
- 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.
- Delete the following .tld files from your project's Web
Content/WEB-INF directory: struts-*.tld.
- Copy the following .tld files from
Struts11/WebContent/WEB-INF directory to your project's
Web Content/WEB-INF directory:
struts-*.tld.
To migrate iSeries Web Tools project contents:
- 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.
- 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.
- 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.
- To continue the process, click OK. The Progress
Information window shows the progress of the migration.
- When the migration is finished, a message indicates the results.
- 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.
- 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
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 projects migration.
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.
The migration activities involve the following stages:
- Migrating projects using an existing 5.0 Web project on the
file system
- Migrating iSeries Web project contents
- Addressing errors and warnings generated as a result of the migration
In Version 6.0, 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 will continue to function using the old
names.
To migrate the contents of the Web content folder:
- When you start the Version 6.0 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.
- Switch to the Resource perspective.
- 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.
- Select the Web content folder of the newly created project, right-click
and select Import from the context menu.
- 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.
- 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.
- 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
- 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:
- Select the Java source folder of the newly created project, right-click
and select Import from the context menu.
- 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.
- 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.
- 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:
- Now select the newly created project, right-click and select
Import from the context menu.
- Choose File System as the import source and click
Next. Click the Browse button and select the
existing 5.0 Web project.
- 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.
- 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
so the files are re-created as necessary.
- 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
- Right-click on WebContent/WEB-INF/web.xml. Select Open
with > Deployment Descriptor Editor.
- Go to the Servlets tab.
- Remove the Servlet entry that maps the servlet class
org.apache.struts.action ActionServlet, default name
action.
To migrate iSeries Web Tools project contents:
- 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.
- 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.
- 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.
- To continue the process, click OK. The Progress
Information window shows the progress of the migration.
- When the migration is finished, a message indicates the results.
- 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.
- 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
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 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
WebSphere Development Studio Client for iSeries Version
6.0.
The migration activities involve the following stages:
- Migrating projects using an existing 4.0 Web project on the
file system
- Migrating iSeries Web project contents
- Addressing errors and warnings generated as a result of the migration
In Version 6.0, 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 will continue to function using the old
names.
To migrate the contents of the Web content folder:
- When you start the Version 6.0 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.
- Switch to the Resource perspective.
- 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.
- Select the Web content folder of the newly created project, right-click
and select Import from the context menu.
- 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.
- 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.
- 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:
- Select the Java source folder of the newly created project, right-click
and select Import from the context menu.
- 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.
- 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.
- 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:
- Now select the newly created project, right-click and select
Import from the context menu.
- Choose File System as the import source and click
Next. Click the Browse button and select the
existing 4.0 Web project.
- 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.
- 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
so the files are re-created as necessary.
- 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.
To migrate iSeries Web Tools project contents:
- 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.
- 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.
- 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.
- To continue the process, click OK. The Progress
Information window shows the progress of the migration.
- When the migration is finished, a message indicates the results.
- 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.
- 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
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 projects migration.
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 section "Subfile service
program QDTSSFL" under Help > Help contents then in the help system
at Reference > User interfacce 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 > Comb 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, Capslock, 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 Pageup Button, Pagedown 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 Run-time 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.
| Error code
| Description
| Action
|
| E100
| An undetermined error occurred during the migration of the JSP
file.
| Resolve or address all other errors or warnings in the migration log file
and run the migration tool again.
|
| E101
| An iSeries Web component in the JSP file has an error.
| Resolve the iSeries Web component error.
|
| E200
| Processing the .wit file resulted in an undetermined error.
| Double-click the .wit file that is in error to invoke the Web
Interaction wizard. Proceed through all of the pages of the wizard and
make any necessary changes. Click Finish.
|
| E201
| One or more Web component names defined in the pages used in this
interaction are invalid.
| Double-click the .wit file that is in error to invoke the Web
Interaction wizard. A window opens indicating that Web component names
are invalid and asks if you want to change them. Click Yes. Make
any needed changes. For any Web components that have changes input or
output parameters, complete the Name in Session, Save to session, and Link
options. Proceed through all of the pages of the wizard and make any
necessary changes. Click Finish.
|
| E202
| An output parameter defined in this interaction had the "Message
Indicator" value set to true. Advanced message handling has changed
significantly in this release. You need to redefine the Message
Handling options.
| Double-click the .wit file that is in error to invoke the Web
Interaction wizard. On the "Map and Link the Output Parameters to the
Output Fields" page, set the Message Controller value to true, select the
value "true". Now you can see the button; click it and define the
message control specifications.
|
| E300
| An undetermined error occurred processing the design comtrol (DTC) and/or
the resulting iSeries Web component.
| Resolve or address all other errors or warnings in the migration log
file. Rename the migration log file and run the migration tool
again.
|
| E301-E302
| The design control property for push buttons, Next/Previous, is no longer
supported. The Button Web component Button type attribute will be
defined as Submit.
| Use the Web Interaction wizard to create an interaction to specify the
page that contained the Next/Previous button as the input JSP page, and to
specify the target page of the Next button as the output JSP page. In
version 4.0, the Next/Previous button was used with multiple input
pages. 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.
|
| E400
| An undetermined error occurred during the migration of the code
generation template file.
| Make sure that the code generation templates are not read-only.
Address all other errors or warnings in the migration log file and run the
migration tool again.
|
| E401
| The code generation template file has been customized. Use the
newer version of the template.
| Ensure that the customizations you made to the older version of the
template have been made to the later version of the template. For
example, customized content in <workspace_location>\metadata\
plugins\com.ibm.etools.iseries.
webtools\iseriesPgmCallAction. template.bak needs to be
correctly inserted into <workspace_location>\metadata\
plugins\com.ibm.etools.iseries.
webtools\iseriesPgmCallAction. template
|
| Warning code
| Description
| Action
|
| W100
| An iSeries Web component on the JSP page has a warning.
| Address the iSeries Web component warning.
|
| W300
| A list box or combination box contained more than one character for the
delimiter property. The first character found in the delimiter property
is used for the corresponding iSeries Web component delimiter
attribute.
| Ensure that all options of the Selection Box or Combo Box Web component
have their name and value attributes defined correctly.
|
| W301-W302
| A list box or combination box contained the preselect character *, in a
Data property [key] or [value].
| Ensure that all options of the Selection Box or Combo Box Web component
have their name and value attributes defined correctly.
|
| W303
| All radio button design controls in a JSP file that have the same Group
name property now appear as an option of a Radio Button Group Web
component. The properties defined on the Font tab and Color tab for the
first radio button found in the JSP page are used as the Color and Font
attributes for the Radio Button Group. That is, Color tab and Font tab
properties are lost for subsequent radio buttons in the same group.
| Ensure that the Radio Button Group appears visually as desired within the
JSP page by selecting the associated JSP file and running the file on the
server. Ensure that Radio Button Group Font and Color attributes looks
the way you want by selecting the associated JSP file and running on the
server.
|
| W304
| The Pushbutton property Label is no longer supported. The
Pushbutton property Value has been mapped to the Label attribute of the
corresponding Button Web component. The text that appears on the Button
Web component is different than that for the Pushbutton design control.
| Change the value of the Label attribute if the text shown on the Button
Web component is not suitable.
|
| W305
| The Subfile or Table design control now appears visually outside of the
HTML FORM tag. A Table Web component cannot appear inside an HTML FORM
tag. If the design control type was Subfile, the corresponding iSeries
Web component is the Table Web component.
| Ensure that the Table Web component looks the way you want it on the JSP
page.
|
| W306-W320
| A design control event property is no longer supported.
- W306 - OnDblClick
- W307 - OnMouseDown
- W308 - OnMouseOut
- W309 - OnMouseOver
- W310 - OnSelect
- W312 - OnChange for radio buttons
- W313 - OnChange for check boxes
- W314 - OnMouseUp
- W315 - OnKeyDown for radio buttons
- W316 - OnKeyPress for radio buttons
- W317 - OnKeyUp for radio buttons
- W318 - OnKeyDown for push buttons
- W319 - OnKeyPress for push buttons
- W320 - OnKeyUp for push buttons
| If required, define the associated action with a different event.
|
| W321
| The Web component had an attribute defined that is no longer supported
because 1) the associated CSS attribute is not supported by most browsers 2)
the associated HTML attribute is already deprecated in HTML 4.0 and is
not supported by most browsers
| None.
|
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.
2000, 2005. 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:
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.
Other company, product, and service names may be trademarks or service
marks of others.