IBM WebSphere Development Studio Client for iSeries Version 5.1.2 Migration Guide
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:
- If you accepted the default location when you installed Version 5.0, 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.0 or 5.1 IDE, switch to the Navigator view: click Window > Show View > Other. Expand Basic and selectNavigator. 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 out where your Version 4.0 workspace is:
- 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 IDE, 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.
Moving from Version 5.0 or 5.1 to Version 5.1.2
Quick post-installation steps:
- 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.
- 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.
- If you have WebSphere Development Studio Client Advanced Edition for iSeries, Version 5.1.2,
the Migration Guide is migrate.html or migrate.pdf in the wsad directory on CD 1.
- Otherwise the Migration Guide is migrate.html or migrate.pdf in the wssd directory on CD 1.
The guide is also available after installation in, for example,
- C:\Program Files\IBM\WebSphere Studio\Application
Developer\v5.1\migrate.html
- C:\Program Files\IBM\WebSphere Studio\Site Developer\v5.1\migrate.html
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:
- 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.
- If prompted to confirm that you want to convert to the new user interface
format, click OK.
- Remove the old classpath 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. Re-run the Program Call wizard on all the PCML files.
For Program Call beans in a Web project:
After installation:
- 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.
- If prompted to confirm that you want to convert to the new user interface
format, click OK.
- 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.
- 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 migration will replace iwdtrt.jar and jt400.jar in the WEB-INF\lib
folder with the Version 5.1.2 jar files.
- Re-run the Program Call wizard on all the PCML files.
- Re-run the Web Services wizard on all the Web Services beans.
- 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:
- 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.
- If prompted to confirm that you want to convert to the new user interface
format, click OK.
- Remove the old classpath 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. Re-run the Program Call wizard on all the PCML files.
For Program Call beans in a Web project:
After installation:
- 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.
- If prompted to confirm that you want to convert to the new user interface
format, click OK.
- 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.
- 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 migration will replace iwdtrt.jar and jt400.jar in the WEB-INF\lib
folder with the Version 5.1.2 jar files.
- Re-run the Program Call wizard on all the PCML files.
- 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:
- 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.
- When prompted to confirm that want you to convert to the new user interface
format, click OK.
- Remove the old classpath 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
- Re-run the Program Call wizard on all the PCML files.
- 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:
- 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.
- When prompted to confirm that you want to convert to the new workspace
format, click OK.
- 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.
- Right-click the project name in the Web perspective and select Migrate > iSeries Web Tools project.
- Important: Close and reopen the project at this point, to avoid an exception
related to deletion of resources.
- The Confirm Migration window indicates that the project structure and
contents will be migrated. To continue the process, click OK.
- 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.
- Re-run the Program Call wizard on all the PCML files.
- Re-run the Web Services wizard on all the Web service beans.
- 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.
- 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:
- 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.
- When prompted to confirm that you want to convert to the new workspace
format, click OK.
- In the main menu, click Window > Preferences.
- In the left pane, expand LPEX Editor and
select Parsers.
- 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.
- 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.
- 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:
- Select File > Import.
- Choose WebFacing Projects. Click Next.
- 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.
- 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 5.1.2 workspace.
- 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:
- PageBuilder.jsp
- CmdKeys.jsp
- logon.jsp
- index.html
- If the previous project was Struts-enabled, then the Struts configuration
files (struts-config.xml) must be updated.
- If the previous project used Web Site Designer, then the following files
must be updated:
- \WebContent\index.jsp
- \WebContent\INV1.jsp
- \WebContent\INV2.jsp
- \WebContent\theme\WFB_blue.jtpl
Migrating iSeries Web projects
The following methods can be used to migrate iSeries Web projects:
- Migrating iSeries Web projects using an existing WebSphere Development
Studio Client Version 5.0.x or 5.1 workspace
This migration involves using
your existing workspace in the IDE in Version 5.1.2 and running the iSeries Web
Tools migration routine.
- Migrating iSeries Web projects using an existing WebSphere Development
Studio Client Version 4.0 workspace
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.
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:
- Migrating projects using an existing 5.0.x or 5.1 workspace
- Migrating iSeries Web project contents
- 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:
- 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.
- 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 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:
- Load your Struts 1.1 Beta 2 projects into a IBM WebSphere Studio Application
Developer Version 5.1.2 workspace.
- 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.
Stage 2: Migrating iSeries Web project contents
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 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.
- Important: Close and reopen the project at this point to avoid an exception
related to deletion of resources.
- 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 5.1.2
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:
- Migrating projects using an existing V4.0.x workspace
- 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).
- Migrating iSeries Web Tools project contents
- 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:
- Commit (release) any pending changes to the repository.
- Close all perspectives and shut down the Version 4.0 product.
- 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.
- Install Development Studio Client for iSeries Version 5.1.2.
After installation:
- 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.
- When prompted to confirm that you want to update the workspace created
with a previous version of the product, click OK.
- 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.
- Open any closed projects (see Known problems and limitations).
- Verify your class path variables (see Known problems and limitations).
- 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.
- 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).
- For each EAR project, update the application.xml file.
- In a Navigator view, right-click META-INF/application.xml and select Open with > Deployment Descriptor
Editor.
- Click Yes for the message
The IBM extensions file contains deprecated absolute paths.
This can be auto-corrected... Would you like to autocorrect?
- Save and then close the editor window.
- For each server configuration, update the configuration file.
- In the Server Configuration view of a Server perspective, right-click
the server name and select Open.
- A similar autocorrect window opens.
- Click Yes.
- 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.
- Select Window > Preferences > Java > Installed
JREs.
- In the list, select the check box for the default JRE location that you
have your JRE_LIB set to.
- 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.
- If you select the Team > Share Project option,
a wizard guides you through the migration process. When you are finished,
your project is shared and the Synchronize view opens. Conflicting changes
will appear on every file. This is due to changes in the way sync information
is stored between Eclipse 1.0 and 2.0.
- If you do not have any outgoing changes (which you should not have if
you committed all of your outgoing changes before upgrading as recommended
above), simply select the project in the Synchronize view and select Override and Update which loads the current contents from the server.
- If you do have outgoing changes, pull down the triangle menu in the Synchronize
view and select Compare File Contents. After
some work, the Synchronize view will show you only the files which are actually
different. You can then use the Synchronize view to resolve these conflicts.
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:
- Migrate the Web project structure or J2EE project structure from Version
4.0 to Version 5.1.2.
- Optionally, migrate J2EE level 1.2 to level 1.3.
To migrate to the J2EE project structure:
- If not already open, open the Version 5.1.2 IDE by selecting the product from
the Start > Programs menu.
- In the IDE, select Window > Open Perspective
> Web to open the Web perspective.
- Right-click the project name in the Project Navigator view of the Web
perspective and select Migrate > J2EE Migration
Wizard.
- 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.
- 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:
- 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.
- Important: Close and reopen the project at this point, to avoid an exception
related to deletion of resources.
- Right-click the project name in the Project Navigator view of 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 opens indicating that the migration operation
is taking place, and shows the progress of the migration.
- On completion of the migration process, a Warning, Error, or Success message
window indicates the results of the migration.
- 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.
- 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:
- Converts all design-time controls in JSP files to the new Web component
fields and controls.
- Regenerates Web interaction-related files based on the struts-framework
from the .wit files, and updates Web interaction run-time files.
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:
- 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 interface reference >
iSeries Web applications > iSeries Web components > Subfile APIs.
- The data format array returned from a host program for a Combo Box Web
component can now be in one of two formats. As a result, you may need to change
your program to obtain the desired data format result in the combo box. For
more information about data formats, see the "Data tab" section in
the online help under Reference > User interface
reference > iSeries Web applications > iSeries Web components > Comb Box Web
component.
- The data format array returned from a host program for a Selection 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 selection
box. For information about data formats, see the "Data tab" section
in the online help under Reference > User interface
reference > iSeries Web applications > iSeries Web components > Selection
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.
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:
- 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.
- 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:
- Right-click on the iSeries project, and select Properties > iSeries Project.
- 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.
- 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.)
- Close Version 4.0 and uninstall it.
- Continue with the installation of Development Studio Client for iSeries Version 5.1.2.
After installation:
- In Version 5.1.2, open the Remote System Explorer perspective: Click Window > Open Perspective > Remote System Explorer.
- Navigate to the associated library of your iSeries project. This library
contains all the source that you uploaded from the iSeries project.
- 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:
- In the main menu, click Window > Open Perspective > Resource. Click OK.
- 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.
- Select File > Import > File System. Click Next.
- Navigate to your old workspace and import the project you want to recreate.
(See the sections on finding your workspace under Before you begin.)
- 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.
- 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.
- Now drag and drop source members from the old project to the new Version 5.1.2 project.
- 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 |
*
 |
* 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.