Installation and migration guide

• Hardware and software prerequisites for VisualAge(R) for Java(TM), Professional and Enterprise Editions
• How to install VisualAge for Java, Professional and Enterprise Editions
• Prerequisites and supported platforms for the team repository server (EMSRV)
• How to install the team repository server (EMSRV)
• How to prepare for the team development environment
• Limitations and known problems with installation
• How to migrate from a previous version of VisualAge for Java (both general and component-specific information)

A PDF version of this guide is also available in the pdf directory. The pdf directory is located on the VisualAge for Java, Professional Edition product CD and on the VisualAge for Java, Enterprise Edition, Additional Features CD. 

Where to find more information about VisualAge for Java

This file does not include detailed information about the specific components and features of VisualAge for Java. For that information, you should refer to the product Release Notes which you can access by selecting Start > Programs > IBM VisualAge for Java for Windows V4.0> Release Notes. For all languages, the release notes are included on the product CD (they are available after installation) and on the Web at http://www.ibm.com/vadd.  

This file does not contain information about using VisualAge for Java. Refer to the Getting Started guide and to the online help for that information. Some of the online help has been grouped into PDF documents which you can view and print using Adobe Acrobat Reader (available from http://www.adobe.com/). Not all PDFs are available in all languages. The PDF files are available from the pdf directory. The pdf directory is located on the VisualAge for Java, Professional Edition product CD and on the VisualAge for Java, Enterprise Edition, Additional Features CD. If you have an electronic version of VisualAge for Java it can be found in your temporary directory (where you extracted your parts to). If you did not download the part containing the PDFs, you will not have this directory.

See the PDF Index (in the Getting Started guide) for information on what each PDF file contains. The online help also contains a "Web Resources" section that contains links to VisualAge resources that are available on the Internet.

The VisualAge Developer Domain (VADD) Web site offers technical articles, tutorials, samples, and FAQs, along with easy access to support and product updates for VisualAge for Java. At this site, you can download the VisualAge for Java development tools, as well as reusable beans, wizards, and toolkits to complement your applet and servlet development. See http://www.ibm.com/vadd. You can also use this site to request features in upcoming releases of VisualAge for Java.

If you have already subscribed to VisualAge Developers Domain, you do not need to re-register. You can use your current ID and password to obtain ongoing information and code updates. If you are a new user, locate the subscription number in the box (or media kit) that you received. If you purchased VisualAge for Java and do not have a subscription number, contact your IBM(R) sales representative.

The product home page for VisualAge for Java home page is at http://www.ibm.com/software/ad/vajava

Table of contents

Part A: VisualAge for Java, Professional Edition

1.0 Prerequisites
2.0 Installation
      2.1 Installing VisualAge for Java, Version 4.0
      2.2 Installing additional components later
      2.3 Installation considerations for Windows(R) 2000
      2.4 Installing the IBM Developer Kit, Java Technology Edition,v1.2.2
3.0 Migrating from a previous version of VisualAge for Java
      3.1 Migrating from VisualAge for Java Version 3.5 or Version 3.5.3
      3.2 Migrating from Version 2.0, 3.0x or 3.0x Early Adopters of VisualAge for Java
4.0 Known problems and limitations
      4.1 Known problems and limitations with installation
      4.2 Known problems and limitations with uninstallation

Part B: VisualAge for Java, Enterprise Edition

1.0 Prerequisites
      1.1 General prerequisites
      1.2 Component-specific prerequisites
2.0 Installation
      2.1 Installing VisualAge for Java, Version 4.0
      2.2 Installing additional components later
      2.3 Installing the VisualAge for Java team clients
      2.4 Installing a client that has a standalone repository
      2.5 Installation and usage considerations for Windows(R) 2000
      2.6 Installing the IBM Developer Kit, Java Technology Edition, v1.2.2
3.0 Migrating from a previous version of VisualAge of Java
     3.1 Migrating a shared repository from a previous version of VisualAge for Java
4.0 Known problems and limitations
      4.1 Known problems and limitations with installation
      4.2 Known problems and limitations with uninstallation

Part C: Team repository server (EMSRV)

1.0 Prerequisites
      1.1 Supported platforms
      1.2 TCP/IP
      1.3 Novell patches required to run EMSRV on NetWare 4.x
      1.4 Solaris patch required to run EMSRV on Solaris     
      1.5 File systems supported   
2.0 Installation
     2.1 Installing EMSRV for Windows(R)
             2.1.1 Installing EMSRV as a Service in the Windows Registry
     2.2 Installing EMSRV for NetWare 
     2.3 Installing EMSRV for OS/2 (R) Warp
     2.4 Installing EMSRV for AIX
     2.5 Installing EMSRV for HP-UX/Solaris(TM)
     2.6 Installing EMSRV for Linux
3.0 Migration
      3.1 Migrating from Version 6.x/7.0 of EMSRV to Version 7.1
4.0 Preparing for team development
      4.1 Preparing the team server
      4.2 Testing a client connection
      4.3 Adding users to the repository user list
5.0 Limitations and known problems
      5.1 Performance on low-bandwidth, high-latency network connections
      5.2 TCP/IP connection limitations 
      5.3 Detecting unexpectedly dropped connections
      5.4 Interchanging different versions of EMSRV and EMSRV utilities
      5.5 PAM Limitations
      5.6 Passwords with non-ASCII characters cannot be used to authenticate with EMSRV
      5.7 Menus and windows have corrupted characters when running on Japanese NetWare
      5.8 EMADMIN does not copy stored resources directory

Part D: Component-specific migration information

1.0 CICS(R) Transaction Server  *+
2.0 Data Access beans
3.0 Data Access Builder * +
4.0 EJB(TM) Development Environment+
5.0 Enterprise Access Builder and e-connectors +
6.0 Enterprise Toolkit for AS/400(R) +
7.0 Enterprise Toolkit for OS/390(R) +
8.0 Enterprise Toolkit for Workstations * +
9.0 External Version Control
10.0 IDL Development Environment +
11.0 Integrated Development Environment
12.0 JSP/Servlet Development Environment
13.0 Migration Assistant *
14.0 Persistence Builder +
15.0 RMI Access Builder * +
16.0 Visual Composition Editor
17.0 Servlet Builder and Servlet Launcher  * +
18.0 Swing classes
19.0 XMI Toolkit +

* These components are not supported in VisualAge for Java, Version 4.0

+ Enterprise Edition only

Part E: General information

1.0 Dealing with project resources and resource management
2.0 Migrating from OS/2 and AIX
3.0 New security restrictions in J2SDK v.1.2.2
4.0 New External Version control tool (replaces External SCM tool)
5.0 Working with third-party ORBs in VisualAge for Java
6.0 Contents of the Additional Features CD

Appendixes

Appendix A: A comparison of data access features

Part A: VisualAge for Java, Professional Edition

A.1.0 Prerequisites

This edition of VisualAge for Java, Version 4.0 has the following hardware and software prerequisites:

• Windows(R) 98, Windows 2000, or Windows NT (R) 4.0 with Service Pack 4 or higher. 
• Mouse or pointing device *
• TCP/IP installed and configured
• Pentium (R) II processor or higher recommended. If you plan to work in the WebSphere(TM) Test Environment we recommend a minimum processor speed of 400 MHz.
• SVGA (800x600) display or higher (1024 x 768 recommended)
• 48 MB RAM minimum (96 MB recommended)
• To use the Distributed Debugger, you will need 128 MB RAM minimum (196 MB recommended)
• 128 MB RAM minimum is required if you wish to work in the VisualAge for Java WebSphere Test Environment. We strongly recommend 256 MB to avoid disk thrashing.
• Frames-capable Web browser such as Netscape Navigator 4.7 or higher, or Microsoft (R) Internet Explorer 5.0 or higher. You should not use anything lower than Netscape Navigator 4.7 or Internet Explorer 5.0 to view any online documentation.
• Disk space requirements: (based on NTFS) 350 MB minimum (400 MB or more recommended). Disk space on FAT depends on hard disk size and partitioning:
  If you are installing to a very large FAT drive, then the space required for VisualAge for Java is almost doubled (due to 32KB cluster overhead).

If you want to run the Websphere Application Server with DB2(R) and VisualAge for Java concurrently, then a minimum of 512 MB is recommended.

* Note: VisualAge for Java does not support the Logitech scroll mouse. Any Logitech mice with drivers that remap scrolling action to the mouse will cause a system error to occur when it is used to scroll. 

A.2.0 Installation

This section contains information about installing VisualAge for Java, Version 4.0 Important: If you are migrating from a previous version of VisualAge for Java, refer to section 3.0 before installing Version 4.0. For special information about installing on Windows 2000, refer to section 2.3.

Please also refer to the README (which can be found in the README directory of the product CD) for information about late breaking problems and limitations. 

A.2.1 Installing VisualAge for Java, Version 4.0

Before you install the product, check the following things:

• You must have at least 20 MB free on your Windows system drive, and your environment variable TEMP or TMP must point to a valid temporary directory with at least 6 MB free.
• If you are using the default target directory, then the PATH must be less than 377 characters on Windows 98, and less than 820 characters on Windows NT and Windows 2000.
• The CLASSPATH must be less than 455 characters. VisualAge for Java inserts approximately 54 characters into the CLASSPATH during installation. These numbers are based on the assumption the target directory is 36 characters long, for example, Program Files\IBM\VisualAge for Java

If you attempt to install VisualAge for Java on Windows, Millennium Edition, you will be prompted to increase your environment space. The steps outlined below must be performed before you install, otherwise the VisualAge for Java help system will not function correctly. To increase your environment space, perform the following steps:

1. Exit the Installation screen.
2. Open Windows Explorer. Browse to your Windows directory (for example, C:\Windows).
3. Right-click Command.com, and then click Properties from its pop-up menu. Click the Memory tab.
4. In the Initial Environment box, set the initial environment size to 4,096 bytes. Click OK.
5. Close Windows Explorer.
6. Reboot your computer.
7. Re-start the VisualAge for Java installation.

A.2.1.1 Installing VisualAge for Java, Version 4.0 from the product CD

1. Insert the CD-ROM into your CD drive. If you are migrating from a previous version of VisualAge for Java, read "Migrating from a previous version of VisualAge for Java" (section 3.0 of this document) BEFORE proceeding with the installation procedure.
2. If autorun is disabled on your system, run setup.exe from the root of the CD drive.
3. Select Install Products. Select Install VisualAge for Java to begin the installation of VisualAge for Java. If you intend to debug any classes developed outside the VisualAge for Java IDE or debug programs running on a separate machine, refer to section A.2.1.1.1 for information on installing the Distributed Debugger.
4. Follow the on-screen instructions.
5. Start the VisualAge for Java IDE.

Installing silently
To install VisualAge for Java, Version 4.0 silently, invoke the following command from the ivj40\setup directory:

setup /s /v/qn

VisualAge for Java will automatically be installed in the c:\Program Files\IBM\VisualAge for Java default directory.

To silently install to a different directory (for example, d:\IBMVJava40), invoke the following command from the ivj40\setup directory:

setup /s /v"INSTALLDIR=\"d:\IBMVJava40\" /qn"

where d:\IBMVJava40 is the directory you want to install to.

A.2.1.1.1 Installing the Distributed Debugger from the product CD
If you intend to debug any classes developed outside the VisualAge for Java IDE or debug programs running on a separate machine, you should install the Distributed Debugger. The Distributed Debugger is supported on the following operating systems: Windows, AIX, OS/2, HP-UX, Solaris, Linux, and Linux/390. Installation instructions for each operating system are provided below. All Distributed Debugger files are on the product CD in the Debugger directory.

 Distributed Debugger for Windows

1. Run setup.exe and select Install Products. Then select Install Distributed Debugger to install the debugger.

1. Create a scratch directory, for example /tmp/idebug
2. Copy idebug.tar.Z from the install media to your scratch directory.
3. Change directory to your scratch directory.
4. Uncompress the idebug.tar.Z file by issuing the command: uncompress idebug.tar.Z
5. Extract the install images from idebug.tar by issuing the command: tar -xvf idebug.tar
6. As root, issue the following command: installp -ac -X -V2 -g -N -d idebug
7. You can also use SMIT with the command: smitty install_latest

Distributed Debugger for OS/2

Distributed Debugger for HP-UX

Prerequisite: 
Java version 1.3 is required for installation and Java debugging.

1. Make a scratch directory, for example, /tmp/idebug
2. Copy install.class to your scratch directory.
3. From a command prompt, open your scratch directory. If your scratch directory is /tmp/idebug, you would issue the command: cd /tmp/idebug to open it.
4. As root, type the command: java install.class

1. Create a scratch directory, for example, /tmp/idebug
2. Copy dbgsetup and idebug.pkg to your scratch directory.
3. From a command prompt, open your scratch directory. If your scratch directory is /tmp/idebug, you would issue the command cd /tmp/idebug to open it.
4. Make "dbgsetup" executable by running the following command: chmod +x dbgsetup
5. As root, enter the following command to install the debugger: ./dbgsetup idebug.pkg

Distributed Debugger for Linux 

Distributed Debugger for Linux/390 

As root, enter the following command to install the debugger: rpm -Uvh DERJPICL-9-1.s390.rpm

Distributed Debugger for OS/390

1. Install the Distributed Debugger for Windows.
2. Follow the instructions in README_install.txt which can be found in the base install directory on Windows.

A.2.1.2 Installing from the electronic image of VisualAge for Java, Version 4.0
To reduce download time, the electronic image of VisualAge for Java, Professional Edition for Windows, Version 4.0 is divided into parts.

• IDE (Integrated Development Environment) - comprises nine archive parts, of which only two are required. This allows you to download only those features that you want.
• Distributed Debugger - provides a separately downloadable part for each operating system that you will use as a target for debugging.
• IBM Developer Kit 1.2.2 - contains the IBM Developer Kit, Java Technology Edition, v 1.2.2, PTF 9, for the Windows platform. 

A.2.1.2.1 IDE
There are nine downloadable parts for the Integrated Development Environment. All nine parts are self-extracting archives. You must install the first two; the rest are optional. Refer to the list below for details about what each archive contains.

Once you have downloaded the first two parts plus the optional files that you want, run each self-extracting archive and ensure that each one is extracted into the same temporary directory. Once all the files have been extracted, go to the temporary directory and run setup.exe. Follow the on-screen instructions and start the IDE.

If you intend to work in any language other than English, you must download the correct part and run the self-extracting archive for your language before you run setup.exe. You cannot change or add a language after you have installed VisualAge for Java.

If you are working with an electronic image of VisualAge for Java, you cannot use the Add/Remove Program dialog (Start > Settings >Control Panel > Add/Remove Programs) to install additional VisualAge for Java components after your initial installation. If you try to do so, you will receive an error message and will not be able to install any additional components. You must run setup.exe from the path that you extracted the downloaded parts from in order to add any additional components to VisualAge for Java.

The following is a description of each archive part:

• VisualAge for Java - IDE 1 of 9 (English only) - REQUIRED. Includes the core Integrated Development Environment, Data Access Beans and Visual Composition Editor.
• VisualAge for Java - IDE 2 of 9 (English only) - REQUIRED. Includes the core Integrated Development Environment, Tools API, Servlet SmartGuide and XML for Java Parser.
• VisualAge for Java - IDE 3 of 9 (English only) - OPTIONAL. Enhanced Database Support (Stored Procedure Builder and SQLJ), JSP Development Environment, External Version Control.
• VisualAge for Java - IDE 4 of 9 - OPTIONAL. Deployment Environments and online documentation in PDF format.
• VisualAge for Java - IDE 5 of 9 - OPTIONAL. Portuguese (BR) and Spanish language pack. This contains the Portuguese (BR) and Spanish text for the IDE and all of its components.
• VisualAge for Java - IDE 6 of 9 - OPTIONAL. French and Italian language pack. This contains the French and Italian text for the IDE and all of its components.
• VisualAge for Java - IDE 7 of 9 - OPTIONAL. Japanese language pack. This contains the Japanese text for the IDE and all of its components.
• VisualAge for Java - IDE 8 of 9 - OPTIONAL. German and Korean language pack. This contains the German and Korean text for the IDE and all of its components.
• VisualAge for Java - IDE 9 of 9 - OPTIONAL. Simplified and Traditional Chinese language pack. This contains the Simplified and Traditional Chinese text for the IDE and all of its components.

A.2.1.2.2 Distributed Debugger
There is a separately downloadable part for each target operating system that is supported by the Distributed Debugger. If you intend to debug any classes developed outside the VisualAge for Java IDE or debug programs running on a separate machine, you should download and install the Distributed Debugger. Installation instructions for each operating system are provided below. You can also find these instructions and information about the license agreement in the readme.txt file included with each part.

VisualAge for Java - Distributed Debugger for Windows contains the user interface and the debug engine for Windows. This part is a self-extracting archive. To install it, follow these steps:

1. If you have downloaded and extracted VisualAge for Java, run setup.exe and select Install Products. Then select Install Distributed Debugger. 
2. If you want to install the Distributed Debugger without VisualAge for Java, then open the following directory from a command prompt: DebugDirectory\windows (where DebugDirectory is the directory you extracted the Distributed Debugger to) and run the following command: setup.bat

1. Create a scratch directory, for example /tmp/idebug
2. Copy idebug.tar.Z from the install media to your scratch directory.
3. Change directory to your scratch directory.
4. Uncompress the idebug.tar.Z file by issuing the command: uncompress idebug.tar.Z
5. Extract the install images from idebug.tar by issuing the command: tar -xvf idebug.tar
6. As root, issue the following command: installp -ac -X -V2 -g -N -d idebug
7. You can also use SMIT with the command: smitty install_latest

VisualAge for Java - Distributed Debugger for HP-UX contains the debug engine for HP-UX.

Prerequisite: 
Java version 1.3 is required for installation and Java debugging.

To install it, untar the file, and follow these instructions:

1. Make a scratch directory, for example, /tmp/idebug
2. Copy install.class to your scratch directory.
3. From a command prompt, open your scratch directory. If your scratch directory is /tmp/idebug, you would issue the command: cd /tmp/idebug to open it.
4. As root, type the command: java install.class

1. Make "dbgsetup" executable by running the following command: chmod +x dbgsetup
2. As root, enter the following command to install the debugger: ./dbgsetup idebug.pkg

VisualAge for Java - Distributed Debugger for Linux contains the debug engine for Linux. To install it, untar the file, and install the debugger by following these instructions:

VisualAge for Java - Distributed Debugger for Linux/390 contains the debug engine for Linux/390. To install it, untar the file, and install the debugger by following these instructions:

As root, enter the following command: rpm -Uvh DERJPICL-9-1.s390.rpm

Distributed Debugger for OS/390

1. Install the Distributed Debugger for Windows.
2. Follow the instructions in README_install.txt which can be found in the base install directory on Windows.

A.2.1.2.3 IBM Developer Kit 1.2.2
VisualAge for Java - IBM Developer Kit 1.2.2 contains the IBM Developer Kit, Java Technology Edition, v 1.2.2, PTF 9, for the Windows platform. This is a self-extracting archive. To install it, run this file, which will automatically launch the installation program after it has been extracted from the archive, and follow the instructions.

A.2.2 Installing additional components later

To install additional VisualAge for Java components any time after the initial installation, insert the CD-ROM into your CD drive, select to install VisualAge for Java, and select Modify in the Program Maintenance screen. If autorun is disabled on your system, you will have to run setup.exe from the root of the CD drive. If you have an electronic version of VisualAge for Java, you will also have to manually run setup.exe, and follow the same steps.

All the components will be listed in the Edit Features window, with an indication of their current installation state. A red 'X' indicates that a component is not currently installed. You can select to install these components. Do not select any components that are not marked with a red 'X'; they have already been installed. 

You cannot install a second instance of VisualAge for Java, Version 4.0. You cannot change the installation language without uninstalling the product first.

A.2.3 Installation considerations for Windows 2000  

This release of VisualAge for Java continues to provide toleration support (as defined by Microsoft) for Windows 2000.

The default installation directory is <Program Files>\IBM\VisualAge for Java. For Windows 2000, by default, installation to <Program Files> can only be performed by Administrators and Standard (Power) users. Regular (Restricted) users cannot write to this location.

Due to the current design of VisualAge for Java, if the product is installed to this location and is to be used by a Regular (Restricted) user, you must change the security settings for either the IBM or IBM\VisualAge for Java directory under <Program Files> to allow write access by regular users. Failure to do so may result in failures when attempting to start the IDE.

A.2.4 Installing the IBM Developer Kit, Java Technology Edition, v1.2.2, PTF 9 

If you installed VisualAge for Java from the product CD, you must run install.exe from the IBM Developer Kit directory to install the IBM Developer Kit, Java Technology Edition, v1.2.2, PTF 9. This directory is located on the product CD. If you have an electronic version of VisualAge for Java, this directory is located in your temporary directory (where you extracted your parts to), however, you do not need to run install.exe, because the installation program is automatically launched after you extract it from the downloaded IBM Developer Kit archive.

For detailed information about the IBM Developer Kit, refer to the README file in the IBM Developer Kit directory.

A.3.0 Migrating from a previous version of VisualAge for Java

Refer to Part D and Part E for information about both component-specific and general migration information before beginning the migration process.

You can automatically migrate from Version 3.5 or Version 3.5.3. Version 4.0 is installed over top of  Version 3.5 or Version 3.5.3. Refer to section 3.1 for information about migrating from VisualAge for Java Version 3.5 or Version 3.5.3.

You must manually migrate from 3.0x, Early Adopters.  Refer to section 3.2 for information about migrating from VisualAge for Java, 3.0x, Early Adopters.

If you are currently using VisualAge for Java, Version 2.0, 3.0, or 3.02 with JDK 1.1.x support, you cannot automatically migrate to VisualAge for Java, Version 4.0. These versions of VisualAge for Java can coexist with VisualAge for Java, Version 4.0. Refer to section 3.2 for information about migrating your repository contents and your resource files from Version 2.0 or 3.0x of VisualAge for Java.

You cannot migrate from VisualAge for Java, Version 3.5, Entry Enterprise Edition or VisualAge for Java, Version 3.5, or Version 3.5.3 Enterprise Edition to VisualAge for Java, Version 4.0, Professional Edition. You must migrate to Version 4.0, Enterprise Edition.

Note: When you are migrating from VisualAge for Java, Version 3.5 or Version 3.5.3 to Version 4.0, the installation process may appear to hang. This occurs because the "DoCosting" function (which compares the 3.5 or 3.5.3 versions of files with the 4.0 versions of files) can take up to three minutes to execute, causing the installation process to appear as if it has hung.

A.3.1 Migrating from Version 3.5 or from Version 3.5.3

Migration from VisualAge for Java, Version 3.5 or Version 3.5.3 is automatic. The Version 4.0 installation program automatically upgrades an installed Version 3.5 or Version 3.5.3 product to Version 4.0.

Automatic migration

1. Perform the following steps to back up your user data. Create backup copies of your repository and resource files in case problems occur during migration.
   1. Version your projects and packages. Only versioned projects and packages can be imported into the VisualAge for Java, Version 4.0 repository. Refer to your VisualAge for Java online help for versioning instructions.
   2. Save your repository to a new location outside your VisualAge for Java directory tree. The file name and path of the repository is x:\IBMVJava\ide\repository\ivj.dat, where x:\IBMVJava is the VisualAge for Java installation directory.
      Note: If you are migrating from Version 3.5 or Version 3.5.3, the repository also includes versioned copies of your project resource files, which are located in the following directory: x:\IBMVJava\ide\repository\ivj.dat.pr. You must save a copy of the ivj.dat.pr directory outside your VisualAge for Java directory tree. 
2. To install VisualAge for Java, Version 4.0, refer to the installation instructions in section 2.1.
3. Select to upgrade your current installation. You do not need to uninstall Version 3.5 or Version 3.5.3 because it is automatically upgraded to Version 4.0. Version 4.0 will automatically be installed in the directory Version 3.5 or Version 3.5.3 was installed in.
4. Upon the completion of a successful upgrade installation, all of your project resources and your repository data are automatically migrated to Version 4.0 when you start the Version 4.0 IDE for the first time. 

In the event that an installation failure occurs, you must manually migrate your user data. You also must manually migrate your user data if the IDE fails to start or if an error is encountered by the IDE when it is migrating your user data. 

Manual migration

1. Verify you have saved your repository data (that is, your repository and, if you are migrating from Version 3.5 or Version 3.5.3 your ivj.dat.pr directory) and resource files outside the VisualAge for Java directory tree.
2. Uninstall the product completely. All Version 3.5 or Version 3.5.3 subdirectories and files should be deleted.
3. Reboot and install Version 4.0.
4. Start the IDE.
5. You can now import packages and projects from your old repository into the new repository. In the Workbench, select File > Import, and then select the Repository radio button and click Next. In the Repository name field, enter the path of your backup copy of ivj.dat. Then select the projects and packages that you want to import. You will not be able to import any projects or packages that have not been versioned. Note: You should not try to import any system projects from a previous version of VisualAge for Java.
6. To automatically add the selected projects to the workspace, select the Add most recent project edition to the workspace check box. This check box is only available when the Projects radio button is selected.
7. Click Finish.
8. You do not need to copy the backup copy of your resource files into the subdirectory x:\IBMVJava\ide\project_resources\project, where x:\IBMVJava is the VisualAge for Java, Version 4.0 installation directory and project is the name of the project with which the resources are associated.
   When you import your Version 3.5 or Version 3.5.3 projects into the repository, all versioned copies of your project resources (contained in the ivj.dat.pr directory) are automatically added to the repository. 

A.3.2 Migrating from Version 2.0, 3.0x or 3.0x Early Adopters of VisualAge for Java

You can manually migrate the contents of your repository and your resource files from Version 2.0, Version 3.0x, 3.0x, Early Adopters of VisualAge for Java. Refer to the online help file "Repairing class or package references" for information about repairing breakage.

You do not have to uninstall Version 2.0 or 3.0x or 3.0x, Early Adopters; they can coexist with VisualAge for Java, Version 4.0.

Follow all the steps below before uninstalling Version 2.0, 3.0x or 3.0x, Early Adopters, if you want to import your Version 2.0, 3.0x or 3.0x Early Adopters Environment for Java 2 Platform, Standard Edition, v1.2 repository and resource files into Version 4.0. If you are not uninstalling Version 2.0, 3.0x or 3.0x, Early Adopters, you do not need to perform steps 2,3, 4, and 8, but you must perform all the other steps.

1. Version your projects and packages. Only versioned projects and packages can be imported into this version of VisualAge for Java. Refer to your VisualAge for Java online help for versioning instructions. 
2. Save your repository to a new location outside your VisualAge for Java directory tree. The file name and path of the repository is x:\IBMVJava\ide\repository\ivj.dat, where x:\IBMVJava is the VisualAge for Java installation directory.
3. Copy any resource files (such as images or sound files) used by your Java applications to a directory outside your VisualAge for Java directory tree. By default, resource files for each VisualAge for Java project are located in subdirectories called x:\IBMVJava\ide\project_resources\project, where x:\IBMVJava is the VisualAge for Java installation directory and project is the name of the project with which the resources are associated.
4. You can now uninstall Version 2.0, 3.0x or 3.0x, Early Adopters, and install Version 4.0. You do not have to uninstall Version 2.0, 3.0x or 3.0x, Early Adopters; they can coexist with VisualAge for Java, Version 4.0.
5. Install VisualAge for Java Version 4.0 (see section 2.1) and start the Version 4.0 IDE. 
6. Refer to the online help for information about importing packages and projects from your old repository into the new repository. You will not be able to import any projects or packages that have not been versioned. Note: You should not try to import any system projects from a previous version of VisualAge for Java.
7. Copy the backup copy of your resource files (or create a copy of your resource files from your current 2.0/3.0x or 3.0x, Early Adopters installation if you did not uninstall 2.0/3.0x or 3.0x, Early Adopters and copy it) into the subdirectory x:\IBMVJava\ide\project_resources\project, where x:\IBMVJava is the VisualAge for Java, Version 4.0 installation directory and project is the name of the project with which the resources are associated.
8. Once you have verified that your manual migration is successful, you can delete your backup copies created in steps 2 and 3.

A.4.0 Known problems and limitations

Please also refer to the README (which can be found in the README directory of the CD) for information about late breaking problems and limitations. 

A.4.1 Known problems and limitations with installation

The following is a list of issues you should be aware of during installation.

A.4.1.1 Disk limitations

• Do not install to an HPFS network or local drive since Windows 98, Windows 2000, and Windows NT 4.0 have trouble handling long file names on HPFS.
• Do not install to a Novell NetWare drive. Installation will fail on a Novell NetWare drive.

A.4.1.2 User authorization

• You must have write access to the root "\" directory of the drive where VisualAge for Java is installed to install the NetQuestion Search Server.
• When you install the product on Windows 2000, you may receive a warning message if you are not an Administrator. The message indicates that some programs may not work correctly if they are not installed by an Administrator. You should log on as an Administrator before beginning the VisualAge for Java installation.
• When a Restricted User attempts to install VisualAge for Java, Version 4.0 on Windows 2000, they may incorrectly receive a "Setup Initialization Error" with the message "Setup has detected that unInstallShield is in use. Please close unInstallShield and restart setup. Error 432." Verify that you have Administrator or Standard User access rights before attempting to install the product again. 
• If you do not have Administrator rights while installing on Windows NT, the online help search function will not work. 

A.4.1.3 TCP/IP considerations

• An "Autoconfigured" warning from the installation program indicates that your proxy exceptions are autoconfigured for your browser. Check with your system administrator to ensure that 127.0.0.1 is treated as a local address
• You must install and configure TCP/IP in order for IBM VisualAge for Java to install properly. For Windows 98 and Windows 2000, you must enable TCP/IP as follows:
  1. For a LAN Adapter configuration:
     • You must have DNS enabled with a valid host and domain name.
     • Your LAN DNS must resolve localhost to 127.0.0.1.
     • You cannot run disconnected with a LAN Adapter configuration.
  2. For a dial-up Adapter configuration:
     • You must have DNS disabled.
     • Your TCP/IP address must be obtained automatically.

  These configuration options will apply to all TCP/IP adapters, even though they have only been changed for this one. You will not be able to use both LAN and dial-up without reconfiguring.

  Dial-up networking TCP/IP properties for your Internet service provider (ISP) must be configured as documented by the ISP. The dial-up networking TCP/IP properties will override the properties in the dial-up Adapter TCP/IP properties configured via the Network icon in the Windows 98 or Windows 2000 Control Panel. The overriding of the properties will take place only if the dial-up Adapter TCP/IP properties are configured as above. You must not enable the DNS in the dial-up Adapter TCP/IP properties or set an IP address in the dial-up Adapter TCP/IP properties, because doing so will interfere with the dial-up networking configuration for the ISP.

  For Windows NT 4.0, you can use either of the TCP/IP configurations described above. If you are running standalone, you can also enable the Microsoft Loopback Adapter without the other two adapters.

A.4.1.4 Shell extension (Windows NT)

If you get a message that indicates that the installation program has detected a shell extension for Windows NT, the installation cannot proceed. You should then perform the following steps:

1. Make sure you have an Emergency Recovery Disk. Instructions for creating this are available in the Windows help documentation.
2. Type regedit.exe at a command prompt.
3. In the Registry Editor, expand the key
   \\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon
4. Select the shell name in the name/data pairs for the above key. Important: Make a note of the data recorded for this name, because you will need it after installing IBM VisualAge for Java.
5. Select Edit > Modify from the menu bar for the shell name/data pair.
6. Set the value for the shell name to Explorer.exe. Click OK.
7. Select Registry > Exit from the menu bar.
8. Restart and complete the IBM VisualAge for Java installation.
9. Once installation is complete, restore the previous registry entry as follows:
   a. Type regedit.exe at a command prompt.
   b. In the Registry Editor, expand the key \\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon
   c. Select the shell name in the name/data pairs for the above key.
   d. Select Edit > Modify from the menu bar for the shell name/data pair.
   e. Restore the value for the shell name to the value that was recorded in Step 4. Click OK.
   f. Select Registry > Exit from the menu bar.

A.4.1.5 Recovering from failed installation

If your installation fails, you must remove any Version 4.0 files that have been installed. If the directory you intended to install VisualAge for Java in is empty, then the installation process rolled back and removed any files that were installed. You can delete the empty directory if you want to, but it is not necessary. However, if the directory contains files, then you must start the installation process again. It will open in maintenance mode and you must select to remove your partial installation of Version 4.0 before you can try to install the product again.

You will also need to delete the registry entry:

\\HKEY_LOCAL_MACHINE\SOFTWARE\IBM\VisualAge for Java for Windows

using the following instructions:

1. Make sure you have an Emergency Recovery Disk. Instructions for creating this are available in the Windows help documentation.
2. Type regedit.exe at a command prompt.
3. In the Registry Editor, expand and select the key
   \\HKEY_LOCAL_MACHINE\SOFTWARE\IBM\VisualAge for Java for Windows\4.0
4. Select Edit > Delete from the menu bar for this key.
5. Select Yes when asked to confirm deletion of the key.
6. Select Registry > Exit from the menu bar.

If any NetQuestion files were installed before the installation failed, you must delete them as well.

1. Open a new command prompt. Check to see if any NetQuestion files were installed, by typing the following in the command prompt you just opened: set imninstsrv. This command will provide you with the location where NetQuestion is installed on your machine. For example,

   IMNINSTSRV=C:\imnnq_nt

   Your NetQuestion directory location may appear differently, depending on which drive you install VisualAge for Java on, and which operating system you are using. If the variable is set (that is, you are provided with a location where NetQuestion is installed), proceed to step 2. 

   If you receive an error message such as "Environment variable imninstsrv not defined", then either no NetQuestion files were installed or the NetQuestion installation did not complete successfully. If this occurs, select Start > Find > Files or Folders and search for the following file on your system: vahelp.cfg. If you find this file in any directories whose name begins with "imnnq" (for example, imnnq_NT or imnnq_98), delete it. You do not need to perform steps 2 and 3. 

2. Go to the NetQuestion directory (this is the information that follows IMNINSTSRV=)
3. Type vahcfg remove /p vj32

This action removes any NetQuestion files that VisualAge for Java installed. It will not affect NetQuestion files installed by other products (for example, DB2).

Back up your repository and resource files if you have not already done so. Refer to Part A, Section 3.1 for information on how to perform this task. 

Reboot and reinstall the product after you have performed all these steps. If the help fails after you have reinstalled VisualAge for Java, refer to the Troubleshooting Guide for more information about recovering from help failures. The Troubleshooting Guide (trshoot.htm) is located on the VisualAge for Java, Professional Edition product CD and on the VisualAge for Java, Enterprise Edition, Additional Features CD. After you install VisualAge for Java, it is also located in X:\IBMVJava, where X:\IBMVJava is your VisualAge for Java installation directory.

A.4.1.6 Windows Installer errors

The following is a list of Windows Installer errors you should be aware of during installation.

If you receive error message 1603 when you are installing VisualAge for Java, this indicates that Windows Installer has failed to initalize and the installation cannot proceed. 

Certain products (such as Symantec's VisualCafe) automatically install a file called sfc.dll when they are installed on any Windows platform. It is only used on Windows 2000, where Windows Installer invokes it for security processing. 

If a file with this name resides on the PATH on Windows NT 4.0, the Windows Installer will attempt to load it, even though sfc.dll is only applicable to Windows 2000. Windows Installer will then fail. 

To work around this problem, follow these steps:

1. Select Start > Find > Files or Folders and search for the sfc.dll file on your system.
2. Temporarily rename the sfc.dll file (the version that resides on the Windows NT 4.0 PATH) to sfc.old.
3. Install VisualAge for Java.
4. After you have successfully installed VisualAge for Java, rename sfc.old to sfc.dll.

Fatal LoadLibrary() error

The Fatal LoadLibrary() errror occurs because one or more VisualAge for Java installation kernels (IKernels) were not properly registered by Windows Installer. To work around this problem, you must delete the InstallShield directory the IKernal files reside in, and then reinstall VisualAge for Java by following these these steps:

1. If necessary, exit the installation.
2. Delete the following directory: x:\Program Files\Common Files\InstallShield where x is the drive you attempted to install VisualAge for Java on.
3. Reinstall the product. 

Error 1631 or Internal Error 2755 (Windows NT 4.0 only)

If you install VisualAge for Java on Windows NT 4.0, you may receive one of the following error messages:

• Error 1631: The Windows Installer service failed to start. Contact your support personnel.
• Internal Error 2755: Please contact product support for assistance.

If you receive either of these error messages, you may have registry keys with null values. When you start the VisualAge for Java installation, the userenv.dll file will attempt to parse various registry keys, and if any of the keys have null values, the installation will fail with one of the above error message.

To work around this behavior, you should either remove null environment variables or modify them (change the value from null to a valid value) before you install VisualAge for Java. After you have installed VisualAge for Java, you can return them to their original value.

Caution: Remove or modify null variables with caution. You should consider any potential impact that may occur before removing or modifying them.

Internal Errors 2381, 1303, 1310, 1313 (Windows NT only)

If you are attempting to install VisualAge for Java and any or all of the following conditions are true:

• You are installing VisualAge for Java on Windows NT 4.0.
• The drive that contains the winnt folder or the drive that you are installing VisualAge for Java on is formatted with the NTFS file system
• You have incorrect permissions set on these drives
• You have read-only permissions on the directory you are installing VisualAge for Java in.

you may receive one or more of the following error messages:

• Internal Error 2381: Please contact product support for assistance.
• Internal Error 1303: The Installer has insufficient privileges to access this directory: DirectoryName
• Internal Error 1310: Error attempting to create the destination file: FileName System error code: ErrorCode (this code varies depending on your problem)
• Internal Error 1315: The specified folder 'FolderName ' is not writable.

This problem has been reported to occur when there were only Read permissions on the following folders:

\Program Files\IBM\VisualAge for Java
\WinNT\Installer

To resolve this problem, ensure that you have the necessary permissions on your drives or directories. To do this, follow these steps:

1. In Windows Explorer, select the appropriate drive or directory.
2. Right-click the folder and select Properties from its pop-up menu.
3. Select the Security tab. Click Permissions.
4. Select Everyone. From the Type of Access drop-down menu select Full Access.
5. Select the Replace Permissions on Subdirectories check box.
6. Click OK.
7. Click Yes when prompted to confirm if you want to you want to replace permissions on all subdirectories.
8. Click OK.
9. Install VisualAge for Java.

Internal Error 2735 Engine Startup

If you receive error 2735, perform the following steps to work around it:

1. Search for the following files in your Windows 32 system directory:
   • shd401lc.dll
   • shdoclc.dll
   • shdoc401.dll
   • shdocvw.dll
2. Rename shd401lc.dll to shd401lc.old.
3. Rename shdoclc.dll to shdoclc.old.
4. Select Start > Run to open the Run dialog. Run the following commands to unregister these .dll files. 
   • regsvr32 /u shd401lc.dll
   • regsvr32 /u shdoclc.dll
5. Register these dlls by running the following commands from the Run dialog:
   • regsvr32 shdoc401.dll
   • regsvr32 shdocvw.dll
6. Install VisualAge for Java.

If you receive the following error message, the value of your Common Administrative Tools registry file may be incorrect:

Error 1606. Could not access network location \Profiles\AllUsers\StartMenu\Programs\Administrative Tools\.
Internal Error 2707. INSTALLDIR.

You must edit the value of the Common Administrative Tools registry file before you can install VisualAge for Java. To do so, follow these steps:

1. Invoke regedit.exe from a command prompt.
2. Expand and select the key
   HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folder
3. Select Common Administrative Tools.
4. Select Edit > Modify.
5. In the Value Data field, enter the following: %SystemRoot%\Profiles\AllUsers\StartMenu\Programs\Administrative Tools
6. Click OK.
7. Select Registry > Exit from the menu bar.
8. Install VisualAge for Java.

A.4.2 Known problems and limitations with uninstallation

The following is a list of issues that you should be aware of when you are uninstalling VisualAge for Java.

A.4.2.1 Disk space

You must have at least 2MB free on your Windows system drive, and your environment variable TEMP or TMP must point to a valid temporary directory with at least 5MB free.

A.4.2.2 Uninstalling the Distributed Debugger

If you installed the Distributed Debugger as part of your VisualAge for Java installation, you should uninstall VisualAge for Java before you uninstall the Distributed Debugger. After you have uninstalled VisualAge for Java, you can uninstall the Distributed Debugger by going to the Debugger installation directory and running the uninstallation program.

If you have uninstalled VisualAge for Java, and you cannot uninstall the Distributed Debugger, you must delete the registry key:

HKEY_LOCAL_MACHINE/SOFTWARE/IBM/IBM Distributed Debugger/CurrentVersion/install/ParentProducts/VisualAge for Java

and then try to uninstall the Debugger again. DO NOT follow these steps if you are using the Distributed Debugger with any other products, because you will no longer be able to use the debugger after you delete the registry key.

Follow these steps:

1. Type regedit.exe at a command prompt.
2. In the Registry Editor, expand and select the key:
   HKEY_LOCAL_MACHINE/SOFTWARE/IBM/IBM Distributed Debugger/CurrentVersion/install/ParentProducts/VisualAge for Java
3. Select Edit > Delete from the menu bar for this key.
4. Select Yes when asked to confirm deletion of the key.
5. Select Registry > Exit from the menu bar.

As well, set the value of the following registry key to 1:

HKEY_LOCAL_MACHINE/SOFTWARE/IBM/IBM Distributed Debugger/CurrentVersion/install/refcount

A.4.2.3 Environment variables (Windows 98)

When you uninstall VisualAge for Java on Windows 98, some environment entries may be left in your autoexec.bat file. Normally these leftover entries do not cause any problems, but if you uninstall and reinstall the product several times, two problems may occur. You may have conflicting path statements that can prevent the online help from working or you may run out of path space, which could prevent you from reinstalling the product successfully.

To solve these problems:

1. Make a backup copy of your autoexec.bat file.
2. Determine if you have another program that requires the HTML search engine (such as DB2) on your system by following these steps:
   a) Uninstall VisualAge for Java and reboot your system.
   b) Type regedit.exe from a command prompt and, in the Registry Editor, expand the HKEY_LOCAL_MACHINE\SOFTWARE\ tree. If there is an IBM directory in this tree, expand it to see if there is an NetQuestion directory. If you see this directory, you are probably using the search engine with another IBM product.
3. If you are not using the HTML search engine for another product, then removeany IMN or IMQ entries in your autoexec.bat file before reinstalling VisualAge for Java.
4. If you are using the HTML search engine for another product, delete any duplicates of these entries from your autoexec.bat file:
   IMNINST
   IMNINSTSRV
   IMNNQ
   IMNNQ_95
   IMQCONFIGCL
   IMQCONFIGSRV
   Also delete duplicate entries of the line IF EXIST X:\IMNNQ_95\IMNENV.BAT CALL IMNEV.BAT
5. Make sure that you do not remove the original entries when you remove the duplicates. If you are not sure which entries are the original ones, you must determine where the system considers NetQuestion to be installed. Follow these steps:
   1. Type regedit.exe at a command prompt.
   2. In the Registry Editor, expand the key
      \\HKEY_LOCAL_MACHINE\SOFTWARE\IBM\NetQuestion\Installation Directory
   3. The directory value inside this key shows you the path where NetQuestion is installed. Certain environment variables must contain this directory as part of their value for NetQuestion to function correctly.
      
      If you find any of the above environment variables that include a directory different from the one found in the registry as part of their value, delete them.

A.4.2.4 Uninstalling NetQuestion

When you are uninstalling VisualAge for Java, NetQuestion may not be uninstalled. Problems may occur if NetQuestion is not uninstalled and you later attempt to reinstall the product. 

To remove NetQuestion files installed by VisualAge for Java, follow these steps. It will not affect NetQuestion files installed by other products (for example, DB2).

1. To find the NetQuestion directory, type the following at a command prompt: set imninstsrv. This command will provide you with the location where NetQuestion is installed on your machine. For example,

   IMNINSTSRV=C:\imnnq_nt

   Your NetQuestion directory location may appear differently, depending on which drive you installed VisualAge for Java on, and which operating system you are using. If you receive an error message such as "Environment variable imninstsrv not defined", then all the NetQuestion files have been uninstalled.

2. Go to the NetQuestion directory (this is the information that follows IMNINSTSRV=)
3. Type vahcfg remove /p vj32

This removes any NetQuestion files that VisualAge for Java installed. 

If you later reinstall VisualAge for Java and the help fails, refer to the Troubleshooting Guide for more information about recovering from help failures. The Troubleshooting Guide (trshoot.htm) is located on the VisualAge for Java, Professional Edition product CD and on the VisualAge for Java, Enterprise Edition, Additional Features CD. After you install VisualAge for Java, it is also located in X:\IBMVJava, where X:\IBMVJava is your VisualAge for Java installation directory.

Part B: VisualAge for Java, Enterprise Edition

B.1.0 Prerequisites

B.1.1 General prerequisites

This edition of VisualAge for Java, Version 4.0, has the following hardware and software prerequisites:

• Windows 98, Windows 2000, or Windows NT(R) 4.0 with Service Pack 4 or higher. 
• Mouse or a pointing device *
• TCP/IP installed and configured
• Pentium II (R) processor or higher recommended. If you plan to work in the WebSphere Test Environment we recommend a minimum processor speed of 400 MHz.
• SVGA (800x600) display or higher (1024x768 recommended)
• 96 MB RAM minimum (160 MB recommended)
• 128 MB RAM minimum is required if you wish to work in the VisualAge for Java WebSphere Test Environment. We strongly recommend 256 MB to avoid disk thrashing.
• To use the Distributed Debugger, you will need 128 MB RAM minimum (196 MB recommended)
• Disk space requirements: (based on NTFS) 400 MB minimum (750 MB or more recommended.) Disk space on FAT depends on hard disk size and partitioning. If you are installing to a very large FAT drive, then the space required for VisualAge for Java is almost doubled (due to 32KB cluster overhead). If you are installing the e-connectors (automatically installed with the Transactions Access Builder) you may need an extra 150-200 MB disk space free.
• Frames-capable Web browser such as Netscape Navigator 4.7 or higher, or Microsoft (R) Internet Explorer 5.0 or higher. 

If you want to run the Websphere Application Server with DB2 and VisualAge for Java concurrently, then a minimum of 512 MB is recommended.

You must use EMSRV, Version 7.1, if you are working in a team environment. For information on moving from Version 6.x or 7.0 to Version 7.1, refer to Part C. 

* Note: VisualAge for Java does not support the Logitech scroll mouse. Any Logitech mice with drivers that remap scrolling action to the mouse will cause a system error to occur when it is used to scroll.

B.1.2 Component-specific prerequisites

Certain components have specific prerequisites:

• Domino(TM) AgentRunner
  • For development of the applications, Notes 5.0.5 (or higher) Client and the Domino 5.0.5 (or higher) Designer are required. For the execution of applications, Notes 5.0 (or higher) Client or Domino 5.0 (or higher) Server is required.
• Domino Access Builder
  • Requires Notes 5.0.5 (or higher) Client or Domino 5.0.5 (or higher) Server
• Enterprise Toolkit for AS/400 (R) (ET/400)
  • OS/400 Release V, V4R3M0 or higher is required
• Enterprise Toolkit for OS/390(R) (ET/390)
  • On OS/390:
    • NFS daemon running on OS/390
    • REXEC server running on OS/390
    • OMVS FTP server running on OS/390
    • VisualAge for Java, Enterprise Edition for OS/390, Run Time Feature 
    • Write access to the /tmp directory on OS/390 
    • For VisualAge for Java, Enterprise Edition for OS/390, Version 2, the TCP parameter SBDATACONN needs to be configured on the host to define conversions between EBCDIC and ASCII code pages when performing ET/390 Run Executable, Debug Executable, Run Main, and Debug Main actions from the VisualAge for Java's Integrated Development Environment. See the OS/390 TCP/IP OpenEdition: Configuration Guide for more information about defining this parameter.
    • A properly configured ET/390 Java Install Data file (javaInstall.data) residing in the /usr/lpp/hpj/ directory. If you have not purchased the Compiler Feature of VisualAge for Java, Enterprise Edition for OS/390, you can create this file manually, referring to the ET/390 online help for information about its keywords and parameters. 

  On workstations, the NFS Maestro Client for Windows NT or Windows 2000. For the NFS Client for Windows NT, you need to perform a binary mount for the HFS directory to which class files will be exported.

• Enterprise Access Builder for SAP R/3
  • Requires access to an SAP R/3 server.
• Enterprise Access Builder for IMS(TM)
  • In order to run a Java application or servlet that uses IMS Connector for Java, the following separately packaged and installed products must be installed and running on the target host machine:

  • IMS Connect V1.1 and IMS Version 7 (recommended) or
  • IMS Connect V1.1 and IMS Version 5.1 or 6.1

  • The prerequisites for using Local Option with IMS Connector for Java,Version 4.0 are:
    • IMS Connect V1.1 plus the Local Option enabling APAR PQ45057
    • IMS V7.1 Note: Local Option is only supported for IMS V7.1 and above
  • If you want to deploy an EAB application from a previous version of VisualAge for Java that used IMS Connector for Java you must use the following Version 4.0 run-time files (located in IBM Connectors\classes and eab\runtime30):
    • imsconn.jar
    • ccf.jar
    • recjava.jar
    • eablib.jar

B.2.0 Installation

This section contains information about installing VisualAge for Java, Version 4.0. Important: If you are migrating from a previous version of VisualAge for Java, refer to section 3.0 below before installing VisualAge for Java, Version 4.0. For special information about installing on Windows 2000, refer to section 2.5.

Please also refer to the README (which can be found in the root directory of the product CD) for information about late breaking problems and limitations.

Important : Due to a limitation in the support of the CD-ROM file system (CDFS) on Windows 98, the installation of certain e-business connectors files from the CD-ROM may fail and cause one or more of the following error dialogs to be displayed, depending on the connectors you selected:

• ENCINA VAJ.RUL DELCon* copies failed
• ENCINA VAJ.RUL Deligh* copies failed
• ENCINA VAJ.RUL Drpc*
• ENCINA VAJ.RUL Transaction*
• HOD VAJ.RULcopy of file *.* failed

Any files that did not get installed are stored in a zip file (econnfix.zip) located in the root of the product CD. If you are trying to install VisualAge for Java on Windows 98 and receive any of the above messages, you must unzip econnfix.zip to the directory where the product was installed (for example, by running the command unzip econnfix.zip -d c:\Program Files\IBM\VisualAge for Java\ where c:\Program Files\IBM\VisualAge for Java\ is your product installation directory).Once these files are in place, the connectors will function correctly.

B.2.1 Installing VisualAge for Java, Version 4.0, Enterprise Edition

Before you install the product, check the following things:

• The CLASSPATH must be less than 418 characters. VisualAge for Java inserts approximately 92 characters into the CLASSPATH during the installation. These numbers are based on the assumption that the target directory is 36 characters long, for example, Program Files\IBM\VisualAge for Java 
• If you are using the default target directory, then the PATH must be less than 377 characters on Windows 98, and less than 820 characters on Windows NT and Windows 2000.
• You must have at least 20 MB free on your Windows system drive, and your environment variable TEMP or TMP must point to a valid temporary directory with at least 6 MB free. 

If you attempt to install VisualAge for Java on Windows, Millennium Edition, you will be prompted to increase your environment space. The steps outlined below must be performed before you install, otherwise the VisualAge for Java help system will not function correctly. To increase your environment space, perform the following steps:

1. Exit the Installation screen.
2. Open Windows Explorer. Browse to your Windows directory (for example, C:\Windows).
3. Right-click Command.com, and then click Properties from its pop-up menu. Click the Memory tab.
4. In the Initial Environment box, set the initial environment size to 4,096 bytes. Click OK.
5. Close Windows Explorer.
6. Reboot your computer.
7. Re-start the VisualAge for Java installation.

You must perform the following instructions, regardless of whether you are installing the VisualAge for Java team clients or installing a client with a local repository. Refer to section 2.3 for details about installing a team client or section 2.4 for details about installing a local repository.

B.2.1.1 Installing VisualAge for Java, Version 4.0 from the product CD

1. If you are migrating from a previous version of VisualAge for Java, read "Migrating from a previous version of VisualAge for Java", section 3.0 of this document, BEFORE proceeding with the installation procedure.
2. Insert the CD-ROM into your CD drive. 
3. If autorun is disabled on your system, run setup.exe from the root of the CD drive.
4. Select Install Products. Select Install VisualAge for Java to begin the installation of VisualAge for Java. If you intend to debug any classes developed outside the VisualAge for Java IDE or debug programs running on a separate machine, refer to section B.2.1.1.1 for information on installing the Distributed Debugger. 
5. Follow the on-screen instructions.
6. Start the VisualAge for Java IDE.

Installing silently
To install VisualAge for Java, Version 4.0 silently, invoke the following command from the ivj40\setup directory:

setup /s /v/qn

VisualAge for Java will automatically be installed in the c:\Program Files\IBM\VisualAge for Java default directory.

To silently install to a different directory (for example, d:\IBMVJava40), invoke the following command from the ivj40\setup directory:

setup /s /v"INSTALLDIR=\"d:\IBMVJava40\" /qn"

where d:\IBMVJava40 is the directory you want to install to.

Note: You cannot connect to a shared repository when you install VisualAge for Java silently; you can only connect to a local repository when you install silently. If you want to install silently and still work in a team environment, you should install locally, and then connect to your shared repository after you have installed the product and started the IDE. Refer to the team.pdf file in the pdf directory for instructions on how to install locally, but work in a team environment. The pdf directory is located on the VisualAge for Java, Enterprise Edition, Additional Features CD. If you have an electronic version of VisualAge for Java it can be found in your temporary directory (where you extracted your parts to). If you did not download the part containing the PDFs, you will not have this directory.

B.2.1.1.1 Installing the Distributed Debugger from the product CD
If you intend to debug any classes developed outside the VisualAge for Java IDE or debug programs running on a separate machine, you should install the Distributed Debugger. The Distributed Debugger is supported on the following operating systems: Windows, AIX, OS/2, HP-UX, Solaris, Linux, and Linux/390. Installation instructions for each operating system are provided below. All Distributed Debugger files are on the Additional Features CD.

 Distributed Debugger for Windows

1. You can install the Distributed Debugger from the Additional Features CD. From the Additional Features Install screen select Install Products, then Install Distributed Debugger.

1. Create a scratch directory, for example /tmp/idebug
2. Copy idebug.tar.Z from the install media to your scratch directory.
3. Change directory to your scratch directory.
4. Uncompress the idebug.tar.Z file by issuing the command: uncompress idebug.tar.Z
5. Extract the install images from idebug.tar by issuing the command: tar -xvf idebug.tar
6. As root, issue the following command: installp -ac -X -V2 -g -N -d idebug
7. You can also use SMIT with the command: smitty install_latest

Distributed Debugger for OS/2

Distributed Debugger for HP-UX

Prerequisite: 
Java version 1.3 is required for installation and Java debugging.

1. Make a scratch directory, for example, /tmp/idebug
2. Copy install.class to your scratch directory.
3. From a command prompt, open your scratch directory. If your scratch directory is /tmp/idebug, you would issue the command: cd /tmp/idebug to open it.
4. As root, type the command: java install.class

1. Create a scratch directory, for example, /tmp/idebug
2. Copy dbgsetup and idebug.pkg to your scratch directory.
3. From a command prompt, open your scratch directory. If your scratch directory is /tmp/idebug, you would issue the command cd /tmp/idebug to open it.
4. Make "dbgsetup" executable by running the following command: chmod +x dbgsetup
5. As root, enter the following command to install the debugger: ./dbgsetup idebug.pkg

Distributed Debugger for Linux 

Distributed Debugger for Linux/390 

As root, enter the following command to install the debugger: rpm -Uvh DERJPICL-9-1.s390.rpm

Distributed Debugger for OS/390

1. Install the Distributed Debugger for Windows.
2. Follow the instructions in README_install.txt which can be found in the Debugger\OS390 subdirectory on the product CD.

B.2.1.1.2 Installing the beta version of J2EE components 
This release of VisualAge for Java includes a beta version of several components of the Java 2 Platform, Enterprise Edition (J2EE (TM)). Sun Microsystems Inc. has not officially released these J2EE components. Specifically, this release of VisualAge for Java includes a beta version of the following J2EE components:

• J2EE Connector for CICS
• J2EE Connector for SAP R/3 
• J2EE Connector for PeopleSoft 
• J2EE Connector for J.D. Edwards OneWorld.
• J2EE Connector for Oracle Applications/Financials
• Tools to import data structures found on JD Edwards, PeopleSoft and Oracle Applications servers 
• Tools to generate J2EE-compliant records
• Tools to create and edit J2EE-compliant Commands
• Tools to create and edit J2EE-compliant EAB session beans
• Tools to migrate existing EAB applications to the J2EE-based architecture. These tools migrate records, Commands and Navigators. 

The beta components are located in the extras\BetaJ2EEConnectors subdirectory on the Additional Features CD. If you want to use these beta components, refer to the README file in the BetaJ2EEConnectors subdirectory which contains installation instructions for the components. 

B.2.1.2. Installing from the electronic image of VisualAge for Java, Version 4.0
To reduce download time, the electronic image of VisualAge for Java, Enterprise Edition for Windows, Version 4.0 is divided into parts.

• IDE (Integrated Development Environment) - comprises fourteen archive parts, of which only two are required. This allows you to download only those features that you want.
• Distributed Debugger - provides a separately downloadable part for each operating system that you will use as a target for debugging.
• EMSRV - One archive part contains the team server code for all supported server platforms, which are in listed in Part C, Section 1.1 of this document.
• IBM Developer Kit 1.2.2 - contains the IBM Developer Kit, Java Technology Edition, v 1.2.2, PTF 9, for the Windows platform. 

B.2.1.2.1 IDE
There are fourteen downloadable parts for the Integrated Development Environment. All fourteen parts are self-extracting archives. You must install the first two; the rest are optional. Refer to the list below for details about what each archive contains.

Once you have downloaded the first two parts plus the optional files that you want, run each self-extracting archive and ensure that each one is extracted into the same temporary directory. Once all the parts have been extracted, go to the temporary directory and run setup.exe. Follow the on-screen instructions and start the IDE.

If you intend to work in any language other than English, you must download the correct part and run the self-extracting archive for your language before you run setup.exe. You cannot change or add a language after you have installed VisualAge for Java

If you are working with an electronic image of VisualAge for Java, you cannot use the Add/Remove Program dialog (Start > Settings >Control Panel > Add/Remove Programs) to install additional VisualAge for Java components after your initial installation. If you try to do so, you will receive an error message and will not be able to install any additional components. You must run setup.exe from the path that you extracted the downloaded parts from in order to add any additional components to VisualAge for Java.

The following is a description of each part:

• VisualAge for Java - IDE 1 of 14 (English only) - REQUIRED. Includes the core Integrated Development Environment, Data Access Beans and Visual Composition Editor.
• VisualAge for Java - IDE 2 of 14 (English only) - REQUIRED. Includes the core Integrated Development Environment, Tools API, Servlet SmartGuide and XML for Java Parser.
• VisualAge for Java - IDE 3 of 14 (English only) - OPTIONAL. Enhanced database support (Stored Procedure Builder and SQLJ), EJB/JSP Development Environment, Persistence Builder, External Version Control, ET/400, ET/390, Tivoli connection. NOTE: This is required if you are going to install the Transaction Access Builder.
• VisualAge for Java - IDE 4 of 14 (English only) - OPTIONAL. Application Access Builders (Domino, SAP R/3, C++), Transactions Access Builder (requires parts 3,5 and 6), XMI Toolkit, XML Generator, Domino Agent Runner, IDL Development Environment.
• VisualAge for Java - IDE 5 of 14 - OPTIONAL. e-connectors. If you install this part, you must install part 6 as well. NOTE: This is required if you are going to install the Transaction Access Builder
• VisualAge for Java - IDE 6 of 14 - OPTIONAL. e-connectors. If you install this part, you must install part 5 as well. NOTE: This is required if you are going to install the Transaction Access Builder
• VisualAge for Java - IDE 7 of 14 - OPTIONAL. Deployment Environments, Technology Previews, Merant(TM) DataDirect SequeLink Java Edition Version 5.1 for Oracle and Microsoft SQLServer
• VisualAge for Java - IDE 8 of 14 - OPTIONAL. Portuguese (BR) and Spanish language pack. This contains the Portuguese (BR) and Spanish text for the IDE and all of its components.
• VisualAge for Java - IDE 9 of 14 - OPTIONAL. French and Italian language pack. This contains the French and Italian text for the IDE and all of its components.
• VisualAge for Java - IDE 10 of 14 - OPTIONAL. Japanese language pack. This contains the Japanese text for the IDE and all of its components.
• VisualAge for Java - IDE 11 of 14 - OPTIONAL. German and Korean language pack. This contains the German and Korean text for the IDE and all of its components.
• VisualAge for Java - IDE 12 of 14 - OPTIONAL. Simplified and Traditional Chinese language pack. This contains the Simplified and Traditional Chinese text for the IDE and all of its components.
• VisualAge for Java - IDE 13 of 14 - OPTIONAL. Java 2 Platform, Enterprise Edition (J2EE) components for the Transaction Access Builder. This contains IBM Connectors and Tools for J2EE(TM) - Beta (requires part 4).
• VisualAge for Java - IDE 14 of 14 - OPTIONAL. Online documentation in PDF format.

B.2.1.2.2. Distributed Debugger
There is a separately downloadable part for each target operating system that is supported by the Distributed Debugger. If you intend to debug any classes developed outside the VisualAge for Java IDE or debug programs running on a separate machine, you should download and install the Distributed Debugger. Installation instructions for each operating system are provided below. You can also find these instructions and information about the license agreement in the readme-1st.txt file included with each part.

VisualAge for Java - Distributed Debugger for Windows contains the user interface and the debug engine for Windows. This part is a self-extracting archive. To install it, follow these steps:

1. If you have downloaded and extracted VisualAge for Java, run setup.exe and select Install Products. Then select Install Distributed Debugger. 
2. If you want to install the Distributed Debugger without VisualAge for Java, then open the following directory from a command prompt: DebugDirectory\windows (where DebugDirectory is the directory you extracted the Distributed Debugger to) and run the following command: setup.bat

1. Create a scratch directory, for example /tmp/idebug
2. Copy idebug.tar.Z from the install media to your scratch directory.
3. Change directory to your scratch directory.
4. Uncompress the idebug.tar.Z file by issuing the command: uncompress idebug.tar.Z
5. Extract the install images from idebug.tar by issuing the command: tar -xvf idebug.tar
6. As root, issue the following command: installp -ac -X -V2 -g -N -d idebug
7. You can also use SMIT with the command: smitty install_latest

VisualAge for Java - Distributed Debugger for OS/2 contains the OS/2 debug engine. To install it, follow the instructions in README_install.txt (included with the Distributed Debugger for OS/2 part).

VisualAge for Java - Distributed Debugger for HP-UX contains the debug engine for HP-UX.

Prerequisite: 
Java version 1.3 is required for installation and Java debugging.

To install it, untar the file, and follow these instructions:

1. Make a scratch directory, for example, /tmp/idebug
2. Copy install.class to your scratch directory.
3. From a command prompt, open your scratch directory. If your scratch directory is /tmp/idebug, you would issue the command: cd /tmp/idebug to open it.
4. As root, type the command: java install.class

1. Make "dbgsetup" executable by running the following command: chmod +x dbgsetup
2. As root, enter the following command to install the debugger: ./dbgsetup idebug.pkg

VisualAge for Java - Distributed Debugger for Linux contains the debug engine for Linux. To install it, untar the file, and install the debugger by following these instructions:

VisualAge for Java - Distributed Debugger for Linux/390 contains the debug engine for Linux/390. To install it, untar the file, and install the debugger by following these instructions:

As root, enter the following command: rpm -Uvh DERJPICL-9-1.s390.rpm

Distributed Debugger for OS/390

1. Install the Distributed Debugger for Windows.
2. Follow the instructions in README_install.txt which can be found in the base install directory on Windows.

B.2.1.2.3 EMSRV (team server)
VisualAge for Java - EMSRV 7.1 contains the repository server program for the team development environment. A single archive part contains the server code for Windows, AIX, OS/2, NetWare, HP-UX, Linux, and Solaris, in ZIP file format. To install, unzip this part and follow the instructions in instmigr.htm

B.2.1.2.4 IBM Developer Kit 1.2.2 
VisualAge for Java - IBM Developer Kit 1.2.2 contains the IBM Developer Kit, Java Technology Edition, v 1.2.2, PTF 9, for the Windows platform. This is a self-extracting archive. To install, run this file, which will automatically launch the installation program after it has been extracted from the archive, and follow the instructions. 

B.2.2 Installing additional components later

To install additional VisualAge for Java components any time after the initial installation, insert the CD-ROM into your CD drive, select to install VisualAge for Java, and select Modify in the Program Maintenance screen. If autorun is disabled on your system, you will have to run setup.exe from the root of the CD drive. If you have an electronic version of VisualAge for Java, you will also have to manually run setup.exe and then follow the same steps.

All the components will be listed in the Edit Features window, with an indication of their current installation states. A red 'X' indicates that a component is not currently installed. You can select to install these components. Do not select any components that are not marked with a red 'X'; they have already been installed. 

You cannot install a second instance of VisualAge for Java, Version 4.0. You cannot change the installation language without uninstalling the product first.

B.2.3 Installing the VisualAge for Java team clients

Before each member of the development team can follow these steps, the EMSRV administrator must have set up and started the server, tested the client connection, and added the team developers to the repository user list. Refer to the Part C in this guide for information on performing these tasks. Part C also provides information on migrating a team repository.

In the following instructions, it is assumed that the shared repository that is installed on the server is called ivj.dat. EMSRV, Version 7.1 must have been installed on your server. You may receive an error message if you try to connect to a previous version of EMSRV.

1. Before you start to install VisualAge for Java, Version 4.0, ask your administrator for the following information:
   • The host name or IP address of the server. 
   • The file name of the shared repository. By default, the file name is ivj.dat; you will not need to specify path information if the administrator specifies the repository's location as the EMSRV working directory when starting the server.
   • Your repository user name. You will need to select this name as the workspace owner when you start the VisualAge for Java client.
   • If password protection is enabled, the password for that workspace owner. (By default, password protection is not enabled.)
2. Start the VisualAge for Java, Version 4.0 installation. For details on installation, refer to section 2.0. If you are migrating from a previous version of VisualAge for Java, refer to section 3.0 for details about the migration process.
3. When prompted by the installation program, specify that you wish to use a repository that resides on a server. If, instead of always working as a client connected to a shared repository, you would like to have a local repository on your workstation for working in standalone mode, see the alternative instructions below in section 2.4. Provide the server's TCP/IP host name (or IP address) and the name of the repository, as given to you by your administrator. If the administrator did not specify a working directory when starting the EMSRV program, then you will need to fully qualify the repository's name with the server's path information for that file. The installation program will automatically insert the server address and repository information into the client's ide.ini file.
4. You will be asked to select a workspace owner name from the list of repository users that the administrator has set up. Select your user name. If password protection has been enabled, you will need to provide the user password.
   
   A progress bar indicates that the workspace is being connected to the repository. If, instead of a user list, you see an error message indicating that an unrecoverable error has occurred, one of the following situations may have occurred:
   1. The server is not active.
   2. You specified an incorrect server name when you installed VisualAge for Java on your workstation.
   3. You specified an incorrect repository name during installation.
   
   You can correct the server or repository information by editing the ide.ini file on the team client.

B.2.4 Installing a client that has a standalone repository

You may wish to have your own VisualAge for Java source code repository on your workstation, to use when you are not connected to the shared repository. In this case, when you are installing VisualAge for Java, Version 4.0 on your workstation, specify that your repository will be on your local machine, rather than on the server. The installation program will create a repository for you.

When you want to use the shared repository on the team server, refer to the online help or the team.pdf file. The team.pdf file is in the pdf directory. The pdf directory is located on the VisualAge for Java, Enterprise Edition, Additional Features CD. If you have an electronic version of VisualAge for Java it can be found in your temporary directory (where you extracted your parts to). If you did not download the part containing the PDFs, you will not have this directory.

B.2.5 Installation and usage considerations for Windows 2000  

This release of VisualAge for Java continues to provide toleration support (as defined by Microsoft) for Windows 2000. 

The default installation directory is <Program Files>\IBM\VisualAge for Java. For Windows 2000, by default, installation to <ProgramFiles> can only be performed by Administrators and Standard (Power) users. Regular (Restricted) users cannot write to this location.

Due to the current design of VisualAge for Java, if the product is installed to this location, and is to be used by a Regular (Restricted) user, you must change the security settings for the IBM or IBM\VisualAge for Java directory under <ProgramFiles> to allow write access by regular users. Failure to do so may result in failures when attempting to start the IDE or while using some VisualAge for Java tools within the IDE.

The server list for the AS/400 Enterprise Toolkit is now stored as "<ProgramFiles>\IBM\shared files\fvdctcp.txt". Again, by default, this location is protected, and cannot be written to by Regular users. If a user without sufficient authority attempts to create or update the server list through any of the AS/400 SmartGuides' Add/Modify server list buttons, the file creation or update will fail with an io error in its Java code, which may or may not show up in the log or console.

The system Administrator must determine whether to give write access to the regular user for this location, or to keep it protected and load the file manually, preventing unauthorized users from updating the file.

B.2.6 Installing the IBM Developer Kit, Java Technology Edition, v1.2.2, PTF 9 

If you installed VisualAge for Java from the product CD, you must run install.exe from the IBM Developer Kit directory to install the IBM Developer Kit, Java Technology Edition, v1.2.2, PTF 9. This directory is located on the Additional Features CD. If you have an electronic version of VisualAge for Java, this directory is located in your temporary directory (where you extracted your parts to), however, you do not need to run install.exe, because the installation program is automatically launched after you unzip it from the downloaded IBM Developer Kit archive. 

For detailed information about the IBM Developer Kit, refer to the README file in the IBM Developer Kit directory.

B.3.0 Migrating from a previous version of VisualAge for Java  

Refer to Part D and Part E for information about both component-specific and general migration information before beginning the migration process.

The VisualAge for Java, Version 4.0 upgrade will perform repository updates during installation in order to bring the system class libraries in the repository up to the correct release level. This requires that the repository is available for read-write access during this upgrade. No user code will be modified during this operation.

If you are migrating from a previous version of VisualAge for Java, Enterprise Edition, and you work in a stand-alone environment (rather than a team environment); and you will continue working in a stand-alone environment, follow the migration instructions for Professional Edition in Part A of this document.

Note: When you are migrating from VisualAge for Java, Version 3.5 or Version 3.5.3 to Version 4.0, the installation process may appear to hang. This occurs because the "DoCosting" function (which compares the 3.5 versions of files with the 4.0 versions of files) can take up to three minutes to execute, causing the installation process to appear as if it has hung.

If you are migrating from a team environment or to a team environment, consider the following issues before you begin the migration process.

• Will you continue to use your existing repositories? If yes, there are two approaches that you can take.
  • You can migrate the contents of the Version 4.0 repository into your existing repository. This will allow users of mixed development environments to access the same repository simultaneously, although differences in JDK levels may prevent you from treating all code as common. For more information on how to perform this task, refer to Section 3.1 of Part B.
  • You can continue using your existing repository and also install the Version 4.0 repository for separate use. In this case, you may have deal with issues like dual maintenance and planning the eventual, phased migration of your users to the Version 4.0 repository.
• What version of VisualAge for Java are you migrating from? If you decide to upgrade your JDK 1.1.x-based repository and you migrate your applications to work properly with the Java 2 Platform, v1.2.2, they may no longer work on v1.1.x of the Java platform. For example, Swing classes are in a different package in the J2SDK v1.2.2 than they were in JDK v 1.1.x, and you must update the references to the Swing classes if you are migrating applications from 1.1.x to 1.2.2. If you have many JDK-dependent applications, you may want to keep them in separate repositories. 
• How many repositories are involved? In general, you need to consider all shared repositories and local Early Adopters Environment, Version 3.5 or Version 3.5.3 repositories. If you have N users of the Early Adopters Environment, Version 3.5 or Version 3.5.3 (all with local repositories) and R shared repositories, then there are N + R repositories to upgrade.

The steps that you will need to follow when migrating depend on your situation and on your answers to the above questions.

The following migration scenario is one of the most complicated. In this scenario, you have more than one shared repository and N developers with Version 3.5 or Version 3.5.3 local repositories. You want to use the new Version 4.0 repository, but also keep using all the data in your old shared repositories. 

Note: This scenario covers dealing with Version 3.5 or Version 3.5.3 (Java 2) local repositories, not JDK 1.1.x local repositories. If you want to import JDK 1.1.x local repository information into your Version 4.0 repository, follow the instructions in Section 3.2 of Part A. 

1. Upgrade EMSRV to Version 7.1. The team administrator must install EMSRV, Version 7.1. Refer to Section 2 of Part C for instructions on how to perform this task. 
2. Create backup copies of your user data.
   1. Version your projects and packages. Only versioned projects and packages can be imported into the VisualAge for Java, Version 4.0 repository. Refer to your VisualAge for Java online help for versioning instructions.
   2. Save your repository to a new location outside your VisualAge for Java directory tree. The file name and path of the repository is x:\IBMVJava\ide\repository\ivj.dat, where x:\IBMVJava is the VisualAge for Java installation directory. 
      Note: If you are migrating from Version 3.5 or Version 3.5.3, the repository also includes versioned copies of your project resource files, which are located in the following directory: x:\IBMVJava\ide\repository\ivj.dat.pr. You must save a copy of the ivj.dat.pr directory outside your VisualAge for Java directory tree.
3. The team administrator performs a complete installation of VisualAge for Java, Version 4.0, including a local repository. The administrator then exports the entire contents of the local repository into all the shared repositories. Refer to Part B, Section 3.1 for details on how to perform this task.
4. All Version 3.5 or Version 3.5.3 users install Version 4.0 locally, which will automatically upgrade the N local repositories.

The migration process is now complete, and users can switch between a local repository or a shared repository as desired. Note: If you are migrating from a team environment to a local environment, you must manually export your projects from your old shared repository into your local one. As well, if you had a local repository you will have to import any projects you want to use from your old local repository into your new Version 4.0 local repository.

B.3.1 Migrating a shared repository from a previous version of VisualAge for Java

You must upgrade to EMSRV 7.1 before you can perform the following steps. You can find instructions on how to perform this task in section C.3.1  

You can upgrade your Version 2.0 or 3.0x (JDK 1.1-based) or 3.0x, Early Adopters or 3.5 (JDK 1.2 based) shared repository to work with VisualAge for Java, Version 4.0. In the steps below, the team administrator performs a complete installation of VisualAge for Java, Version 4.0 using a local repository. The administrator then exports the entire contents of the local repository into all the shared repositories.

To upgrade an existing repository on the server to work with VisualAge for Java, Version 4.0, follow these steps:

1. Install VisualAge for Java, Version 4.0 as a full install with a local repository. Refer to Section 2.0 in Part B for instructions on how to perform this task.
2. Start the Version 4.0 IDE. You will be connected to the local repository.
3. In the Workbench, select File > Export, then select the Repository radio button and click Next. Select Shared repository with EMSRV server. Type the IP address or host name of the server in the Shared repository with EMSRV server address field.
4. Click Browse to locate your shared repository or type the shared repository's path and file name in the Repository name field.
5. Select Projects. Click Details to see a list of versioned projects that can be exported from the source repository. 
6. Select all the project editions and export them.
7. Click Finish.

All of the projects are copied into your shared repository. Your project resource files are also exported. If the repository you are exporting to is called sample.dat, then your project resources are exported to a folder called sample.dat.pr.

B.4.0 Known limitations and problems

Please also refer to the README (which can be found in the README directory of the CD) for information about late breaking known problems and limitations. 

B.4.1 Known limitations and problems with Installation  

The following is a list of issues that you should be aware of when you are installing VisualAge for Java.

B.4.1.1 Disk limitations

• Do not install to an HPFS network or local drive since Windows 98, Windows 2000, and Windows NT 4.0 have trouble handling long file names on HPFS.
• Do not install to a Novell NetWare drive. Installation will fail on a Novell NetWare drive.

B.4.1.2 User authorization

• You must have write access to the root "\" directory of the drive where VisualAge for Java is installed to install the NetQuestion Search Server. 
• When you install the product on Windows 2000, you may receive a warning message if you are not an Administrator. The message indicates that some programs may not work correctly if they are not installed by an Administrator. You should log on as an Administrator before beginning the VisualAge for Java installation.
• When a Restricted User attempts to install VisualAge for Java, Version 4.0 on Windows 2000, they may incorrectly receive a "Setup Initialization Error" with the message "Setup has detected that unInstallShield is in use. Please close unInstallShield and restart setup. Error 432." Verify that you have Administrator or Standard User access rights before attempting to install the product again.
• If you do not have Administrator rights while installing on Windows NT, the online help search function will not work.

B.4.1.3 TCP/IP considerations

• An "Autoconfigured" warning from the installation program indicates that your proxy exceptions are autoconfigured for your browser. Check with your system administrator to ensure that 127.0.0.1 is treated as a local address
• You must install and configure TCP/IP in order for IBM VisualAge for Java to install properly. For Windows 98 and Windows 2000, you must enable TCP/IP as follows:
  1. For a LAN Adapter configuration:
     • You must have DNS enabled with a valid host and domain name.
     • Your LAN DNS must resolve localhost to 127.0.0.1.
     • You cannot run disconnected with a LAN Adapter configuration.
  2. For a dial-up Adapter configuration:
     • You must have DNS disabled.
     • Your TCP/IP address must be obtained automatically.

  These configuration options will apply to all TCP/IP adapters, even though they have only been changed for this one. You will not be able to use both LAN and dial-up without reconfiguring.

  Dial-up networking TCP/IP properties for your Internet service provider (ISP) must be configured as documented by the ISP. The dial-up networking TCP/IP properties will override the properties in the dial-up Adapter TCP/IP properties configured via the Network icon in the Windows 98 or Windows 2000 Control Panel. The overriding of the properties will take place only if the dial-up Adapter TCP/IP properties are configured as above. You must not enable the DNS in the dial-up Adapter TCP/IP properties or set an IP address in the dial-up Adapter TCP/IP properties, because doing so will interfere with the dial-up networking configuration for the ISP.

  For Windows NT 4.0, you can use either of the TCP/IP configurations described above. If you are running standalone, you can also enable the Microsoft Loopback Adapter without the other two adapters.

B.4.1.4 Shell extension (Windows NT)

If you get a message that indicates that the installation program has detected a Shell Extension for Windows NT, the installation cannot proceed. You should then perform the following steps:

1. Make sure you have an Emergency Recovery Disk. Instructions for creating this are available in the Windows help documentation.
2. Type regedit.exe at a command prompt.
3. In the Registry Editor, expand the key
   \\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon
4. Select the shell name in the name/data pairs for the above key. Important: Make a note of the data recorded for this name, because you will need it after installing IBM VisualAge for Java.
5. Select Edit > Modify from the menu bar for the shell name/data pair.
6. Set the value for the shell name to Explorer.exe. Click OK.
7. Select Registry > Exit from the menu bar.
8. Restart and complete IBM VisualAge for Java installation.
9. Once installation is complete, restore the previous registry entry as follows:
   a. Type regedit.exe at a command prompt.
   b. In the Registry Editor, expand the key \\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon
   c. Select the shell name in the name/data pairs for the above key.
   d. Select Edit > Modify from the menu bar for the shell name/data pair.
   e. Restore the value for the shell name to the value that was recorded in Step 4. Click OK.
   f. Select Registry > Exit from the menu bar.

B.4.1.5 Recovering from failed installation

If your installation fails, you must remove any Version 4.0 files that have been installed. If the directory you intended to install VisualAge for Java in is empty, then the installation process rolled back and removed any files that were installed. You can delete the empty directory if you want to, but it is not necessary. However, if the directory contains files, then you must start the installation process again. It will open in maintenance mode and you must select to remove your partial installation of Version 4.0 before you can try to install the product again.

You will also need to delete the registry entry:

\\HKEY_LOCAL_MACHINE\SOFTWARE\IBM\VisualAge for Java for Windows

using the following instructions:

1. Make sure you have an Emergency Recovery Disk. Instructions for creating this are available in the Windows help documentation.
2. Type regedit.exe at a command prompt.
3. In the Registry Editor, expand and select the key
   \\HKEY_LOCAL_MACHINE\SOFTWARE\IBM\VisualAge for Java for Windows\4.0
4. Select Edit > Delete from the menu bar for this key.
5. Select Yes when asked to confirm deletion of the key.
6. Select Registry > Exit from the menu bar.

If any NetQuestion files were installed before the installation failed, you must delete them as well.

1. Open a new command prompt. Check to see if any NetQuestion files were installed, by typing the following in the command prompt you just opened: set imninstsrv. This command will provide you with the location where NetQuestion is installed on your machine. For example,

   IMNINSTSRV=C:\imnnq_nt

   Your NetQuestion directory location may appear differently, depending on which drive you install VisualAge for Java on, and which operating system you are using. If the variable is set (that is, you are provided with a location where NetQuestion is installed), proceed to step 2. 

   If you receive an error message such as "Environment variable imninstsrv not defined", then either no NetQuestion files were installed or the NetQuestion installation did not complete successfully. If this occurs, select Start > Find > Files or Folders and search for the following file on your system: vahelp.cfg. If you find this file in any directories whose name begins with "imnnq" (for example, imnnq_NT or imnnq_98), delete it. You do not need to perform steps 2 and 3. 

2. Go to the NetQuestion directory (this is the information that follows IMNINSTSRV=)
3. Type vahcfg remove /p vj32

This removes any NetQuestion files that VisualAge for Java installed. It will not affect NetQuestion files installed by other products (for example, DB2).

Back up your repository and resource files if you have not already done so. Refer to Part B, Section 3.0 for information on how to perform this task. 

After performing all of these steps, reboot and re-install the product. If the help fails after you have re-installed VisualAge for Java, refer to the Troubleshooting guide for more information about recovering from help failures. The Troubleshooting guide (trshoot.htm) is located on the VisualAge for Java, Professional Edition product CD and on the VisualAge for Java, Enterprise Edition, Additional Features CD. After you install VisualAge for Java, it is also located in X:\IBMVJava, where X:\IBMVJava is your VisualAge for Java installation directory.

B.4.1.6 CICS Transaction Gateway

If you have a version of the CICS Transaction Gateway installed on your machine when you install VisualAge for Java, then VisualAge will use this version instead of installing its own.

B.4.1.7 Windows Installer errors

The following is a list of Windows Installer errors you should be aware of during installation.

If you receive error message 1603 when you are installing VisualAge for Java, this indicates that Windows Installer has failed to initalize and the installation cannot proceed. 

Certain products (such as Symantec's VisualCafe) automatically install a file called sfc.dll when they are installed on any Windows platform. It is only used on Windows 2000, however, where the Windows Installer invokes it for security processing. 

If a file with this name resides on the PATH on Windows NT 4.0, the Windows Installer will attempt to load it, even though sfc.dll is only applicable to Windows 2000. Windows Installer will then fail. 

To work around this problem, follow these steps:

1. Select Start > Find > Files or Folders and search for the sfc.dll file on your system.
2. Temporarily rename the sfc.dll file (the version that resides on the Windows NT 4.0 PATH) to sfc.old.
3. Install VisualAge for Java.
4. After you have successfully installed VisualAge for Java, rename sfc.old to sfc.dll.

Fatal LoadLibrary() error

The Fatal LoadLibrary() errror occurs because one or more VisualAge for Java installation kernels (IKernels) were not properly registered by Windows Installer. To work around this problem, you must delete the InstallShield directory the IKernal files reside in, and then reinstall VisualAge for Java by following these these steps:

1. If necessary, exit the installation.
2. Delete the following directory: x:\Program Files\Common Files\InstallShield where x is the drive you attempted to install VisualAge for Java on.
3. Reinstall the product. 

Error 1631 or Internal Error 2755 (Windows NT 4.0 only)

If you install VisualAge for Java on Windows NT 4.0, you may receive one of the following error messages:

• Error 1631: The Windows Installer service failed to start. Contact your support personnel.
• Internal Error 2755: Please contact product support for assistance.

If you receive either of these error messages, you may have registry keys with null values. When you start the VisualAge for Java installation, the userenv.dll file will attempt to parse various registry keys, and if any of the keys have null values, the installation will fail with one of the above error message.

To work around this behavior, you should either remove null environment variables or modify them (change the value from null to a valid value) before you install VisualAge for Java. After you have installed VisualAge for Java, you can return them to their original value.

Caution: Remove or modify null variables with caution. You should consider any potential impact that may occur before removing or modifying them.

Internal Errors 2381, 1303, 1310, 1313 (Windows NT only)

If you are attempting to install VisualAge for Java and any or all of the following conditions are true:

• You are installing VisualAge for Java on Windows NT 4.0.
• The drive that contains the winnt folder or the drive that you are installing VisualAge for Java on is formatted with the NTFS file system
• You have incorrect permissions set on these drives
• You have read-only permissions on the directory you are installing VisualAge for Java in.

you may receive one or more of the following error messages:

• Internal Error 2381: Please contact product support for assistance.
• Internal Error 1303: The Installer has insufficient privileges to access this directory: DirectoryName
• Internal Error 1310: Error attempting to create the destination file: FileName System error code: ErrorCode (this code varies depending on your problem)
• Internal Error 1315: The specified folder 'FolderName ' is not writable.

This problem has been reported to occur when there were only Read permissions on the following folders:

\Program Files\IBM\VisualAge for Java
\WinNT\Installer

To resolve this problem, ensure that you have the necessary permissions on your drives or directories. To do this, follow these steps:

1. In Windows Explorer, select the appropriate drive or directory.
2. Right-click the folder and select Properties from its pop-up menu.
3. Select the Security tab. Click Permissions.
4. Select Everyone. From the Type of Access drop-down menu select Full Access.
5. Select the Replace Permissions on Subdirectories check box.
6. Click OK.
7. Click Yes when prompted to confirm if you want to you want to replace permissions on all subdirectories.
8. Click OK.
9. Install VisualAge for Java.

Internal Error 2735 Engine Startup

If you receive error 2735, perform the following steps to work around it:

1. Search for the following files in your Windows 32 system directory:
   • shd401lc.dll
   • shdoclc.dll
   • shdoc401.dll
   • shdocvw.dll
2. Rename shd401lc.dll to shd401lc.old.
3. Rename shdoclc.dll to shdoclc.old.
4. Select Start > Run to open the Run dialog. Run the following commands to unregister these .dll files. 
   • regsvr32 /u shd401lc.dll
   • regsvr32 /u shdoclc.dll
5. Register these dlls by running the following commands from the Run dialog:
   • regsvr32 shdoc401.dll
   • regsvr32 shdocvw.dll
6. Install VisualAge for Java.

If you receive the following error message, the value of your Common Administrative Tools registry file may be incorrect:

Error 1606. Could not access network location \Profiles\AllUsers\StartMenu\Programs\Administrative Tools\.
Internal Error 2707. INSTALLDIR.

You must edit the value of the Common Administrative Tools registry file before you can install VisualAge for Java. To do so, follow these steps:

1. Invoke regedit.exe from a command prompt.
2. Expand and select the key
   HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folder
3. Select Common Administrative Tools.
4. Select Edit > Modify.
5. In the Value Data field, enter the following: %SystemRoot%\Profiles\AllUsers\StartMenu\Programs\Administrative Tools
6. Click OK.
7. Select Registry > Exit from the menu bar.
8. Install VisualAge for Java.

B.4.2 Known limitations and problems with uninstallation 

The following is a list of items that you should be aware of during uninstallation.

B.4.2.1 Disk space

You must have at least 2MB free on your Windows system drive, and your environment variable TEMP or TMP must point to a valid temporary directory with at least 5MB free.

B.4.2.2 Uninstalling the Distributed Debugger

If you installed the Distributed Debugger as part of your VisualAge for Java installation, you should uninstall VisualAge for Java BEFORE you uninstall the Distributed Debugger. After you have uninstalled VisualAge for Java, you can uninstall the Distributed Debugger by going to the Debugger installation directory and running the uninstallation program.

If you have uninstalled VisualAge for Java, and you cannot uninstall the Distributed Debugger, you must delete the registry key:

HKEY_LOCAL_MACHINE/SOFTWARE/IBM/IBM Distributed Debugger/CurrentVersion/install/ParentProducts/VisualAge for Java

and then try to uninstall the Debugger again. DO NOT follow these steps if you are using the Distributed Debugger with any other products because you will no longer be able to use the debugger after you delete the registry key.

Follow these steps:

1. Type regedit.exe at a command prompt.
2. In the Registry Editor, expand and select the key
   HKEY_LOCAL_MACHINE/SOFTWARE/IBM/IBM Distributed Debugger/CurrentVersion/install/ParentProducts/VisualAge for Java
3. Select Edit > Delete from the menu bar for this key.
4. Select Yes when asked to confirm deletion of the key.
5. Select Registry > Exit from the menu bar.

As well, set the value of the following registry key to 1:

HKEY_LOCAL_MACHINE/SOFTWARE/IBM/IBM Distributed Debugger/CurrentVersion/install/refcount

B.4.2.3 Environment variables (Windows 98)

When you uninstall VisualAge for Java on Windows 98 some environment entries may be left in your autoexec.bat file. Normally these leftover entries do not cause any problems, but if you uninstall and re-install the product several times, two problems may occur. You may have conflicting path statements that can prevent the online help from working or you may run out of path space, which could prevent you from re-installing the product successfully.

To solve these problems:

1. Make a backup copy of your autoexec.bat file.
2. Determine if you have another program that requires the HTML search engine (such as DB2) on your system by following these steps:
   a) Uninstall VisualAge for Java and reboot your system.
   b) Type regedit.exe at a command prompt and, in the Registry Editor, expand the HKEY_LOCAL_MACHINE\SOFTWARE\ tree. If there is an IBM directory in this tree, expand it to see if there is an NetQuestion directory. If you see this directory, then you are probably using the search engine with another IBM product.
3. If you are not using the HTML search engine for another product, then remove any IMN or IMQ entries in your autoexec.bat file before re-installing VisualAge for Java.
4. If you are using the HTML search engine for another product, delete any duplicates of these entries from your autoexec.bat file:
   
   IMNINST
   IMNINSTSRV
   IMNNQ
   IMNNQ_95
   IMQCONFIGCL
   IMQCONFIGSRV
   Also delete duplicate entries of the line IF EXIST X:\IMNNQ_95\IMNENV.BAT CALL IMNEV.BAT
5. Make sure that you do not remove the original entries when you remove the duplicates. If you are not sure which entries are the original ones, then you must determine where the system considers NetQuestion to be installed. Follow these steps:
   1. Type regedit.exe at a command prompt.
   2. In the Registry Editor, expand the key \\HKEY_LOCAL_MACHINE\SOFTWARE\IBM\NetQuestion\Installation Directory
   3. The directory value inside of this key shows you the path where NetQuestion is installed. Certain environment variables must contain this directory as part of their value for NetQuestion to function correctly.
      
      If you find any of the above environment variables that include a directory different from the one found in the registry as part of their value, delete them.

B.4.2.4 Uninstalling NetQuestion

When you are uninstalling VisualAge for Java, NetQuestion may not be uninstalled. Problems may occur if NetQuestion is not uninstalled and you later attempt to reinstall the product. 

To remove NetQuestion files installed by VisualAge for Java, follow these steps. It will not affect NetQuestion files installed by other products (for example, DB2).

1. To find the NetQuestion directory, type the following at a command prompt: set imninstsrv. This command will provide you with the location where NetQuestion is installed on your machine. For example,

   IMNINSTSRV=C:\imnnq_nt

   Your NetQuestion directory location may appear differently, depending on which drive you installed VisualAge for Java on, and which operating system you are using. If you receive an error message such as "Environment variable imninstsrv not defined", then all the NetQuestion files have been uninstalled.

2. Go to the NetQuestion directory (this is the information that follows IMNINSTSRV=)
3. Type vahcfg remove /p vj32

This removes any NetQuestion files that VisualAge for Java installed. 

If you later reinstall VisualAge for Java, and the help fails, refer to the Troubleshooting guide for more information about recovering from help failures. The Troubleshooting guide (trshoot.htm) is located on the VisualAge for Java, Professional Edition product CD and on the VisualAge for Java, Enterprise Edition, Additional Features CD. After you install VisualAge for Java, it is also located in X:\IBMVJava, where X:\IBMVJava is your VisualAge for Java installation directory.

Part C: EMSRV

You must use EMSRV, Version 7.1, if you are planning on working in a team environment with the Enterprise Edition of VisualAge for Java.

All EMSRV files are located on the Additional Features CD.

C.1.0 Prerequisites

Please also refer to the section on "Known problems and limitations" at the end of Part C before installing EMSRV.

C.1.1 Supported Platforms

The EMSRV server is supported for the following operating system platforms:

• Novell NetWare4.2
• Novell NetWare 5.1
• OS/2 (R) Warp Version 4.0
• OS/2 Warp Server for e-business
• Windows NT (R) Workstation Version 4.0 (with Service Pack 5) **
• Windows NT Server Version 4.0 (with Service Pack 5) **
• Windows (R) 2000 Professional **
• Windows 2000 Professional Server **
• Windows 2000 Advanced Server **
• Sun Solaris (TM) Version 2.6 (with Patch 106757-05) +
• Sun Solaris Version 7.0
• HP-UX Version 10.20 *
• HP-UX Version 11.0 *
• AIX (R) Version 4.3.2
• AIX Version 4.3.3
• Red Hat Linux 6.1
• Red Hat Linux 6.2

* Note: HP-UX is supported on 700-class workstation machines only. It has been tested on an HP-UX 9000/715/60 machine and an HP-UX 9000/782/200+ machine. Because 800-class (server) machines have a different architecture and require different binaries, EMSRV is not supported on 800-class machines.

+ For information about obtaining this patch, refer to section C.1.4.

IBM no longer supports EMSRV on Netware 4.11 or Netware 5.0, but EMSRV can be run on that platform if CLIBAUX.NLM is loaded before EMSRV.NLM is loaded. CLIBAUX.NLM is included with Novell's Support Pack 8a but is also available separately from Novell in the file CLIBAUX1.EXE, which can be found at the following location:

http://support.novell.com/cgi-bin/search/download?/pub/updates/nw/nw42/clibaux1.exe

Withdrawal of support for SMP hardware

** IMPORTANT NOTE: Running any release of EMSRV for Windows NT/2000 on a machine with more than one processor may lead to repositories becoming corrupt.

EMSRV is no longer supported on Windows NT/2000 servers that run on SMP hardware (machines with more than one processor). The decision to remove support for SMP hardware is due to the frequency of reports concerning repository corruptions with Windows servers and SMP hardware. EMSRV continues to support SMP hardware for all other operating systems.

IBM ACCEPTS NO LIABILITY FOR DAMAGES YOU MAY SUFFER AS A RESULT OF USE OF EMSRV ON A WINDOWS NT/2000 SERVER THAT RUNS ON SMP HARDWARE, INCLUDING BUT NOT LIMITED TO, DAMAGES CLAIMED BY YOU, BASED ON THIRD PARTY CLAIMS. IN NO EVENT WILL IBM, ITS SUPPLIERS, AGENTS AND EMPLOYEES BE LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE, EXEMPLARY OR CONSEQUENTIAL DAMAGES WHICH MAY RESULT FROM USE OF EMSRV ON A WINDOWS NT/2000 SERVER THAT RUNS ON SMP HARDWARE.

If you want to use EMSRV on a server that runs on SMP hardware, you must use the -mp parameter when you start EMSRV. This will bypass the check for SMP hardware. By doing this, you will be running EMSRV on an unsupported platform and must assume full responsibility (IBM DOES NOT ASSUME RESPONSIBILITY OR LIABILITY OF ANY KIND) if repositories become subsequently corrupted.

EMSRV does not exploit extra processors, by virtue of the fact that EMSRV is an input/output-bound process, not processor-bound. Consequently, the performance of EMSRV is not impacted by the number of processors on your server.

C.1.2 TCP/IP

TCP/IP must be installed and configured on your server.

C.1.3 Novell patches required to run EMSRV

We recommend you obtain and apply the NetWare Minimum Patch List. These patch files are available at http://support.novell.com/misc/patlst.htm. You must select and apply the appropriate patches for the version of NetWare you are using.

C.1.4 Patch required to run EMSRV on Solaris

There is a bug in the Solaris, Version 2.6 implementation of PAM that prevents EMSRV from working correctly. Patch 106257-05 must be applied if you are using EMSRV on Solaris, Version 2.6. The patch is available at:

http://sunsolve.sun.com/pub-cgi/retrieve.pl?doc=fpatches%2F106257&zone_32=PAM

The specific bug which this patch fixes is:

4092227 pam_conv appdata_ptr member is not passed thru to conv() function as documented

The patch is not required if you are working with Version 7.0 of Solaris.

C.1.5 File systems supported

EMSRV has been tested and certified with the following file systems:

NetWare

• NWFS (NetWare File System) with DOS namespace
• NWFS with OS/2 or LONG namespace
• NSS (Novell Storage Services) with DOS namespace
• NSS with OS/2 or LONG namespace

OS/2

• HPFS (High-Performance File System)
• FAT

Windows NT and Windows 2000

• NTFS (New Technology File System)
• FAT32
• FAT

Solaris

• UFS (Unix File System)

HP-UX

• VxFS (Veritas File System)

AIX

• JFS (Journaled File System)

Linux

• EXT2FS (Second Extended File System)

EMSRV only supports locally-mounted file systems.

C.2.0 Installation

This section contains instructions for installing the EMSRV repository server program and a shared repository. For instructions for starting the server, refer to the "Server setup and administration" file emsrv71.htm (emsrv70.htm for all languages other than English), which can be found in the TeamServer\docs directory.

C.2.1 Installing EMSRV for Windows(R)

Setting up EMSRV for Windows
Before you install EMSRV on Windows, you should note the following facts about file types:

• The path to a repository accessed via EMSRV for Windows NT must be specified at the command line as a FAT, NTFS or UNC path, relative to the EMSRV working directory (that is, when you specify the path to the repository it must begin with the EMSRV working directory). It is not possible to access a repository residing on a remote volume (that is, a remote unit of data storage). Examples of this include drives shared using Microsoft (R) Networking that reside on other machines, and NetWare volumes accessible by the Gateway (and Client) Services for NetWare. 
• When using EMSRV for Windows NT or Windows 2000, long file names may be created and viewed on FAT, FAT32, and NTFS volumes. Unlike earlier FAT implementations, implementation for Windows NT and Windows 2000 has long file name support. Long file name support is required for the stored resource management feature used by VisualAge for Java, Version 4.0.

Installing EMSRV on Windows
To install the EMSRV repository server program and a shared repository on a Windows NT or Windows 2000 server, follow these steps:

1. From the TeamServer/Windows directory on the Additional Features CD, run setup.exe.
2. Follow the on-screen instructions. When prompted to select an installation directory, select a subdirectory that is part of your PATH or create a subdirectory and add it to your PATH. We suggest placing them in a location with a lot of free space because the emsrv.log file will be written to the subdirectory you select.
3. Extract the following from the ide.zip file into the desired directory: 
   • ivj.dat (repository file)
   • ivj.dat.pr directory (project resources directory)

   The ide.zip file is located in the ivj40\backup directory which is located on the on the VisualAge for Java, Enterprise Edition, Additional Features CD. If you have an electronic version of VisualAge for Java it can be found in your temporary directory (where you extracted your parts to).

This directory is where you intend to store shared source code repositories. When you start the server later, you will specify this subdirectory as the EMSRV working directory, using the -W EMSRV startup parameter when you start the server.

EMSRV must have full rights to read, write and search the entire tree of directories in the ivj.dat.pr directory. The ivj.dat.pr directory should always be copied to the same directory as ivj.dat, or you will not be able to access your project resources.

You may choose to rename the repository file, for example to team1.dat. If you rename the repository after copying it onto the server, you must rename the project resources directory accordingly. For example, if you rename the repository to team1.dat, you must change the name of the project resources directory to team1.dat.pr.

Team members will need to specify the repository file name when they install the VisualAge for Java client code. They also will need to specify the path on the server machine.

1. If you wish to enable password checking through the use of a passwd.dat file, copy the passwd.dat file from the TeamServer directory to the same directory where you copied ivj.dat. For more information on the types of password checking available, refer to the "Server setup and administration" file emsrv71.htm (emsrv70.htm for all languages other than English), which can be found in the TeamServer\docs directory.
2. Verify that TCP/IP is installed and correctly bound to a LAN adapter. You can verify the binding by using the ping command (for example, ping IP address/host name)to communicate with the server from a workstation on the LAN.
3. Proceed to install EMSRV in the Windows NT registry (optional), authorize the EMSRV user, and start EMSRV. These topics are described in the "Server setup and administration" file, emsrv71.htm (emsrv70.htm for all languages other than English).

If you prefer to start EMSRV as a service rather than from a command prompt, you can install EMSRV in the Windows registry. There are two advantages to installing EMSRV as a service:

• You can specify automatic startup so that EMSRV will start whenever the repository server is booted.
• You can specify the default settings that you want EMSRV to use. For example, you might want to ensure that password validation is always enabled.

Tip: If EMSRV is started as a service, the default EMSRV working directory is the Windows NT or Windows 2000 system32\directory. It is recommended that you change this default by using the -W parameter when you install EMSRV as a service in the Windows NT or Windows 2000 registry.

Important: EMSRV is no longer supported on Windows NT/2000 servers that run on SMP hardware (machines with more than one processor). The decision to remove support for SMP hardware is due to the frequency of reports concerning repository corruptions with Windows servers and SMP hardware.  EMSRV continues to support SMP hardware for all other operating systems.

IBM ACCEPTS NO LIABILITY FOR DAMAGES YOU MAY SUFFER AS A RESULT OF USE OF EMSRV ON A WINDOWS NT/2000 SERVER THAT RUNS ON SMP HARDWARE, INCLUDING BUT NOT LIMITED TO, DAMAGES CLAIMED BY YOU, BASED ON THIRD PARTY CLAIMS. IN NO EVENT WILL IBM, ITS SUPPLIERS, AGENTS AND EMPLOYEES BE LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE, EXEMPLARY OR CONSEQUENTIAL DAMAGES WHICH MAY RESULT FROM USE OF EMSRV ON A WINDOWS NT/2000 SERVER THAT RUNS ON SMP HARDWARE.

If you want to install and start EMSRV as a Windows NT/2000 service on SMP hardware you must install the service using the -mp parameter. This will bypass the check for SMP hardware. By doing this, you will be running EMSRV on an unsupported platform and must assume full responsibility (IBM DOES NOT ASSUME RESPONSIBILITY OR LIABILITY OF ANY KIND) if repositories become subsequently corrupted.

If you do not install the service using the -mp parameter, the service will not start and you will receive the following error message:

Could not start the EMSRV service on \\host
Error 2140: An internal Windows NT error occurred.

If you attempt to install EMSRV as a service again (for example, to add the -mp parameter), the service will install successfully, but you will receive the following error:

Message file emsrvmsg.dll, could not be copied to C:\WINNT\System32\emsrvmsg.dll

--- OS error 1224: The requested operation could not be performed on a file with a user mapped section open. Make sure the DLL is in the same directory as EMSRV.EXE.

You can ignore this error message, as the DLL will already have been installed when the service was previously installed.

To install EMSRV as a service:

1. From a command prompt, change to the directory where the EMSRV executable program is installed.
2. Issue the command emsrv -install [parameter2] [parameter3] ...  The first parameter must be -install; the others are the EMSRV startup parameters that you have chosen for your environment.
   
   The following is an example of this command:
   
   emsrv -install -u joe -p donttell -W j:\sharedrep -rn
   
   This example installs EMSRV as a service in the Windows registry, with joe as the EMSRV user name and donttell as joe's password. By default, the EMSRV working directory will be j:\sharedrep and native password validation will be enforced.
   
   A message confirms that EMSRV has been installed.
3. Steps a and b are slightly different for Windows NT and Windows 2000.
   a) From the Windows NT Control Panel, double-click Services. The Services dialog box will appear. Select EMSRV from the list of services. 
   b) From the Windows 2000 Control Panel, double-click Administrative Tools. Double-click Services. Double-click EMSRV.
   You can start it manually from here. EMSRV is now installed as a service in the registry and the necessary DLLs have been copied to the system directory.
4. In the Startup Parameters text box, type the EMSRV startup parameters that you want to use. If you are specifying the working directory for EMSRV to use, you must type an extra backslash for each backslash in the path. Here is an example:
   
   -u emsrvacc -p secret -W d:\\javateam
5. Click Start. A message will appear, informing you that EMSRV is starting.

For more information about starting EMSRV, refer to the "Server setup and administration" file emsrv71.htm(emsrv70.htm for all languages other than English), which can be found in the TeamServer\docs directory.

The parameters that you provided will be used, by default, whenever EMSRV is started. You can also override or add to these parameters if you start EMSRV manually from the Services icon of the Windows Control Panel.

Setting up EMSRV for Netware
Before you install EMSRV on Netware, you should note the following limitations:

• When using EMSRV for NetWare, long file names may only be created and viewed on NetWare volumes to which the LONG or OS/2 namespace has been added. Long file name support is required for the stored resource management feature used by VisualAge for Java 4.0
• EMSRV for NetWare requires the NetWare TCP/IP stack (TCPIP.NLM) to be loaded and configured on the server. When EMSRV for NetWare is started, TCPIP.NLM will automatically be loaded if it is not already installed. The NWSNUT.NLM files, which are required by the EMSRV for NetWare user interface, will also automatically be loaded.

Installing EMSRV on Netware
To install the EMSRV repository server program and a shared repository on NetWare, follow these steps:

1. From the TeamServer\Netware directory, copy the following program files to the SYS:\SYSTEM directory on the server:
   • emsrv.nlm
2. Extract the following from the ide.zip file into the desired directory on the server:
   • ivj.dat (repository file)
   • ivj.dat.pr directory (project resources directory)

   The ide.zip file is located in the ivj40\backup directory which is located on the on the VisualAge for Java, Enterprise Edition, Additional Features CD. If you have an electronic version of VisualAge for Java it can be found in your temporary directory (where you extracted your parts to).

When you start the server later, you will specify this subdirectory as the EMSRV working directory, using the -W EMSRV startup parameter. EMSRV must have full rights to read, write and search the entire tree of directories in the ivj.dat.pr directory. The ivj.dat.pr directory should always be copied to the same directory as ivj.dat, or you will not be able to access your project resources.

You may choose to rename the repository file, for example, to team1.dat. If you rename the repository after copying it onto the server, you must rename the project resources directory accordingly. For example, if you rename the repository to team1.dat, you must change the name of the project resources directory to team1.dat.pr.

Team members will need to specify the repository file name and location when they install the VisualAge for Java client code.

1. Copy the sample password file, passwd.dat, from the TeamServer directory to the same directory where you copied ivj.dat. 
2. Verify that the NetWare TCPIP.NLM is loaded and correctly bound to a LAN adapter. You can verify the binding by using the ping command (for example, ping IP address/host name) utility to communicate with the product from a workstation on the LAN.
3. To ensure that hostnames will appear in the EMADMIN output when EMSRV is queried, check that the resolver is set up correctly to enable reverse DNS lookups. Also ensure that the RESOLV.CFGfile (located in sys:\etc) is set up correctly. The following is a sample of how a file would be set up: 
   domain javadev.com
   nameserver 192.168.73.150
4. For instructions for starting the product, refer to the "Server setup and administration" file emsrv71.htm (emsrv70.htm for all languages other than English), which can be found in the TeamServer\docs directory.

C.2.3 Installing EMSRV for OS/2 Warp

Note: OS/2 is no longer supported as a development platform. Refer to Part E for details.

Setting up EMSRV for OS/2
Before you install EMSRV on OS/2, you should note the following:

• When using EMSRV for OS/2, long file names may be created and viewed on HPFS volumes. Long file name support is required for the stored resource management feature used by VisualAge for Java 4.0

Installing EMSRV on OS/2 
To install the EMSRV repository server program and a shared repository on an OS/2 server, follow these steps:

1. Copy the following three files from the TeamServer directory to the desired directory on the OS/2 computer:
   • emsrv.exe
   • emadmin.exe
   • emclient.mod

   Place these files in a subdirectory that is part of your PATH or create a subdirectory and add it to your PATH. We suggest placing them in a location with a lot of free space because the emsrv.log file will be written to the subdirectory you place these files in.

2. Extract the following from the ide.zip file into the subdirectory where you placed the files you copied in step 1:
   • ivj.dat (repository file)
   • ivj.dat.pr directory (project resources directory)

   The ide.zip file is located in the ivj40\backup directory which is located on the on the VisualAge for Java, Enterprise Edition, Additional Features CD. If you have an electronic version of VisualAge for Java it can be found in your temporary directory (where you extracted your parts to).

   This subdirectory is where you intend to store shared source code repositories. When you start the server later, youwill specify this subdirectory EMSRV working directory, using the -W EMSRV startup parameter.

   EMSRV must have full rights to read, write and search the entire tree of directories in the ivj.dat.pr directory. The ivj.dat.pr directory should always be copied to the same directory as ivj.dat, or you will not be able to access your project resources.

   You may choose to rename the repository file, for example to team1.dat. If you rename the repository after copying it onto the server, you must rename the project resources directory accordingly. For example, if you rename the repository to team1.dat, you must change the name of the project resources directory to team1.dat.pr.

   Team members will need to specify the repository file name when they install the VisualAge for Java client code.

3. If you wish to enable password checking through the use of a passwd.dat file, copy the passwd.dat file from the TeamServer directory to the same directory where you copied ivj.dat. For more information on the types of password checking available, refer to the "Server setup and administration" file emsrv71.htm (emsrv70.htm for all languages other than English), which can be found in the TeamServer\docs directory.
4. Verify that TCP/IP is installed and correctly bound to a LAN adapter. You can verify the binding by using the ping command (for example, ping IP address/host name) to communicate with the server from a workstation on the LAN.
5. To start the server, refer to the instructions for starting EMSRV on OS/2, in the "Server setup and administration" file emsrv71.htm (emsrv70.htm for all languages other than English).

C.2.4 Installing EMSRV for AIX

Setting up EMSRV for AIX
Before you install EMSRV on AIX, you should note the following characteristics:

• On AIX, large file support needs to be enabled for both the volume hosting a repository and the user starting the EMSRV process. 
• When creating a file system, ensure that the argument '-o bf=true' is used with mkfs.
• To set the limits for the user starting the EMSRV process, the -Hf and -Sf options for the ulimit command require arguments specifying the number of 512 byte blocks. The following commands should be appropriate to enable repositories up to 16 GB in size:
  
  ulimit -Hf 33554432
  ulimit -Sf unlimited
• EMSRV for AIX authentication is implemented using the system authenticate() function. This allows one EMSRV executable (emsrv) to support both shadowed and nonshadowed passwords in addition to DCE authentication. The authentication method for each user is set in the /etc/security/user file. 

Installing EMSRV on AIX
In the steps below, "EMSRV user" refers to the user who starts the EMSRV program.

You must copy the following files from the TeamServer directory to your machine:

• emsrv
• emadmin

Place these files in a subdirectory that is part of your PATH or create a subdirectory and add it to your PATH. We suggest placing them in a location with a lot of free space because the emsrv.log file will be written to the subdirectory in which you place these files.

Follow these steps for setting up EMSRV on an AIX machine:

1. The EMSRV user or the system administrator (root) sets aside disk space to store repositories.
2. An initial repository can be set up by extracting the following from the ide.zip file to the disk space set aside in step 1.
   • ivj.dat (repository file)
   • ivj.dat.pr directory (project resources directory)

   The ide.zip file is located in the ivj40\backup directory which is located on the VisualAge for Java, Enterprise Edition, Additional Features CD. If you have an electronic version of VisualAge for Java it can be found in your temporary directory (where you extracted your parts to).

   EMSRV must have full rights to read, write and search the entire tree of directories in the ivj.dat.pr directory. The ivj.dat.pr directory should always be copied to the same directory as ivj.dat, or you will not be able to access your project resources. The directories must have rw and x (search) bits set for the EMSRV user.

3. Change the file owner to the EMSRV user or the system administrator. If you plan to have more than one repository, make copies of ivj.dat using different names but retain the same suffix (.dat). If you make duplicate copies of the repository, you must make duplicate copies of the ivj.dat.pr directory and change the name to match the repository it is associated with. For example, if you make a duplicate copy called "team.dat", you must make a duplicate project resources directory called "team.dat.pr"
   The EMSRV user or the system administrator should change to the directory where the repositories are stored and start the EMSRV program, using the appropriate flags. For more information on EMSRV flags, refer to the "Server setup and administration" file emsrv71.htm (emsrv70.htm for all languages other than English), which can be found in the TeamServer\docs directory.
4. The EMSRV user or the system administrator tells the team members the location and name of the team repository. This information is needed when team members install their client code.
5. To start the server, refer to the instructions in the "Server setup and administration" file emsrv71.htm (emsrv70.htm for all languages other than English).

Root access on UNIX platforms is required to authenticate users. EMSRV does NOT need to be started by the root user to accomplish this. Doing so would compromise security because EMSRV would then have complete access to all file systems.

Instead, you should change the owner of the EMSRV executable to 'root' and set the SUID bit of the executable. This can be accomplished as follows:

chown root emsrv
chmod u+s emsrv

When EMSRV attempts to authenticate a user, it will temporarily change the authority of the running EMSRV process to be the authority of the owner of the executable. Once authentication is complete, the authority of the running EMSRV process will be changed back to that of the user that started EMSRV. This happens on a per-process (per-client) basis so while a client is being authenticated, only the process serving that client has temporary root access.

Root access for authentication is required regardless of how EMSRV actually implements authentication. Interfaces such as PAM only provide a common API to permit applications to support multiple authentication methods, configuration specific to each method of authentication must still be correct. 

C.2.5 EMSRV for HP-UX or Solaris

C.2.5.1 Setting up EMSRV for HP-UX or Solaris
Before you install EMSRV on Solaris or HP-UX, you should note the following requirements:

For Solaris

• On Solaris, file systems automatically have large file support, but limits for the user starting the EMSRV process must be set using the ulimit command. The -Hf and -Sf options for the ulimit command require arguments specifying the number of 512 byte blocks. The following commands should be appropriate to enable repositories up to 16 GB in size:
  ulimit -Hf 33554432
  ulimit -Sf unlimited

• EMSRV for Solaris implements authentication using PAM. PAM must be correctly configured on a machine running EMSRV; otherwise, it will not even be possible to shut down EMSRV using EMADMIN. The /etc/pam.conf file must specify EMSRV as a service that uses PAM (it must be specified as "emsrv" not "EMSRV"). An example pam.conf file is included with this release. 
• EMSRV requests 4 bytes of shared memory. Operating system settings define the minimum and maximum sizes for chunks of shared memory that a process can ask for. If your maximum setting is less than 4 bytes or your minimum setting is greater than 4 bytes, EMSRV will not run, and it will not generate the log file. 

For HP-UX 

• On HP-UX, large file support needs to be enabled for both the volume hosting a repository and the user starting the EMSRV process. 
• When creating a file system, ensure that the argument '-o largefiles' is used with newfs.
• To set the limits for the user starting the EMSRV process, the -Hf and -Sf options for the ulimit command require arguments specifying the number of 512 byte blocks. The following commands should be appropriate to enable repositories up to 16 GB in size:
  
  ulimit -Hf 33554432
  ulimit -Sf unlimited

C.2.5.2 Installing EMSRV for HP-UX or Solaris
In the steps below, "EMSRV user" refers to the user who starts the EMSRV program.

You must copy the following files from the TeamServer directory to your machine:

For HP-UX:

• emsrv 
• emsrv.shadow 
• emadmin

For Solaris:

• emsrv 
• emadmin
• pam.conf

Place these files in a subdirectory that is part of your PATH or create a subdirectory and add it to your PATH. We suggest placing them in a location with a lot of free space because the emsrv.log file will be written to the subdirectory in which you place these files.

Follow these steps for setting up EMSRV on a Solaris or HP-UX machine:

1. The EMSRV user or the system administrator (root) sets aside disk space to store repositories.
2. An initial repository can be set up by extracting the following from the ide.zip file to the disk space set aside in step 1.
   • ivj.dat (repository file)
   • ivj.dat.pr directory (project resources directory)

   The ide.zip file is located in the ivj40\backup directory which is located on the on the VisualAge for Java, Enterprise Edition, Additional Features CD. If you have an electronic version of VisualAge for Java it can be found in your temporary directory (where you extracted your parts to).

   EMSRV must have full rights to read, write and search the entire tree of directories in ivj.dat.pr. ivj.dat.pr should always be copied to the same directory as ivj.dat, or you will not be able to access your project resources. The directories must have rw and x (search) bits set for the EMSRV user.

3. Change the file owner to the EMSRV user or the system administrator. If you plan to have more than one repository, make copies of ivj.dat using different names but retain the same suffix (.dat). If you make duplicate copies of the repository, you must make duplicate copies of the ivj.dat.pr directory and change the name to match the repository it is associated with. For example, if you make a duplicate copy called "team.dat", you must make a duplicate project resources directory called "team.dat.pr"
   The EMSRV user or the system administrator should change to the directory where the repositories are stored and start the EMSRV program, using the appropriate flags. For more information on EMSRV flags, refer to the "Server setup and administration" file emsrv71.htm (emsrv70.htm for all languages other than English), which can be found in the TeamServer\docs directory.
4. The EMSRV user or the system administrator tells the team members the location and name of the team repository. This information is needed when team members install their client code.
5. To start the server, refer to the instructions in the "Server setup and administration" file, emsrv71.htm (emsrv70.htm for all languages other than English).

Root access on UNIX platforms is required to authenticate users. EMSRV does NOT need to be started by the root user to accomplish this. Doing so would compromise security because EMSRV would then have complete access to all file systems.

Instead, you should change the owner of the EMSRV executable to 'root' and set the SUID bit of the executable. This can be accomplished as follows:

chown root emsrv
chmod u+s emsrv

When EMSRV attempts to authenticate a user, it will temporarily change the authority of the running EMSRV process to be the authority of the owner of the executable. Once authentication is complete, the authority of the running EMSRV process will be changed back to that of the user that started EMSRV. This happens on a per-process (per-client) basis so while a client is being authenticated, only the process serving that client has temporary root access.

Root access for authentication is required regardless of how EMSRV actually implements authentication. Interfaces such as PAM only provide a common API to permit applications to support multiple authentication methods, configuration specific to each method of authentication must still be correct. 

C.2.6 EMSRV for Linux

C.2.6.1 Setting up EMSRV for Linux
Before you install EMSRV on Linux, you should note the following information:

• EMSRV for Linux implements authentication using PAM. This allows both shadowed and nonshadowed passwords to be supported with one EMSRV executable. In addition, Red Hat Linux 6.2 supports MD5 passwords and EMSRV also supports these via PAM.
• PAM must be correctly configured on a machine running EMSRV; otherwise, it will not even be possible to shut down EMSRV using EMADMIN. The PAM configuration file must be copied to /etc/pam.d/emsrv. A sample PAM configuration file is included with this release.

C.2.6.2 Installing EMSRV for Linux
In the steps below, "EMSRV user" refers to the user that starts the EMSRV program.

You must copy the following files from the TeamServer directory to your machine:

• emsrv 
• emadmin
• pam/emsrv

Place these files in a subdirectory that is part of your PATH or create a subdirectory and add it to your PATH. We suggest placing them in a location with a lot of free space because the emsrv.log file will be written to the subdirectory in which you place these files.

Follow these steps for setting up EMSRV on a Linux machine:

1. The EMSRV user or the system administrator (root) sets aside disk space to store repositories.
2. An initial repository can be set up by extracting the following from the ide.zip file to the disk space set aside in step 1.
   • ivj.dat (repository file)
   • ivj.dat.pr directory (project resources directory)

   The ide.zip file is located in the ivj40\backup directory which is located on the VisualAge for Java, Enterprise Edition, Additional Features CD. If you have an electronic version of VisualAge for Java it can be found in your temporary directory (where you extracted your parts to).

   EMSRV must have full rights to read, write and search the entire tree of directories in the ivj.dat.pr directory. The ivj.dat.pr directory should always be copied to the same directory as ivj.dat, or you will not be able to access your project resources. The directories must have rw and x (search) bits set for the EMSRV user.

3. Change the file owner to the EMSRV user or the system administrator. If you plan to have more than one repository, make copies of ivj.dat using different names but retain the same suffix (.dat). If you make duplicate copies of the repository, you must make duplicate copies of the ivj.dat.pr directory and change the name to match the repository it is associated with. For example, if you make a duplicate copy called "team.dat", you must make a duplicate project resources directory called "team.dat.pr"
   The EMSRV user or the system administrator should change to the directory where the repositories are stored and start the EMSRV program, using the appropriate flags. For more information on EMSRV flags, refer to the "Server setup and administration" file emsrv71.htm (emsrv70.htm for all languages other than English), which can be found in the TeamServer\docs directory.
4. The EMSRV user or the system administrator tells the team members the location and name of the team repository. This information is needed when team members install their client code.
5. To start the server, refer to the instructions in the "Server setup and administration" file emsrv71.htm (emsrv70.htm for all languages other than English).

Root access on UNIX platforms is required to authenticate users. EMSRV does NOT need to be started by the root user to accomplish this. Doing so would compromise security because EMSRV would then have complete access to all file systems.

Instead, you should change the owner of the EMSRV executable to 'root' and set the SUID bit of the executable. This can be accomplished as follows:

chown root emsrv
chmod u+s emsrv

When EMSRV attempts to authenticate a user, it will temporarily change the authority of the running EMSRV process to be the authority of the owner of the executable. Once authentication is complete, the authority of the running EMSRV process will be changed back to that of the user that started EMSRV. This happens on a per-process (per-client) basis so while a client is being authenticated, only the process serving that client has temporary root access.

Root access for authentication is required regardless of how EMSRV actually implements authentication. Interfaces such as PAM only provide a common API to permit applications to support multiple authentication methods, configuration specific to each method of authentication must still be correct. 

C.3.0 Migration 

C.3.1 Migrating from Version 6.x or Version 7.0 of EMSRV to Version 7.1

If you currently have Version 6.x or Version 7.0 of EMSRV installed and want to install Version 7.1 of EMSRV, you can either uninstall version 6.x/7.0 of EMSRV and install Version 7.1 or keep your old version of EMSRV and install EMSRV 7.1.

You must install Version 7.1 to work with VisualAge for Java, Version 4.0. 

To move from EMSRV, Version 6.x/7.0 to EMSRV, Version 7.1, follow these steps:

1. Back up your repository.
2. Shut down EMSRV 6.x/7.0.
3. Install EMSRV 7.1.
4. Start EMSRV 7.1. 

EMSRV 7.1 is compatible with EMSRV 6.x/7.0. For example, if you are working in a previous edition of VisualAge for Java (that uses EMSRV 6.x/7.0), you can connect from your previous version to a shared repository running under EMSRV 7.1. 

C.4.0 Preparing for team development  

At this point, you have already installed the repository server programs and a shared source code repository. To finish setting up the team development environment, you must start the server, connect to it from a VisualAge for Java client, and add users to the repository user list.

If you have already installed the VisualAge for Java client on a workstation, you can refer to the online help for more information about setting up the team development environment. Otherwise, refer to the team.pdf in the pdf directory. The pdf directory is located on the VisualAge for Java, Enterprise Edition, Additional Features CD. If you have an electronic version of VisualAge for Java it can be found in your temporary directory (where you extracted your parts to). If you did not download the part containing the PDFs, you will not have this directory.

In the following instructions, it is assumed that the shared repository that is installed on the server is called ivj.dat. When starting the repository server program, the administrator should provide the path of the ivj.dat file as the EMSRV working directory.

C.4.1 Preparing the team server

Before team developers can work with the shared repository, the administrator must set up the VisualAge for Java server and start the EMSRV repository server program. If some developers wish to start using VisualAge for Java, Version 4.0 before the server is ready, they can first install as standalone users and then connect to the shared repository later.

C.4.2 Testing a client connection

To confirm that the server has been successfully started, the administrator should connect to the shared repository from a VisualAge for Java, Enterprise Edition, Version 4.0 client. This action will confirm that the server's TCP/IP connection is working properly, that EMSRV has been started with the correct parameters, and that the administrator is aware of what server information must be provided during client installation.

For information on connecting to a shared repository, refer to "Connecting to a shared repository" in the VisualAge for Java online help or the team.pdf file. The team.pdf file is in the pdf directory. The pdf directory is located on the VisualAge for Java, Enterprise Edition Additional Features CD. If you have an electronic version of VisualAge for Java it can be found in your temporary directory (where you extracted your parts to). If you did not download the part containing the PDFs, you will not have this directory.

C.4.3 Adding users to the repository user list

When a client first connects to the shared repository, the user is prompted to provide a workspace owner name. The user cannot start the IDE without first selecting a valid workspace owner name from a list of repository users.

By default, VisualAge for Java, Version 4.0 has a user called Administrator in its repository user list. Each user could initially choose Administrator as the workspace owner name; however, it is strongly recommended that every user provide a unique name to connect to the server, right away. In the VisualAge for Java team development environment, change control is based on defined user roles, which means each developer should be uniquely identified. To meet this objective, the administrator must add everyone to the list of repository users. (The only VisualAge for Java user who can add other names to a repository user list is Administrator.) The unique name belonging to each user should correspond to a system user name if native password verification is used.

For information on adding users to the repository list, refer to in the VisualAge for Java team online help or the team.pdf file in the pdf directory. The pdf directory is located on the VisualAge for Java, Enterprise Edition, Additional Features CD. If you have an electronic version of VisualAge for Java it can be found in your temporary directory (where you extracted your parts to). If you did not download the part containing the PDFs, you will not have this directory.

Now that the server is set up and ready, users should proceed to install their VisualAge for Java clients. Information on installing VisualAge for Java team clients can be found in Part B of this guide.

C.5.0 Limitations and known problems (EMSRV) 

C.5.1 Performance on low-bandwidth, high-latency network connections

The protocol used between EMSRV clients and EMSRV generally results in a high rate of packets transmitted to the server. This is due to the fact that a large majority of the processing is done at the client. The majority of requests processed by EMSRV are I/O requests (for example, record lock, read, and write requests).

As a result of this architecture, performance experienced at the client-end is highly sensitive to the latency of the network. Latency (measured by round-trip or 'ping' packet times) of less than 5 ms is expected to produce acceptable performance. LAN latency is generally less than 1 ms but a WAN connection or dial-up modem connection on a telephone line may have a latency as high as 500 ms. Even with high-speed DSL, cable, frame relay, or ISDN connections, the latency is a function of the distance between two end-points.

In general, performance on a dial-up modem connection across a telephone line yields unacceptable performance because connections of that type typically have a latency of 200 ms or more. High-speed connections also yield unacceptable performance unless the distance between the client and the server is a few hundred kilometers or less.

The EMSRV protocol is not particularly bandwidth-intensive but bandwidth usage is a function of the number of clients simultaneously using a connection.

C.5.2 TCP/IP connection limitations

The default limit for client connections to EMSRV is 512. This limit can be changed using the -M command-line option when you start EMSRV.

The number is bounded primarily by memory, but some TCP/IP stacks will run out of stream sockets before the limit of memory is reached. Typically, this number is greater than one hundred, but it varies with each stack.

C.5.3 Detecting unexpectedly dropped connections

EMSRV uses the TCP/IP KEEPALIVE timer to detect connections which have been unexpectedly dropped when a client has crashed or been rebooted. Some TCP/IP stacks allow the KEEPALIVE timeout to be changed. Typically, the default setting is 120 minutes.

EMADMIN may be used to list the connections and identify a connection that has not interacted with the server for a long time by the time of the last request. Such a connection may then be closed using the EMADMIN STOP command and the -k option.

C.5.4 Interchanging different versions of EMSRV and EMSRV utilities

VisualAge for Java, Version 4.0, includes version 7.1 of EMSRV and version 7.0 of the EMADMIN utilities.

You must use EMADMIN 7.0 with EMSRV 7.1. EMADMIN 7.0 will not work correctly with releases of EMSRV before 7.0.

C.5.5 PAM Limitations

On Linux and Solaris platforms, authentication is implemented using PAM (Password Authentication Modules). Although this would theoretically allow the use of any PAM (module) with EMSRV by changing the relevant PAM configuration file, in practice this is not possible.

EMSRV does not converse with clients in a manner that is entirely compatible with the PAM architecture. As a result, EMSRV authentication will only work where the module prompts initially for a text password (supplied initially by the client).

C.5.6 Passwords with non-ASCII characters cannot be used to authenticate with EMSRV 

Due to a bug in the Microsoft C run-time libraries, any password containing non-ASCII characters entered in response to the prompt:

'Enter the password of the user who started EMSRV'

will not be correctly interpreted. The workaround is to supply the password with the -p option when running EMADMIN.

The EMSRV for NetWare NLM uses Novell's NLM User Interface Developer Components (NWSNUT). When running on Japanese NetWare, graphics characters used in the NWSNUT menus and windows are not available and will appear as corrupted characters. This is not a bug in the EMSRV NLM nor in NetWare, but rather it is a limitation of the Shift-JIS code page.

When EMADMIN 7.0 is used to copy a VisualAge for Java 4.0 repository, it does not copy the corresponding stored project resources directory. You must copy the stored project resources directory manually.

Part D. Component-specific migration information

Please refer to section 18.0 for important Swing class migration information.

D.1.0 CICS Transaction Server (CICS TS)

This version of VisualAge for Java does not support the CICS(R) Transaction Server. The classes required to support CICS TS 1.3 and below are not included with this version. Any CICS TS applications that you attempt to migrate from earlier versions of VisualAge for Java will not work in Version 4.0 and should be deleted from your Version 4.0 workspace and repository.

If you want to work with CICS TS 1.3 or below, you must continue to use an older (3.02 and earlier) version of VisualAge for Java. For the time being, you must also use an older (3.02 and earlier) version of VisualAge for Java if you want to use the JCICS interface or need CICS support for IIOP. We do not support the CICS Transactions server because it is based on JDK 1.1.x.

D.2.0 Data Access beans

D.2.1. Migrating from Version 2.0 or 3.0x of VisualAge for Java

Data Access beans use Swing components and interfaces. Any applications developed that use the beans must be migrated from the old JDK 1.1.x Swing packages to the new J2SDK v.1.2.2. Swing packages. To do this, select the affected classes and packages after installing VisualAge for Java, Version 4.0, open the Fix/Migrate SmartGuide; and select the Include JDK1.2 renamed packages check box. This will add the appropriate From/To entries for Swing and enable you to automatically migrate Swing references to the Java 2 SDK. Any errors that occur while you are migrating will be logged in the Log window.

For more information on how to properly migrate your applications, refer to the Visual Composition Editor online help file "Fix/migrate guidelines for class or package references" and the related task file "Repairing class or package references".

D.2.2. Migrating from Version 3.5 of VisualAge for Java

You do not need to take any extra steps to migrate your Data Access Beans if you migrated for VisualAge for Java, Version 3.5, as Data Access Beans in Version 3.5 used the J2SDK v.1.2.2 Swing packages.

D.3.0 Data Access Builder

The Data Access Builder is no longer included in VisualAge for Java. If you want to keep using the Data Access Builder, you will have to continue working in a previous version of VisualAge for Java.

There is no new feature in VisualAge for Java, Version 4.0 that directly replaces the functionality previously provided by the Data Access Builder, but there are three components in VisualAge for Java that provide similar functionality - Data Access beans, Persistence Builder and the Enterprise JavaBeans Development Environment. Each feature offers a different approach to creating data access classes. 

You cannot migrate your code over to VisualAge for Java, Version 4.0 and reuse it in any of these tools. You will have to recreate your applications if you want to use them in Version 4.0. Use the feature that best suits your main focus in code development and what you want your applications to do.

A comparison of the Data Access Builder, Data Access beans, and Persistence Builder is provided as an appendix to this guide. 

D.4.0 EJB(TM) Development Environment

D.4.1 Migrating enterprise beans from VisualAge for Java, Version 2.0, Enterprise Update

If you created enterprise beans in VisualAge for Java, Version 2.0, Enterprise Update, and you want to use them in VisualAge for Java, Version 4.0, you need to complete the following activities in your current version of VisualAge for Java, Version 2.0, Enterprise Update:

1. In the Schema Browser, save any unsaved schemas.
2. In the Map Browser, save any unsaved maps.
3. If you have made any recent changes to the schemas or maps since you last generated deployed code, delete the deployed code and then regenerate it and test it.
4. Version the packages (including the schema and map packages) and the project, then export the project in .dat format.

To finish migrating your enterprise bean code, in VisualAge for Java, Version 4.0, follow the steps in either Scenario 1 or Scenario 2 below, depending on whether you are importing from a repository (recommended) or from a JAR file.

Scenario One - Importing from a repository
If you are importing your beans from a repository, follow these steps:

1. Add the projects that contain your enterprise beans, schemas, and maps from the repository into the workspace. Error icons will appear beside some of the loaded classes.
2. Create an open edition of each of the projects. Also create an open edition of any of the packages containing old generated classes.
3. Use the Schema browser and the Map browser to load all available schemas and maps into the workspace, then regenerate the deployed classes.
4. If you did not create and save a schema and map, then create a default schema and map, and regenerate your deployed code.
5. If you plan to work solely in Version 4.0, delete any existing EJB test client classes in the Projects page that you generated earlier using the EJB Development Environment of Version 2.0, Enterprise Update. These classes will contain errors and will not work in Version 4.0 because the EJB test client no longer uses generated classes. (Note that the test client classes will not appear in the EJB Types pane of the EJB page prior to their deletion, so you will need to check the Projects page to determine if there are any to delete.)

You can find more information on how to perform these steps in the VisualAge for Java online help for the EJB Development Environment.

Scenario Two - Importing from a JAR file
If you exported your enterprise beans to a JAR file, follow these steps:

1. On the EJB page, select EJB > Import Enterprise Beans to import the JAR file into your VisualAge for Java, Version 4.0 workspace.
2. Error icons will appear beside many of the imported classes, because the JAR file will not contain the required maps.
3. Regenerate the schemas, maps, deployed classes, and any test clients you have.
4. If you plan to work solely in Version 4.0, delete any existing EJB test client classes in the Projects page that you generated earlier using the EJB Development Environment of Version 2.0, Enterprise Update. These classes will contain errors and will not work in Version 4.0 because the EJB test client no longer uses generated classes. (Note that the test client classes will not appear in the EJB Types pane of the EJB page prior to their deletion, so you will need to check the Projects page to determine if there are any to delete.)

You can find more information on how to perform these steps in the VisualAge for Java online help for the EJB Development Environment.

D.4.2 Migrating enterprise beans from VisualAge for Java, Version 3.0 or 3.02

If you have an existing enterprise bean that has deployed code that was generated using either VisualAge for Java Version 3.0 or Version 3.02, and you now want to work with the enterprise bean using VisualAge for Java, Version 4.0, you must migrate the enterprise bean to Version 4.0 and then explicitly delete and regenerate the deployed code.

However, before you migrate your enterprise bean code to Version 4.0, you need to complete the following activities in your current version of VisualAge for Java (Version 3.0 or Version 3.02):

1. In the Schema Browser, save any unsaved schemas.
2. In the Map Browser, save any unsaved maps.
3. If you have made any recent changes to the schemas or maps since you last generated deployed code, delete the deployed code and then regenerate it and test it.
4. Version the packages (including the schema and map packages) and the project, then export the project in .dat format.

To migrate the enterprise bean code and then regenerate the deployed code, complete the following steps in VisualAge for Java, Version 4.0, in the exact order shown:

1. Import the project repository file into the workspace.
2. Create an open edition of the project. Also, create an open edition of any of the packages that contain deployed code that you want to delete.
3. In the Workbench, click the EJB tab.
4. In the Enterprise Beans pane, select the enterprise bean or group for which you want to delete the deployed code.
5. Select EJB > Delete.
6. Click Deployed Code to delete the deployed code.
7. Migrate your associations (if any) by following the instructions in section D.4.3 (if you are migrating from Version 3.0) or section D.4.4 (if you are migrating from Version 3.02).
8. Ensure that your bean class and bean class parents do not contain any errors.
9. Regenerate your EJB access beans (if any) by completing the following steps:
   1. In the EJB page of the Workbench, select the enterprise bean that is associated with the access bean that you want to migrate.
   2. From the EJB menu, select Add > Access Bean to open the Create Access Bean SmartGuide, then click the Finish button. All of the necessary migration changes to the access bean are made automatically.
10. Regenerate the deployed code.
11. If you plan to work solely in Version 4.0, delete any existing EJB test client classes in the Projects page that you generated earlier using the EJB Development Environment of Version 3.0 or 3.02. These classes will contain errors and will not work in Version 4.0 because the EJB test client no longer uses generated classes. (Note that the test client classes will not appear in the EJB Types pane of the EJB page prior to their deletion, so you will need to check the Projects page to determine if there are any to delete.)
12. If you previously created client JAR files in VisualAge for Java, Version 3.0, 3.02, or 3.5, you should recreate your client JAR files in VisualAge for Java, Version 4.0.

D.4.3 Migrating EJB associations from VisualAge for Java, Version 3.0

When you add, edit, or delete an association in an EJB group that was created in Version 3.0, VisualAge for Java automatically converts all associations in the EJB group to the new association format. To complete the migration process, make the following changes manually:

• Add a call to this._initLinks() in the bean-class methods ejbCreate (all variations), ejbActivate, and ejbLoad. You must also remember to add this call to any future variations of ejbCreate that are added to the bean class.
• Add a call to this._removeLinks() in the bean-class method ejbRemove.

These methods were not converted automatically because of the high probability of handwritten modifications in these methods. VisualAge for Java will add the calls automatically when new beans are created in Version 4.0.

If you import a Version 3.0-or-older CMP entity bean into an EJB group whose associations have already been migrated and then add a new bean that inherits from the imported CMP entity bean, the new bean's bean class will display red Xs in several methods. This is because the imported bean's bean class will be missing the _initLinks, _getLinks,and _removeLinks methods. You must add these methods to the imported bean's bean class by hand.   

When you are ready to deploy your enterprise bean code to a production application server, you should ensure that you also deploy the run-time JAR file that contains the run-time code required by both associations and access beans. This JAR file should be deployed to your application server and should be included in the application server's classpath. Additional information about the run-time JAR file is found in the EJB Development Environment online help.

D.4.4 Migrating EJB associations from VisualAge for Java 3.02

When you first open an EJB group with associations that were created in Version 3.02 of VisualAge for Java, the group will contain error icons next to generated link classes. When you add, edit, or delete an association in this kind of EJB group, VisualAge for Java automatically repairs the link classes for all associations in the EJB group. If you are not planning to make any changes to the association, you will still need to select the association in the Properties pane of the EJB page, and select Edit from its popup menu to open the association editor. You should then click OK to complete the migration process.

VisualAge for Java will automatically remove some association-related methods that were generated in VisualAge for Java 3.02. The methods that are removed are methods that, given the characteristics of the association, would not work correctly in Version 4.0. For example, if a role is part of the primary key, the set method for that role is not valid. The method would have been automatically generated in Version 3.02 and cannot be generated in Version 4.0.

D.5.0 Enterprise Access Builder (EAB) and e-connectors  

D.5.1 Enterprise Access Builder

D.5.1.1 New connector support
The Enterprise Access Builder now supports both Common Connector Framework (CCF) and Java 2, Enterprise Edition (J2EE) Connector Architecture connectors. The Enterprise Access Builder has new tools that will migrate EAB records, Commands, Navigators, and session beans from a CCF format to a J2EE Connector Architecture format. In addition, the following SmartGuides and editors have been updated to reflect the new support for J2EE Connector Architecture:

• Command SmartGuide
• Command Editor
• Session Bean SmartGuide
• Session Bean Editor

For more information on the new support for IBM Connectors and Tools for J2EE(TM) - Beta and the new EAB Migrators, refer to the Enterprise Access Builder online help.

D.5.1.2 Regenerating and editing your records and Commands
If you migrate your EAB applications from a previous version of VisualAge for Java to Version 4.0, you may want to regenerate your records and Commands. They will perform better in Version 4.0 if you regenerate them. 

Previously if you had selected "Direct" and "Shorten names", without selecting "Inner classes" then the names of generated records
were sometimes larger then necessary. This resulted sometimes in names being generated that exceeded the Windows 255 file name limit. The Create Record from Record Type SmartGuide has been optimized now to generate names as short as possible when the above options are selected. However, if you regenerate with these options, since record names may change, it can affect your applications.

If your EAB Command was created in Version 2.0x, you cannot edit it in the Command Editor. However, you can edit it in the Visual Composition Editor. The current version of the run-time environment is backwards compatible, so you can run Version 2.0x Commands with it.

D.5.1.3 Deploying your applications
Version 4.0 is a transition release for Enterprise Access Builder (EAB). The older Common Connector Framework (CCF) architecture, which EAB was based on, is moving to the new J2EE Connector architecture. The EAB documentation covers this transition and the differences between them. For this release both architectures are supported. In deployment, this implies that there are some differences. Read the deployment section in the EAB documentation for those details. The following paragraph is a simple overview of deployment.

For existing applications, you can continue as you have in the past. Deploy your application with eab\runtime30\eablib.jar, ccf.jar, recjava.jar and the JAR files that your connector requires at run time. For new applications that have added some J2EE Connector architecture-related components, such as records and Commands that make use of J2EE architecture, deploy your applications with eab\runtime35\eablib.jar. It is bimodal, meaning it supports both architectures. In addition, you will need other JAR files related only to J2EE, which are specified in the deployment section of the EAB documentation.

D.5.2 E-connectors

The following section contains information about IMS connect, CICS connector, and e-connector migration.

Important : Due to a limitation in the support of the CD-ROM file system (CDFS) on Windows 98, the installation of certain e-business connectors files from the CD-ROM may fail and cause one or more of the following error dialogs to be displayed, depending on the connectors you selected:

• ENCINA VAJ.RUL DELCon* copies failed
• ENCINA VAJ.RUL Deligh* copies failed
• ENCINA VAJ.RUL Drpc*
• ENCINA VAJ.RUL Transaction*
• HOD VAJ.RULcopy of file *.* failed

Any files that did not get installed are stored in a zip file (econnfix.zip) located in the root of the product CD. If you are trying to install VisualAge for Java on Windows 98 and receive any of the above messages, you must unzip econnfix.zip to the directory where the product was installed (for example, by running the command unzip econnfix.zip -d c:\Program Files\IBM\VisualAge for Java\ where c:\Program Files\IBM\VisualAge for Java\ is your product installation directory).Once these files are in place, the connectors will function correctly.

D.5.2.1 IMS Connect
Support for IMS TCP/IP OTMA Connection (IMS TOC) will be suspended in March 2001. We recommend that users migrate from IMS TOC to IMS Connect, and use it instead of IMS TOC.

IMS Connect is a separately available (it is not included with VisualAge for Java) SMP-installable IBM product that you can use in conjunction with the VisualAge for Java IMS Connector to access IMS. After you migrate from IMS TOC to IMS Connect, you can continue to use all your IMS Connector for Java programs - you do not need to change or update them.

D.5.2.2 CICS Connector
The behavior of the CICSELUW flag in the ECIInteractionSpec has been modified to correctly model the CCF Connector architecture. In previous releases, this flag defaulted to FALSE in the constructor and, regardless of whether a real Coordinator was present or not, always determined whether the LUW was extended.

In this release, the CICSELUW flag defaults to TRUE in the ECIInteractionSpec constructor if a real CCF Coordinator (for example, JavaCoordinator) is present. Unless you have specifically set this property in your old VisualAge for Java code, the CICSELUW property in your old code will now default to TRUE once you migrate it to VisualAge for Java, Version 4.0.

When no real Coordinator is present, this flag is ignored and all of your applications (both your old ones and any new ones you create in VisualAge for Java, Version 4.0) will behave as if the CICSELUW flag was FALSE. Therefore, setting this flag explicitly will have no effect unless you employ a real co-ordinator in your environment.

D.5.2.3 E-connector migration
While most previous versions of VisualAge for Java can coexist with Version 4.0, coexistence of different e-connector levels is not supported.

Migrating from VisualAge for Java, Version 3.0x or Version 3.5.x

If you have e-connectors installed, you need to follow one of the two following migration scenarios in order to successfully migrate from a Version 3.0x or Version 3.5.x of VisualAge for Java to Version 4.0.

The difference between the two migration scenarios is the stage at which the connectors are migrated.

In Scenario 1 the connectors are migrated during the initial installation process. After completing the steps in this scenario, you will have VisualAge for Java, Version 3.0x or Version 3.5.x without connectors, coexisting with VisualAge for Java, Version 4.0 with connectors.

In Scenario 2, the connectors are migrated after the initial migration process. After completing the steps in this scenario, you will have VisualAge for Java, Version 4.0 without the connectors coexisting with VisualAge for Java, Version 3.0x or Version 3.5.x with the connectors. Later, you can uninstall the Version 3.0x or Version 3.5.x connectors and install the Version 4.0 connectors.

Migration scenario 1

1. Version all the Version 3.0x or Version 3.5.x projects that contain connectors or EAB code.
2. Export these projects and related resources to a directory outside the VisualAge for Java install tree.
3. Remove all these projects from the 3.0x or 3.5.x workspace.
4. Remove all CICS, Host-On-Demand, IBM Enterprise Access Builder, Encina(R), IMS(TM) and MQSeries(R) features from the workspace
5. Exit the Version 3.0x or 3.5.x IDE.
6. Uninstall the connectors for VisualAge for Java Version 3.0x or 3.5.x by following these steps:
   1. From the Windows Start Menu, select Start > Settings > Control Panel.
   2. Double-click Add/Remove Programs. Select the Install/Uninstall tab.
   3. Select IBM Connectors.  Click Add/Remove.
   4. Confirm that you want to uninstall the connectors and their related components.
   5. Click OK in the Remove Programs window.

7. To prevent conflicts and errors with future installations of connectors, the environment variables must not contain any reference to the removed connectors. To edit the environment variables:

   Windows NT and Windows 2000

   1. From the Start menu, select Settings > Control Panel.
   2. Double-click the System icon. Select the Environment tab.
   3. In the CLASSPATH, PATH, and NLS PATH delete any references to IBM Connectors or IBM\Connectors.

   Windows 98

   1. Back up the c:\autoexec.bat file
   2. At the command prompt, enter edit c:\ autoexec.bat 
   3. In the SET CLASSPATH, SET PATH, and SET NLS PATH statement delete any references to IBM Connectors or IBM\Connectors.
8. Install VisualAge for Java, Version 4.0.
9. Add the desired CICS, Host-On-Demand, IBM Enterprise Access Builder, Encina, IMS and MQSeries features to the Version 4.0 workspace.
10. Import your projects into the Version 4.0 workspace to finish migrating your 1.1.x code. If you use the SAP R/3 Access Builder and Connector, refer to the note at the end of these steps. 
11. You can uninstall VisualAge for Java, Version 3.0x or Version 3.5.x once you have migrated any code you wish to preserve into VisualAge for Java 4.0. 

The Access Builder and Connector for SAP R/3 also provides some utility classes (for example, LogonBean) based on Swing 1.0.3. These classes are replaced by Swing 1.1- based classes. When migrating from Version 3.0x or Version 3.5.x to Version 4.0 you have to migrate your own Swing 1.0.3- based classes to the 1.1 level to continue using the utility classes provided by Access Builder and Connector for SAP R/3. You may use the IDE Fix/Migrate tool for this process.

Migration scenario 2

1. Install VisualAge for Java Version 4.0 without installing the Enterprise Access Builder for Transactions:
   1. Install VisualAge for Java, Version 4.0. Follow the on-screen instructions.
   2. In the Setup Type page, select Custom. Click Next.
   3. Select all the components that you want to install, but do not select the Transactions Access Builder. Click Next when you have finished selecting the components you want to install. If you were returned to the installation screen after attempting to install the Transactions Access Builder and do not want to install the connectors, clear the Transactions Access Builder check box, and click Next.
   4. Continue to follow the on-screen instructions to complete the installation.
      You can continue to work with the connectors for VisualAge for Java, Version 3.0x or Version 3.5.x.

When you want to install the VisualAge for Java, Version 4.0 connectors, you must either uninstall Version 3.0x/3.5.x or  uninstall the 3.0x/3.5.x connectors by following the steps outlined in Migration Scenario 1. Once you have uninstalled the Version 3.0x/3.5.x connectors or VisualAge for Java, Version 3.0x/3.5.x, you can then install the connectors for Version 4.0 by following these steps:

1. Install VisualAge for Java, Version 4.0. Follow the on-screen instructions.
2. In the Program Maintenance page, select Modify. Click Next.
3. Select Transaction Access Builder. Click Next and follow the on-screen instructions to continue installing the component.
4. Add the connectors to the VisualAge for Java IDE. Refer to the online help for information on how to perform this task.

Migrating from VisualAge for Java, Version 3.5 or Version 3.5.3

When migrating from VisualAge for Java, Version 3.5 or 3.5.3 to VisualAge for Java, Version 4.0, the IBM Connectors installed with VisualAge for Java 3.5 or 3.5.3 must first be uninstalled to ensure the correct version of the IBM Connectors are installed with VisualAge for Java 4.0.

If you attempt to install VisualAge for Java, Version 4.0 before removing the Version 3.5 or 3.5.3 IBM Connectors, a dialog will be displayed stating you must first migrate any of your applications that use the IBM Connectors before you can proceed with the Version 4.0 installation.

To migrate your applications and uninstall the Version 3.5 or 3.5.3 IBM Connectors, follow the steps below.

1. Version all the Version 3.5 or 3.5.3 projects that contain connectors or EAB code.
2. Export these projects and related resources to a directory outside the VisualAge for Java install tree.
3. Remove all these projects from the 3.5 or 3.5.3 workspace.
4. Remove all CICS, Host-On-Demand, IBM Enterprise Access Builder, Encina, IMS and MQSeries features from the workspace
5. Exit the Version 3.5 or 3.5.3 IDE.
6. Uninstall the connectors for VisualAge for Java Version 3.5 or 3.5.3 by following these steps:
   1. From the Windows Start Menu, select Start > Settings > Control Panel.
   2. Double-click Add/Remove Programs. Select the Install/Uninstall tab.
   3. Select IBM Connectors. Click Add/Remove.
   4. Confirm that you want to uninstall the connectors and their related components.
   5. Click OK in the Remove Programs window.

7. To prevent conflicts and errors with future installations of connectors, the environment variables must not contain any reference to the removed connectors. To edit the environment variables:

   Windows NT and Windows 2000

   1. From the Start menu, select Settings > Control Panel.
   2. Double-click the System icon. Select the Environment tab.
   3. In the CLASSPATH, PATH, and NLS PATH delete any references to IBM Connectors or IBM\Connectors.

   Windows 98

   1. Back up the c:\autoexec.bat file
   2. At the command prompt, enter edit c:\ autoexec.bat 
   3. In the SET CLASSPATH, SET PATH, and SET NLS PATH statement delete any references to IBM Connectors or IBM\Connectors.
8. Install VisualAge for Java, Version 4.0.
9. Add the desired CICS, Host-On-Demand, IBM Enterprise Access Builder, Encina, IMS and MQSeries features to the Version 4.0 workspace.

Uninstalling connectors

Windows NT and Windows 2000

1. From the Start menu, select Settings > Control Panel.
2. Double-click the System icon. Select the Environment tab.
3. In the CLASSPATH, PATH, and NLS PATH delete any references to IBM Connectors or IBM\Connectors.

Windows 98

1. Back up the c:\autoexec.bat file
2. At a command prompt, enter edit c:\ autoexec.bat 
3. In the SET CLASSPATH, SET PATH, and SET NLS PATH statements delete any references to IBM Connectors or IBM\Connectors.

Windows 98 only: You may have to manually delete the e-connectors directory (which, by default, is C:\IBM Connectors) after you have uninstalled VisualAge for Java. 

D.6.0 Enterprise Toolkit for AS/400 (ET/400)

D.6.1 Migrating from Version 2.0 of VisualAge for Java

Classes generated using the Enterprise Toolkit for AS/400 with VisualAge for Java, Version 2.0 are not compatible with Java classes generated using the Enterprise Toolkit for AS/400 with VisualAge for Java, Version 4.0. The reason for this incompatibility is that the Version 2.0 ET/400 Java classes used the Abstract Windowing Toolkit (AWT) and the Version 4.0 Java ET/400 classes use Java 2 SDK Swing.

However, the classes that were provided in Version 2.0 can still be found in the package com.ibm.ivj.et400.util.awt, which is provided with VisualAge for Java, Version 4.0. If you want to use the classes generated in Version 2.0 in VisualAge for Java, Version 4.0, you will have to change any references in the Version 2.0 classes from the com.ibm.ivj.et400.util package to the com.ibm.ivj.et400.util.awt package. You can do this using the Fix/Migrate SmartGuide provided with VisualAge for Java. Any errors that occur while you are migrating will be logged in the Log window. Refer to the online help for information about using this SmartGuide.

D.6.2 Migrating from Version 3.0 or 3.02 of VisualAge for Java

If you have generated Java classes using the ET/400 Convert Display File SmartGuide with VisualAge for Java, Version 3.0 or 3.02, they are not compatible with the Java classes generated using VisualAge for Java, Version 4.0 ET/400 Convert Display File SmartGuide. 

The reason for this incompatibility is that the code generated in Version 3.0 and 3.02 uses deprecated classes such as AS400SVisualTextField and Subfile classes, whereas the code generated in Version 4.0 uses JFormatted beans. All the deprecated classes can still be found in the package com.ibm.ivj.et400.util, which is included with VisualAge for Java, Version 4.0. If you want to use the classes generated in Version 3.0 or 3.02, then you must use the Fix/Migrate tool to convert all the migrated classes so they refer to the new Java 2 SDK Swing package names. This can be done be selecting the affected classes, opening the Fix/Migrate tool and selecting the Include JDK 1.2 renamed packages check box. This will automatically migrate Swing references to the Java 2 SDK. Refer to the online help for more information about this task. Any errors that occur while you are migrating will be logged in the Log window.

The Create Subfile SmartGuide is not included with VisualAge for Java, Version 4.0. It has been replaced by the more powerful DFU beans and JFormattedTable bean. If you want to continue to using the Create Subfile SmartGuide to generate code, you must continue working with an earlier (3.02 or earlier) version of VisualAge for Java. Any code generated by the Create Subfile SmartGuide in Version 3.0 or 3.02 can be migrated to Version 4.0 as the classes needed for the generated code are still supported, and can be found in the package com.ibm.ivj.et400.util. You must follow the same steps as documented in the previous paragraph to migrate your code. 

D.7.0 Enterprise Toolkit for OS/390 (ET/390)

The version of ET/390 you should use to develop OS/390 applications depends on the SDK level available on OS/390 systems or middleware applications, and the SDK level supported by VisualAge for Java (including ET/390).

On OS/390 systems and middleware applications, two SDK levels are available, as shown in the following table:

In VisualAge for Java, different versions of the product support different SDK levels, as shown in the following table:

The following sections describe the types of OS/390 applications you can develop using the different versions of ET/390.

VisualAge for Java, Versions 3.5, 3.5.3 and 4.0

ET/390 in VisualAge for Java, Versions 3.5, 3.5.3 and 4.0, is targeted primarily at the following types of applications:

• Interpreted applications running on WebSphere Application Server, Version 3.0, with SDK 1.1.8. In this environment, you can create, export, execute, and debug your applications.
• Stand-alone, interpreted applications running on OS/390 with SDK 1.3.0. In this environment, you can create, export, and execute your applications.

For interpreted applications running on WebSphere Application Server, Version 3.0, you must create your application classes so that they work with the Java APIs at the SDK 1.1.8 level. Once they are created, you can export the classes to an NFS-mounted drive, making them available on the OS/390 system. You can then execute and debug your application by clicking the Run main and Debug main menu items from the VisualAge for Java IDE.

For stand-alone, interpreted applications running on the OS/390 system, you must create your application classes so that they work with the Java APIs at the SDK 1.3.0 level. Once they are created, you can export the classes to an NFS-mounted drive, making them available on the OS/390 system. You can then execute your application by clicking the Run main menu item from the VisualAge for Java IDE.

Refer to the online help for ET/390 for details about building, exporting, executing and debugging interpreted applications.

VisualAge for Java, Version 3.02

ET/390 in VisualAge for Java, Version 3.0.2, is targeted primarily at the following types of applications:

• Interpreted and compiled transactions running on CICS Transaction Server, Version 1.3, with SDK 1.1.8 
• Compiled stored procedures running on DB2 Universal Database, Versions 5 and 6, with SDK 1.1.8
• Stand-alone, interpreted applications running on OS/390 with SDK 1.1.8

D.8.0 Enterprise Toolkit for Workstations (ET/WS)

The Enterprise Toolkit for Workstations (ET/WS) and the high-performance compiler (HPJ) are not included in this release of VisualAge for Java. If you want to keep using the Enterprise Toolkit for Workstations, you will have to continue working in a previous (3.02 or earlier) version of VisualAge for Java.

There is no new feature in VisualAge for Java, Version 4.0 that replaces the functionality previously provided by the ET/WS. Functionality similar to what was included with the ET/WS can be found in the "Just-in-time" compiler, which is part of the Java virtual machine. The Java virtual machine is included with the IBM Developer Kit, Java Technology Edition, v1.2.2, PTF 9.

The JIT compiler takes bytecode and compiles it into direct execution code, then run the programs. The bytecode is preserved, and still remain portable, however the code (after being compiled by the JIT) runs more quickly. For more information, go to the Sun(TM) web site http://java.sun.com.

D.9.0 External Version Control 

When you migrate from VisualAge for Java, Version 3.5 to Version 4.0, you can continue to use External Version Control on projects you were using it with in version 3.5. If the External Version Control icons do not appear at first, perform the Tools > External Version Control > Refresh Project action and they should appear.

You may need to restart the Remote Access to Tools API, which you can do from the Options dialog. Select Windows > Option to open the Options dialog. Select Remote Access to Tools API and click the Remote Access to Tools API button to start it.

D.10.0 IDL Development environment

If you have been using the IDL-to-Java compiler provided by either the IBM Component Broker Series or the CICS IIOP Server Support feature, you will need to manually define the IDL-to-Java compiler invocation string in the following dialogs:

The IDL-to-Java Compile page of the Options dialog (accessible from the Windows menu). Modify the string in the Command field.

The Change IDL-to-Java Compile Options dialog. In the IDL page, select IDL > Change Compile Options.  Modify the string in the Command field.

For more information on modifying the string and opening the IDL page, refer to the online documentation for the IDL Development Environment.

Please see section 1.0 of Part D for information about CICS IIOP support.

D.11.0 Integrated Development Environment

The JDK level has changed since Version 3.5 (it is now JDK 1.2.2 PTF 9).

If you modified the VisualAge for Java, Version 3.5 Java Class Library by replacing any packages or classes in it or by adding any packages and classes to it, these modifications will not automatically be reproduced in the Version 4.0 Java Class Library after migration; you will have to manually modify the Java Class Libary again. 

The Java Class Library was entirely read-only in VisualAge for Java before Version 3.5.

D.12.0 JSP/Servlet Development Environment

If you are migrating from an earlier version of VisualAge for Java to VisualAge for Java, Version 4.0, the following two files will be overwritten with new versions, and any changes you may have made to them will be lost:

• ide\project_resources\IBM WebSphere Test Environment\hosts\default_host\default_app\servlets\default_app.webapp
• ide\project_resources\IBM WebSphere Test Environment\properties\default.servlet_engine

You may want to make backup copies of these files before you migrate to Version 4.0, and add your old changes to the new versions of the files after you have finished migrating to VisualAge for Java, Version 4.0. You should not simply copy the old versions of the files over the new versions of them because the new versions contain  information that is not in the old versions of these files.

D.13.0 Migration Assistant for ActiveX

The Migration Assistant for ActiveX is not included in this release of VisualAge for Java. You can migrate the code you created with the Migration Assistant in previous (3.02 or earlier) versions of VisualAge for Java to Version 4.0 by following the general migration steps covered in Part B. There is no new feature in VisualAge for Java, Version 4.0 that replaces that functionality previously provided by the Migration Assistant for ActiveX. 

D.14.0 Persistence Builder  

Note: You do not need to apply Persistence Builder FixPak 3.5.1 or FixPak 3.5.2 (available from VADD) to VisualAge for Java, Version 4.0. These fixes have already been incorporated into the Version 4.0 code.

You must use VisualAge for Java to regenerate code from any previous releases of Persistence Builder.

D.14.1 Upgrading specifically from Version 2.0

The following migration issues pertain to you if you are upgrading from VisualAge for Java, Version 2.0:

1. Version all of your projects pertaining to your Persistence Builder applications.
2. After you have migrated your code to VisualAge for Java, Version 4.0, add your projects to the Version 4.0 workspace. You will encounter problems with the services classes because certain converters are no longer included with VisualAge for Java. To correct these problems, generate the "Data Service Classes and Interfaces" for your object model and the problems will be resolved by the code generation services. 
3. The superclass for converters has been moved to the project: VisualAge Persistence Common Runtime. You have to change the superclass of your composers to: com.ibm.vap.converters.VapAbstractConverter.
4. The composer superclass has also been moved to a new project. You will have to change the superclass of your composers to: com.ibm.vap.composers.VapAttributeComposer

For more information on performing these steps, refer to the online documentation for the Persistence Builder.

D.14.2 Upgrading from all previous versions (including Version 2.0) 

When you load available models, maps, or schemas from the Model Browsers, the internals of the metadata is changed. You cannot then reliably load the metadata into a workspace that is at a lower release level than Version 4.0. The model, map, or schema will appear dirty. Save the model, map, or schema.

Note: The following information only applies if you are migrating from Version 2.0 or 3.0x of VisualAge for Java. It does not apply if you are migrating from Version 3.5.

Classes created in previous releases for custom queries will have errors. The custom query framework now throws a Throwable object, to enable you to catch exceptions that occur when the custom query is called. As a result, any pre-existing custom queries will show up in the IDE as containing an unresolved error (with a red X), because they are not handling the thrown exception. To correct this situation, throw the exception from your custom query or catch the exception.

You can find more information on dealing with errors in the Visual for Java online help.

Changes to run-time support 
The name of the project that contains the Persistence Builder run-time's prerequisite javax packages has changed names. This may require you to recalculate the project path for program elements that use Persistence Builder, as follows:

1. Select the class.
2. From the Selected menu or from the class's pop-up menu, select Run > Check Class Path.
3. Click the Compute now button near the Project path check box.
4. To save the recalculated path setting, select the Save in repository (as default) check box. If you save the setting, a new edition of the class will be created.
5. Select OK.

D.15.0 RMI Access Builder

The RMI Access Builder is not included with VisualAge for Java, Version 4.0. You can import your old generated classes and run-time library projects into the Version 4.0 workspace, but you will not be able to run the Remote Object Invocation Manager (ROIM) as it is not included. You should be familiar with the new Java 2 Platform security model and how its limitations may affect your RMI Access Builder applications.

Adding the RMI Access Builder run-time library to your workspace
You must import the RMI Access Builder run-time library from Version 3.0x of VisualAge for Java, and add it to your workspace. You cannot run your RMI Access Builder applications in VisualAge for Java, Version 4.0 without this.

1. Select File > Import. 
2. Select the Jar file radio button. 
3. Enter the path and name of the run-time, which is x:\IBMJava\eab\runtime\ivjrmi.zip, where x:\IBMJava\ is your Version 3.0x installation directory.
4. Select the .class check box. If the resource check box is selected, clear it. 
5. In the Project field, type IBM Enterprise RMI Access Builder Library.
6. Click Finish. 
7. If the IBM Enterprise RMI Access Builder Libary project does not already exist, you will be prompted to create it.
8. Ensure the project is added to your workspace. If it does not appear in your workspace, go to the Repository Explorer and select to add it.

Migrating your RMI Access Builder applications
If your RMI applications are not already in the Version 4.0 repository, follow these steps to import them into the workspace.

1. Version your RMI Access Builder classes and run-time library projects in your old version of VisualAge for Java. If you wish, you can maintain the classes simply as .java classes. 
2. Import them into the VisualAge for Java, Version 4.0 IDE by following these steps:
   • In the Workbench, select File > Import.
   • Select the Directory or Repository radio button.
   • Enter the name the directory or repository you have stored your applications in.
   • Select the type of files you want to import and import them. 
   • If you have not already done so, copy over any project resources associated with your RMI project into the Version 4.0 project resources directory. Create an open edition of the project and version it. In Version 4.0 of VisualAge for Java, your project resources are automatically versioned when you version the project they are contained in.

If you wish to run any of your server objects, you will first have to create a server mainline. For example, if you have a Sever-Side Server Proxy: Reverse1S, and ServerObj2S, you can write a server main to instantiate the server objects:

import...;
public class Servermain {
    public static void main(String arg[]) {
        try{
            Reverse1S myserver = new Reverse1S();
            ServerOvj2S obj2 = new ServerObj2S();
}
catch (Exception e) {
    e.printStackTrace();
    }
System.out.print ln("Server Objects Started.");
    }
}

As well, due to tighter security restrictions, you will have to define a policy file for servers and clients. For example, you could have a policy file called "My policy":

grant {
//Grant all permissions
permission java.security.AllPermission;
};

Or you could have a policy that allows anyone to listen on unprivileged ports:

grant { 
// allows anyone to listen on un-privileged ports
permission java.net.SocketPermission "localhost:1024-", "listen";
permission java.net.SocketPermission "localhost:1024-", "resolve"; 
permission java.net.SocketPermission "pathfinder:1000-4000", "listen";
permission java.net.SocketPermission "pathfinder:1000-4000", "connect";
permission java.net.SocketPermission "pathfinder:1000-4000", "resolve";
};

where pathfinder is the user's machine name.

When you launch your client, you will have to run a command similar to the following in order to properly launch the client:

java-Djava.security.policy=<myPolicy.file> 

For example if you are running main() within the IDE you would specify java.security.policy= in the Properties section when selecting the "run with" menu item.

You should maintain your code on your previous version of VisualAge for Java so you can continue to develop it or regenerate it.

D.16.0 Visual Composition Editor

You must use the IDE migration tool to repair metadata for visual composites. Refer to the online help topic "Fix/migrate guidelines for class or package references" for information on how to repair broken class or package references due to migration of classes to the J2SDK v.1.2.2 or the renaming of user-defined program elements.

VisualAge for Java does not keep track of the dependencies between the classes being migrated. Classes which are referenced in a class and have not been migrated yet can have problems with class initialization or may introspect incorrectly.

Any errors that occur while you are migrating will be logged in the Log window. For example, suppose that the following message appears in the Log window while you are migrating a class called Sample.Samp:

Migrating class: Sample.Samp

Could not migrate Class:<Pkg>X::Y

Sample.Samp references X::Y; VisualAge for Java encountered problems in loading class Y. Either Y has not been migrated yet, or it is missing. (In the Visual Composition Editor, class Y appears as a problem class.) To fix this, migrate Y first or, if Y is missing, find a replacement class for Y. In extreme cases, you may have to open Samp or Y in your previous version of VisualAge for Java and reset beans or properties so that migration can continue.

In some cases, opening the class in the VCE will result in the Resolve Class References dialog opening. This dialog shows the problem classes that exist in the VCE. The Unresolved class reference column in the dialog specifies the class that VisualAge for Java used as a temporary replacement. This appears as follows:

com.ibm.uvm.abt.edit.DeletedClassView(X)

The X that appears in parentheses is the name of the problem class. It is likely that X was migrated correctly after the current class. To fix this, select the row to be fixed and click the Replace button. In the "Choose a valid class" dialog, select the class X as the replacement class. Do this for all the unresolved classes and then click OK.

D.17.0 Servlet Builder and Servlet Launcher

The Servlet Builder and Servlet Launcher are not included with VisualAge for Java, Version 4.0. A Servlet Builder run-time JAR file that is compatible with Version 4.0 is available at http://www.ibm.com/vadd. Follow the "Download" link. 

There is no new feature in VisualAge for Java, Version 4.0 that directly replaces the functionality previously provided by Servlet Launcher. To test your servlets, you can either launch them explicitly by entering the URL in a web browser, or by writing HTML or JSP pages to invoke them. For development of new servlets, you can use the new Servlet SmartGuide, which will also create an HTML page which will launch your servlet.

You have two options for using the run-time file:

• You do not import your application into VisualAge for Java, Version 4.0, but upgrade it to the J2SDK v1.2.2 using a migration utility, compile it, and deploy it on the Websphere Application server. This option is covered in scenario 1.
• You import your application into VisualAge for Java, Version 4.0, upgrade it to the J2SDK v1.2.2 using the Fix/Migrate SmartGuide, manually modify it, compile it in the WebSphere Unit Test Environment, export it, and deploy it on the Websphere Application server. This option is covered in scenario 2.

Scenario 1

In this scenario, edit the code in your previous edition of VisualAge for Java, using the Servlet Builder before you export it. 

1. Export your application code from your previous version of VisualAge for Java to a directory or repository outside the installation tree. 
2. Use a utility such as WoodenChair's "Utility+ JDK Standard Edition" to migrate your java code (rename packages, handle changes in dependencies etc) to the J2SDK v1.2.2. To find out more about this product and its capabilities, go to WoodenChair's Web site at http://www.woodenchair.com/
3. Compile each of the .java class file and the JAR files using the J2SDK v1.2.2. The Servlet Builder 4.0 run-time JAR file must be in the compile classpath. 
4. Deploy your code to the Websphere Application Server. The Servlet Builder 4.0 run-time JAR file must be in the WebSphere Application Server document root directory or the server's classpath.
5. If you need to make additional modifications, return to step 1. Repeat the other steps as necessary.

Scenario 2

In this scenario, you edit your Servlet Builder code within VisualAge for Java, testing it in the WebSphere Unit Test Environment.

Follow these steps:

1. Import the Servlet Builder 4.0 run-time JAR file into VisualAge for Java, Version 4.0.
2. Import the project you want to work with into the VisualAge for Java, Version 4.0 workspace.
3. Use the Fix/Migrate SmartGuide to repair any broken references in the code.
4. Manually modify the code as desired, and compile and test it within the WebSphere Unit Test Environment.
5. Export the project to a JAR file.
6. Deploy your code to the Websphere Application Server. The Servlet Builder 4.0 run-time JAR file must be in the WebSphere Application Server document root directory or the server's classpath.

You can find more information on how to perform these steps in the VisualAge for Java online help.

The Servlet Builder feature, which was available in previous releases of VisualAge for Java, created servlets that directly generated an HTML user interface. This capability is useful for rapid application development, but has the drawback that it combines the business logic of the application with its user interface. If a change to the user interface is desired then the servlet must be modified. To make maintenance easier, it would be preferable to use JavaServer Pages (TM) (JSP) technology to separate the user interface from the business logic.

A JSP page is an HTML template that includes dynamically generated content. A JSP page can be modified using HTML editing tools like the PageDesigner feature in IBM WebSphere Studio. In IBM's WebSphere programming model, servlets are still used for Web interaction, but they delegate business logic to Java beans and the user interface to JSP. In this programming model, servlets and beans are developed using Java tools and JSP pages are developed using HTML tools.

This separation of the business logic and user interface allows you to assign development responsibilities to the team members who have the appropriate skills and tools, and it leads to easier maintenance.

In accordance with the WebSphere programming model, the function that was provided by the Servlet Builder has been replaced by Java tools in VisualAge for Java and by HTML tools in WebSphere Studio. VisualAge for Java, Version 4.0 provides a new SmartGuide (wizard) to get you started creating Web applications that follow the WebSphere model. You can use the Create Servlet SmartGuide to generate a servlet that invokes a bean for the business logic and a JSP page for the user interface. The SmartGuide also generates an HTML form that you can use to test the servlet. The servlet can be immediately tested in the WebSphere Test Environment of VisualAge for Java, and then refined in the IDE. The JSP and HTML files can be further edited using WebSphere Studio or another HTML tool.

The Create Servlet SmartGuide is modeled on the JavaBean wizard in WebSphere Studio. It also includes additional features that are required by Java programmers. If you already use WebSphere Studio for your HTML development, you will find that the SmartGuide simplifies the flow of work between that tool and VisualAge for Java. The development steps are:

1. Create a Java bean for the business logic of the application.
2. Run the SmartGuide to generate the servlet, JSP, and HTML form.
3. Test the servlet in VisualAge for Java
4. Continue development of the servlet in VisualAge for Java.
5. Refine the JSP and HTML files in WebSphere Studio or equivalent tool. 

D.18.0 Swing classes

Swing classes are in a different package in the J2SDK v1.2.2 than they were for the JDK v1.1.x. If you need to update references to the swing classes you can use the Fix/Migrate SmartGuide.

To migrate your applications, you must select the affected classes and packages, open the Fix/Migrate SmartGuide (by right-clicking on the package or class, then selecting Reorganize > Fix/Migrate), and select the Include JDK1.2 renamed packages check box to automatically migrate Swing references to the J2SDK v1.2.2. This will add the appropriate From/To entries for Swing. Any errors that occur while you are migrating will be logged in the Log window. 

Refer to the online help topics:"Fix/migrate guidelines for class or package references" and "Repairing class or package references" for information on how to properly migrate your applications.  

You may not be able to use the Visual Composition Editor to migrate all Swing properties from JDK 1.1.7 to Java 2 because of serialization changes between Version 1.03 and 1.1.1 of Swing. After you have migrated your code to VisualAge for Java, Version 4.0, you may not be able to open some Swing application classes in the VCE. This will only occur when you have used the VCE property sheet to set the properties of a Javabean to a Swing object.

To work around this problem, follow these steps:

1. Re-open the class in your previous version of VisualAge for Java (in the VCE).
2. In the class' property sheet, click the Reset button. A window opens, listing all the bean properties you have modified. Any properties that have been set to Swing objects should be reset to their default setting.
3. Save the class and re-import it into the Version 4.0 IDE.

D.19.0 XMI Toolkit  

For information on migrating from the Beta 1.2 version of the XMI Toolkit, please refer to the XMI Toolkit release notes.

If you have used any release other than the 3.5 Version of the XMI Toolkit (for example, a technical preview, an alphaWorks release, or an earlier Beta), you should uninstall it and remove the environment updates performed during installation before using this release of the XMI Toolkit. Migration instructions are provided only for the 1.2 Release.

Generated zip files and XMI files from both the Beta 1.2 and pre-Beta 1.2 releases are not compatible with any 3.5 or 3.5.x release of the XMI Toolkit.

Part E: General information

E.1.0 Dealing with project resources and resource management

In Version 4.0 of VisualAge for Java, you can version and release your project resource files. Refer to the IDE and team online help for more information about this new feature.

If you have migrated projects from Version 2.0 or 3.0x of VisualAge for Java to Version 4.0 of VisualAge for Java, you can follow these steps after you have completed the migration process. You do not have to perform them immediately after you have finished migration, but until you do, your project resources are not versioned in the repository. 
Note: You do not need to perform these steps if you migrated your projects from Version 3.5.

1. Ensure that you have copied all your old project resources into the Version 4.0 project resources directory.
2. Add the projects into your workspace from the repository.
3. Create a new open edition of each project. You cannot add new resources to your project until you have created an open edition of it.
4. Version the project, which releases all the resources. 

If you are planning on working in a team environment with the Enterprise Edition of VisualAge for Java, you must use EMSRV, Version 7.1. 

E.2.0 Migrating from OS/2 and AIX

OS/2 and AIX are not supported as development platforms for VisualAge for Java, Version 4.0. You can only install VisualAge for Java, Version 4.0 as a client on Windows NT, Windows 98, and Windows 2000. If you wish to use Version 4.0 with your OS/2 and AIX repository, you must connect to that repository from the Version 4.0 IDE. Refer to the online help for information on how to perform this task. 

If you have written any platform-specific code, you will have to rewrite it so it works on Windows.

Two scenarios 

Note: You cannot have AIX and Windows on the same machine, so the steps in Scenario 1 are only applicable for OS/2.

Scenario 1

If your ivj.dat OS/2 repository is on the same machine as the Windows client:

1. Back up your old ivj.dat. The repository will be restored later, after you install Windows 98, Windows NT, or Windows 2000 and VisualAge for Java, Version 4.0. If the repository resides on a FAT partition managed by OS/2 and you plan to install Windows 98/NT/2000 on the same machine and retain the FAT partition, you do not have to back up the repository. We recommend, however, that you do back up the repository, in case you encounter any problems when you install Windows. 
2. Install Windows 98, Windows NT, or Windows 2000. If your machine is running OS/2,Windows may be installed on the same machine using the dual-boot option to retain the existing OS/2 installation. 
3. Install VisualAge for Java, Version 4.0. 
4. Restore the repository to a partition on a local hard disk that is accessible by the new Windows installation. If the repository previously resided on a FAT partition managed by OS/2 and that partition still exists, you will not need to restore the repository. 
5. Connect to your old repository (Enterprise) or import from your old repository (Professional). You should copy over any old project resources to your Version 4.0 project resources directory.

Scenario 2

If your ivj.dat OS/2 or AIX repository is on a different machine than the Windows client:

1. Your OS/2 or AIX machine must be running the EMSRV repository program (Version 7.1) provided with VisualAge for Java, Version 4.0. You can connect to repositories that were used with Version 3.02 or earlier of VisualAge for Java, but you must have Version 7.1 of EMSRV installed in order to connect to an old repository from Version 4.0.
2. The Windows client, on which you are running VisualAge for Java, Version 4.0 connects to OS/2 or AIX server as required. You should copy over any old project resources to your Version 4.0 project resources directory.

E.3.0 New security restrictions in J2SDK v1.2.2  

Due to a change in the security policy for applets running on the Java 2 Platform v1.2.2, applets can no longer access local resources. 

Several samples that were available with previous versions of VisualAge for Java are not included with VisualAge for Java, Version 4.0 because of this restriction. As well, some samples that are included can only be run as applications, otherwise, they will not work properly. Please refer to the online documentation for instructions on how to properly run samples.

You can change the default security policies by creating your own java.policy file and launching the AppletViewer with the following parameter: -Djava.security.policy=someURL

where someURL is the location of your new policy file. For more details on general security in Java, please refer to http://java.sun.com/security For specific information on security in Java 2 and policy file syntax, please refer to http://java.sun.com/products/jdk/1.2/docs/guide/security

E.4.0 New External Version control tool (replaces External SCM tool)

The External Version Control tool, introduced in VisualAge for Java, Version 3.5, enables you to connect to external source code management (SCM) providers such as ClearCase, PVCS Version Manager, TeamConnection(TM), and SourceSafe(TM) from VisualAge for Java. With this tool, you can add classes to your SCM provider, check classes and resources files in and out of the SCM system, and import the most recently checked-in version of a class from the SCM system.

This tool replaces the old External SCM tool and provides increased functionality.

E.5.0 Working with third-party ORBs in VisualAge for Java

You can work with third-party Object Request Brokers (ORBs) in VisualAge for Java if they are compatible with the J2SDK v1.2.2. You must import the ORB classes into the IDE before you can work with them.

When you import Java classes into the IDE, you can add ORB extension classes to the Java Class Libraries. You may also replace some of the ORB extension classes found in the existing Java Class Libraries as long as they are not part of the J2SDK v1.2.2 core classes.

You can find an article that contains more detail about working with third-party ORBs in Version 3.5.x on the Web at:

http://www.ibm.com/software/vadd/Data/Document2175

This article contains comprehensive information about developing Common Object Request Broker Architecture (CORBA) and ORB applications in VisualAge for Java.

Certain Java Class Library classes may be replaced when a third-party ORB is imported into VisualAge for Java. Patch 2 for Version 3.5 fixes a bug that erroneously allowed you to import certain immutable classes (those contained in mutable packages) into VisualAge for Java. After you apply Patch 2 to VisualAge for Java, Version 3.5, you may receive new or additional warnings in the Log window when you import a third-party ORB. These warnings occur because you cannot import immutable classes into VisualAge for Java after Patch 2 is applied, however, they can be ignored.

E.6.0 Contents of the Additional Features CD

The VisualAge for Java Additional Features CD contains the following:

• IBM Connectors and Tools for J2EE(TM) - Beta
• Team Server
• Distributable Run-Times
• IBM Developer Kit 1.2.2
• Merant DataDirect SequeLink Java Edition Version 5.1 for Oracle and Microsoft SQLServer
• Distributed Debugger
• Technology Previews
  • IBM Stored Procedure Integration Tool for Enterprise JavaBeans
  • XMI Bridge
• Printable Documentation
• Help system troubleshooting guide
• Resources and backup copy of the repository

The Installation and Migration guide and product README are on both the Additional Features CD and the main product CD.

Note: The Additional Features CD is only included with VisualAge for Java, Enterprise Edition. The following items, however, are included with VisualAge for Java, Professional Edition on the product CD:

• Distributable Run-Times
• IBM Developer Kit 1.2.2
• Distributed Debugger
• Printable Documentation
• Help system troubleshooting guide
• Resources and backup copy of the repository

The Installation and Migration guide and product README are on the VisualAge for Java, Professional Edition product CD.

IBM J2EE Connectors and Tools for J2EE(TM) - Beta

This release of VisualAge for Java includes a beta version of several components of the Java 2 Platform, Enterprise Edition (J2EE) which Sun Microsystems Inc. has not officially released. They are the following:

• J2EE Connector for CICS
• J2EE Connector for SAP R/3 
• J2EE Connector for PeopleSoft 
• J2EE Connector for J.D. Edwards OneWorld
• J2EE Connector for Oracle Applications/Financials
• J2EE Connector for IMS (available from http://www.ibm.com/vadd)
• J2EE Connector for HOD (available from http://www.ibm.com/vadd)
• Tools to import data structures found on JD Edwards, PeopleSoft and Oracle Applications servers 
• Tools to generate J2EE-compliant records
• Tools to create and edit J2EE-compliant Commands
• Tools to create and edit J2EE-compliant EAB session beans
• Tools to migrate existing EAB applications to the J2EE-based architecture. These tools migrate records, Commands and Navigators. 

The beta components are located in the extras\BetaJ2EEConnectors subdirectory. If you want to use these beta components, refer to the README file in the BetaJ2EEConnectors subdirectory for installation instructions for the components.

Note: The components shipped with VisualAge for Java, Version 4.0 are only supported on Windows NT and Windows 2000. Not all the J2EE run-time files are supported on Windows 2000. For more information on the J2EE components, refer to the Enterprise Access Beans online help and release notes.

Team Server (EMSRV) 

The TeamServer directory on the Additional Features CD contains the EMSRV repository server program and the "Server setup and administration" file (emsrv71.htm or emsrv70.htm for all languages other than English). Refer to Part C for instructions on installing EMSRV and the  "Server setup and administration" file (located in TeamServer\docs) for information on starting the server. 

Distributable Run-Times

When you export and deploy an applet or application built with VisualAge for Java, you also need to deploy the run-time library for the features with which you created the code, if any, and put the deployed run-time JAR file or Zip file on your class path.

In general, the JAR files are compressed and are for use when running applets off of a server. The Zip files are uncompressed and should be placed on the CLASSPATH of the deployment machine for running applications locally.

The VisualAge for Java run-time libraries are contained in the extras/runtime30 and extras/runtime35 directories. Depending on which features of VisualAge for Java you have installed, some or all runtime libraries are also provided in the eab/runtime35 or runtime30 directory of your install image. Note: The J2EE run-time libraries are not included on the Additional Features CD. The run-time files for the J2EE connectors will be located in eab\runtime 35 and IBM Connectors\classes after you have installed the beta components.  

For more information about installing and using run-time libraries, refer to the online help.

IBM Developer Kit 1.2.2 (for Windows)

The IBM Developer Kit, Java Technology Edition, v 1.2.2, PTF 9, located in the IBM Developer Kit directory, is a Java development environment that helps you develop stand-alone Java applications and applets that conform to the 100% Pure Java specification.

It includes tools for developing Java applications and applets, some of which are: 

Java Compiler 

Converts Java source code into Java bytecodes that can later be run with the Java Interpreter.

Java Class Libraries 

Provide all the standard Java classes, allowing your Java applications to create and extend existing Java objects. 

Java Applet Viewer 

Provides a way to run an applet from the command prompt. 

Java Documentation Generator 

Generates the Toolkit's Application Programming Interface (API) documentation from properly commented Java programs. 

To install the the IBM Developer Kit, run install.exe from the IBM Developer Kit directory. For more detailed information about the IBM Developer Kit, refer to the README file in the IBM Developer Kit directory.

Merant DataDirect SequeLink Java Edition Version 5.1 for Oracle and Microsoft SQLServer

VisualAge for Java, Version 4.0 supports Merant's DataDirect SequeLink Java Edition Version 5.1 driver for Microsoft SQL Server and Oracle database access.

Note: The Merant DataDirect SequeLink Java Edition Version 5.1 server shipped with VisualAge for Java, Version 4.0 is only supported on Windows NT and Windows 2000.

SequeLink is a middle-ware data-access component that provides data connectivity for the latest JDBC standards to a variety of databases such as Oracle, Microsoft SQL server and also mainframe data. SequeLink's client component is database independent; therefore no changes are necessary if new databases are added to the infrastructure. A branded SequeLink client is included with the WebSphere Test Environment.

Note: Because the SequeLink client is branded, you can only communicate with the Merant DataDirect SequeLink Java Edition Version 5.1 server while using the client in conjunction with the WebSphere Test Environment or the Websphere Application Server. Merant DataDirect SequeLink Java Edition Version 5.1 server is not a fully licensed server; you cannot use it for any purpose other than working with the branded Sequelink client. If you have a fully licensed Merant DataDirect SequeLink Java Edition Version 5.1 server, the branded Sequelink client will also work with that.

The corresponding SequeLink server is available as a non-keyed (that is, you will not be prompted for a registration key when you install it) installation. The server can be installed from the Merant\SequeLinkServer subdirectory on the Additional Features CD.

How the driver should be set up and installed varies depending on the component you intend to use them with. Please refer to the following release notes for specific installation and setup information (including information on configuring the SequeLink client included with the WebSphere Test Environment):

• Enterprise JavaBeans (EJB)
• Persistence Builder
• Data Access Beans

Distributed Debugger

If you intend to debug any classes developed outside the VisualAge for Java IDE or debug programs running on a separate machine, you should install the Distributed Debugger.

The Distributed Debugger is supported on the following operating systems: Windows, AIX, OS/2, HP-UX, Solaris, Linux, and Linux/390. All Debugger files are in the Debugger directory on the Additional Features CD. Refer to Part B, Section 2.1.1.1. for installation instructions.  

Technology Previews

The Additional Features CD contains two Technology Previews: the IBM Stored Procedure Integration Tool for Enterprise JavaBeans and the XMI Bridge.

IBM Stored Procedure Integration Tool for Enterprise JavaBeans

You can use the IBM Stored Procedure Integration Tool for Enterprise JavaBeans (SP integration tool for EJBs) to enhance your stateless session EJBs by adding methods that call database stored procedures. Using the Create Stored Procedure Call Method SmartGuide you can define your methods, and then generate the new method in your stateless session bean.

By using the SP integration tool for EJBs, you can leverage business logic contained in your existing stored procedures within an EJB environment. You can minimize your EJB development effort and avoid redundant business logic in your EJB server and database management system (DBMS). Also, because stored procedures can help reduce network traffic between the EJB server and the DBMS, you can improve the performance of your production applications.

The SP integration tool for EJBs is located in the extras\spt subdirectory. Refer to the EJB_SPTool.PDF file in the spt directory for more information about installing and using the technical preview. After you install the SP integration tool for EJBs, the EJB_SPTool.PDF file will also be located in the following directory: x:\ibmvjava\ide\tools\com-ibm-ivj-sptools where x:\ibmvjava is your product installation directory.

XMI bridge

The XMI bridge is a technical preview for Persistence Builder and Enterprise Java Beans which enables you to import a Rational Rose model file or XMI document into a Persistence Builder model or EJB Group.

The XMI bridge is located in the extras\xmib directory. You must have added the XMI Toolkit to the workspace before you can work with the XMI bridge. Refer to the README file in the xmib directory for more information about installing and using the technical preview.

Printable Documentation

Some of the online help has been grouped into PDF documents which you can view and print using Adobe Acrobat Reader (available from http://www.adobe.com/). Not all PDFs are available in all languages. The PDF files are available from the pdf directory. 

See the PDF Index (in the Getting Started guide) for information on what each PDF file contains.

Help system troubleshooting guide

Refer to the help system troubleshooting guide for information about recovering from help failures. The guide is located in the Troubleshoot directory on the Additional Features CD and is available in all languages.

Repository and resources

The ivj40 directory contains two zip files: ide.zip and wte_resources.zip. The ide.zip file contains a copy of the repository (ivj.dat), the project resources directory (ivj.dat.pr), and the workspace file (ide.icx). The wte_resources.zip files contains a backup copy of the project resources for the WTE feature.

Appendix A: A comparison of data access components 

Provided below is a comparison of the Data Access Builder, Data Access beans and Persistence Builder. A brief description of the EJB Development Environment is included, but this component is not included in the comparison.

The Data Access beans feature offers a rapid way to access relational data visually. This feature is intended for use with applications where a reusable object model is not required. You can use the Data Access beans to help you create visual applications that need a direct view of tables inside the target database. You can also incorporate the Data Access beans into your code manually.

The EJB Development Environment enables you to develop beans that implement Sun Microsystems' Enterprise JavaBeans (EJB) programming specifications. The EJB Development Environment provides all of the necessary run-time support for the IBM WebSphere Application Server. An incremental consistency checker ensures that enterprise beans conform to the EJB programming specification and indicates whether changes are needed to fix inconsistencies. Refer to the online help for more information on the EJB Development Environment.

The Persistence Builder provides scaleable persistence support for object models and is a first step towards EJB for many customers. Applications built using Persistence Builder can focus on the optimal, reusable object model and quickly map it to any supported relational database. Persistence Builder supports both bottom-up (Schema to Object), and top-down (Object to Schema) mapping. This feature maps objects, and relationships between objects, to data stored in relational databases.

The rest of this document describes the differences between the data access features - Data Access beans, Data Access Builder, and Persistence Builder.

Implementation details of each feature are not included here. The online documentation covers the additional functionality that the Persistence Builder and Data Access beans offer, such as relationships, visual palette parts, and advanced transactional capability, and the SQL Assist SmartGuide.

The list of core functions listed below represent an overview of Data Access Builder's main capabilities. Each core function has been implemented in different ways by each component.

Part 1: Object to Relational Mapping features

Database Schema to Object Mapping

• Section 1.0 - Using tables and views 
• Section 2.0 - Using custom queries 
• Section 3.0 - Using stored procedures 

Code Generation

• Section 4.0 - CRUD Operations on objects and stored procedure support
• Section 5.0 - Custom query support

Part 2: Run-time features

• Section 1.0 - Datastore/Transactional support
• Section 2.0 - API LOB support
• Section 3.0 - Quick forms
• Section 4.0 - Current Date/Time/Timestamp support 
• Section 5.0 - Cursor support 
• Section 6.0 - Asynchronous Execution Concurrency issues

Part 3: Data Access beans features

Implementations of the functions are explained in the following pages. The Data Access Builder and Persistence Builder functions are all compared consecutively, whereas the comparable Data Access beans functions (for mapping) are listed at the end of this section.

Part 1: Object to Relational Mapping features

Database Schema to Object Mapping

1.0 Database Schema to Object Mapping Using Tables and Views

In Data Access Builder

Note: All Data Access Builder steps must be performed in a previous (3.02 or earler( version of VisualAge for Java that includes the Data Access Builder. 

In the Map Schema SmartGuide, select the DB2 or ODBC connection, then select the Select database tables or view radio button. Click Next. The following page opens, showing a list of tables:

Select the tables you want to work with and click Finish. 1 to 1 object mappings between these tables and the resulting objects will be created. The Data Access Builder window shows the column to attribute mapping that automatically occurred.

In Persistence Builder

In the Schema Browser, select Schemas > Import Schema from Database. Enter the connection information. The Select Tables dialog opens.

Select the desired tables or views, and click OK. The Schema Browser now contains the new schema and lists its tables, columns, and keys.

Select Schemas > Generate Model from Schema. This generates a simple one to one business model.

2.0 Database Schema to Object Mapping using Custom Queries

In Data Access Builder

Enter your query and click Finish. The example above shows a two table join query. Queries with parameter values are also supported.

The resulting object contains the attributes from both tables as shown below:

In Persistence Builder

1. Import the schema using the Schema Browser.
2. Open the model browser and create the object model the tables will be mapped to.
3. Once the model is complete, open the Map browser, and create a new datastore map. Select the schema and model already created.
4. Select a model class, and add a cluster map by selecting New Table Map > Add Cluster Map With No Inheritance.
5. To add more join tables, select New Table Map > Add secondary table map menu item. Once the tables have been added, map the individual attributes by opening the property map editor on each table map.
   
6. Map each attribute to the tables columns, leaving the other tables columns unmapped. The Map browser will show the property maps corresponding to each table in the fourth pane.

3.0 Database Schema to Object Mapping using Stored Procedures

In Data Access Builder

In the Map Schema SmartGuide, select the DB2 or ODBC connection, then select the Stored procedure result set radio button. The Stored Procedure page opens, showing a list of stored procedures. Enter a name for the mapping, select the stored procedure and click Finish.

The resulting object contains attributes mapped to the stored procedure's result columns. The queries or stored procedures for the CRUD operations are not pre-defined for this type of mapping.

In Persistence Builder

The Persistence Builder does not have any tools that support stored procedure mapping. You can generate a "Stub Schema" which creates skeleton service classes, where you must supply the supporting code. The all-instances method might appear like the following:

/**
* Return a query spec for the query called allInstances
* @return java.util.Vector
*/

public java.util.Vector allInstancesQuery() {
   Vector aSpecArray = new Vector();
     DatabaseCompoundType aCompoundType;
        DatabaseQuerySpec spec = new DatabaseCallableQuerySpec("{call getAllEmp ()}");
      aCompoundType = new DatabaseCompoundType();
        aCompoundType.addField((DatabaseTypeField)(new                              com.ibm.ivj.db.base.DatabaseDecimalField("COMM")).setAttributes(9,2,3,false));

aCompoundType.addField((DatabaseTypeField)(new com.ibm.ivj.db.base.DatabaseIntegerField("EMPNO")).setAttributes(4,0,4,false));

aCompoundType.addField((DatabaseTypeField)(new com.ibm.ivj.db.base.DatabaseDecimalField("SAL")).setAttributes(9,2,3,false));

aCompoundType.addField((DatabaseTypeField)(new com.ibm.ivj.db.base.DatabaseIntegerField("DEPTNO")).setAttributes(2,0,4,false));

aCompoundType.addField((DatabaseTypeField)(new com.ibm.ivj.db.base.DatabaseStringField("ENAME")).setAttributes(10,0,12,false));

((DatabaseSelectQuerySpec)spec).setOutputShape(aCompoundType);

aSpecArray.addElement(spec);
return aSpecArray;
}

4.0 CRUD Operations on Objects

Data Access Builder

The basic CRUD operations (Create, Retrieve, Update, and Delete) are automatically generated with one table to one object mappings. If you use custom queries or stored procedures, these queries are missing, and you must manually define the queries using the Data Access Builder Tool. An example of this would be a join query that defines an object Customer.

1. In the Data Access Builder window, from a bean's pop-up menu, select Methods. Add a new method called addCustomer1.

2. Enter the following SQL statement:

INSERT INTO TPF.CUSTOMER (
CUSNO,
FIRSTNAME,
MIDINIT,
LASTNAME,
HOMEPHONE,
HOMEADDR,
WORKPHONE,
BILLADDR,
BRANCHNO,
OPEN DATE)
VALUES (?, ?, ?, ?, ?, ?, ?,?, ? ,?)

After Data Access Builder validates the query, you must map the parameters individually using the Parameter page.

You also need to define the query addCustomer2 for the insert of the second join table CUSTDATA. The synchronization of the two queries for this atomic function is handled by the user.

Persistence Builder

Persistence Builder will generate all of the CRUD operations once a map has been created between the defined schema and model. In the case of multi-table joins, each table query is generated, and the service engine manages these operations as an atomic unit.

Stored Procedures are not supported in the tools yet, but "Stub Schemas" can be generated and extended. An example of an insert stored procedure query follows.

/**
*Return a query spec for the query called insert
* @return java.util.Vector
* @param args java.util.Vector
* @param anInjector com.ibm.vap.Persistence.BOInjector 

public java.util.Vector insertQuery(java.util.Vector args,com.ibm.vap.Persistence.BOInjector anInjector) {
    Vector aSpecArray = new Vector();
DatabaseCompoundType aCompoundType;
   

 DatabaseQuerySpec spec = new DatabaseCallableQuerySpec("{call     

    insertEmp (?,?,?,?)}");

Vector stringArgs;
a CompoundType = new DatabaseCompoundType();

aCompoundType.addField((DatabaseTypeField)(new         com.ibm.ivj.db.base.DatabaseIntegerField("EMPNO")).setAttributes(4,0,4,false));

aCompoundType.addField((DatabaseTypeField)(new com.ibm.ivj.db.base.DatabaseDecimalField("SAL")).setAttributes(9,2,3,false));

aCompoundType.addField((DatabaseTypeField)(new com.ibm.ivj.db.base.DatabaseIntegerField("DEPTNO")).setAttributes(2,0,4,false));

aCompoundType.addField((DatabaseTypeField)(new com.ibm.ivj.db.base.DatabaseStringField("ENAME")).setAttributes(10,0,12,false));

StringArgs = new Vector();
stringArgs.addElement("EMPNO");
stringArgs.addElement("SAL");
stringArgs.addElement("DEPTNO");
stringArgs.addElement("ENAME");

spec.setInputShape(aCompoundType);
spec.setInputValues(args);
spec.setInputNamesWithDuplicates(stringArgs);
   aSpecArray.addElement(spec);
        return aSpecArray;

5.0 Custom Query Support

In Data Access Builder

Custom queries in the Data Access Builder are defined the same way CRUD queries are defined. The user adds the named query, and uses the parameter page if necessary. The resulting query will appear as a method on the BusinessObjectMgr class.

The Data Access Builder also provides other methods of defining custom queries, such as SQL Predicate substitution.

TheEmpMgr.select('WHERE WORKDEPT = 'E11');

In Persistence Builder

There are two options for adding custom queries in Persistence Builder. Lite Collections can be defined at the class level using the class editor.The following page is used to search and filter on the specified class.

Lite collection queries are generally used in search lists or dialogs to "drill down" to the appropriate Business Object. The resulting methods return vectors of "Data Objects" that can be used to retrieve the corresponding persistent business object.

The following is a code example using the generated lite collection shown above:

VapCourseHomeImpl aHome = VapCourseHomeImpl.singleton();
    VapDepartmentKey aKey = new VapDepartmentKey("Sales"); 
VapLiteCollection liteCollection = aHome.getByDepartmentLiteCollection(aKey); 

Enumeration enum = liteCollection.elements();
VapCourseDataObject aDO;
VapCourse aCourse; 

while (enum.hasMoreElements()) {

    aDO = (VapCourseDataObject)enum.nextElement(); 
   aCourse = aHome.find(aDO.getNumber()); 
   //Fetching fully hydrated EJBObject
   }

Persistence Builder also provides a custom query framework, which can be used todefine various operations on a business class. These queries will return fully functional Business Objects.

The following is an example of a class student with a custom query "retrieveStudentsOver21". The Home class for students has the following method:

public Vector retrieveStudentsOver21() throws java.rmi.RemoteException,     
com.ibm.vap.common.VapReadFailureException {
    return customQuery("studentsOver21Query");
}

The QueryPool for students contains the corresponding methods for the custom service:

/* Return a query spec for the query called studentsOver21
 @return java.util.Vector */

public java.util.Vector studentsOver21Query() {
    Vector aSpecArray = new Vector();
    aSpecArray.addElement(new DatabaseSelectQuerySpec(studentsOver21SqlString()));
          return aSpecArray;

}

/* Return the SQL string for the query called studentsOver21Query
  @return java.lang.String */

public java.lang.String studentsOver21SqlString() {

return "SELECT T1.SNAME, T1.SNO, T1.SADVFNO, T1.SBDATE, T1.SADDR, T1.SPHNO, T1.SMAJ, T1.SIQ FROM SPARKY.STUDENT T1 WHERE T1.SBDATE <= (CURRENT DATE - 00210000.)";
}

This method is executed from the home, and has similar object caching behavior as the All-instances method. For more information about this method, refer to the Persistence Builder online help.

Part 2: Run-time features

1.0 Datastore/Transactional Capability

In Data Access Builder

Datastores in the Data Access Builder can be configured at many application levels:

• The Application Datastore is used as a default datastore that all generated business classes may use if one is not defined for it
• The Default Class Datastore specifies at a class level what the instances use as a datastore.
• The Object's Datastore specifies the datastore at the instance level.

Data Access Builder Datastores have a flat transactional model, in other words, if multiple transactions are needed to apply a business function, then a datastore representing each transaction would need to be activated.

Here is a simple scenario with an Employee and Department model:

EmployeeDatastore anEmpDS = new EmployeeDatastore().connect();
DepartmentDatastore aDeptDS = new DepartmentDatastore().connect();

Employee anEmp = new Employee();
Department aDept = new Department();

// Perform actions on anEmp and aDept

if (User Applied Employee Changes)
anEmpDS.commit()
else
anEmpDS.rollback();
aDeptDS.commit();

Persistence Builder

In VisualAge for Java, Version 4.0 Persistence Builder has the option of using the WebSphere Connection Pool using the JNDI name to lookup the Datasource. This option is available when generating the service classes.

Multiple datastores in Persistence Builder are only required if different databases are used to access model data. Multiple nested transactions are supported per datastore. Transactions are not implied as they are in Data Access Builder. User transactions are controlled by transaction objects that have views on the application business objects.

Here is a code snippet showing the same transactional capability in the Data Access Builder example.

DB2Datastore aDS = DB2Datastore.singleton().activate();
Transaction empTransaction = Transaction.begin();
Employee anEmp = EmployeeHomeImpl.create("EmpNum1");
Transaction deptTransaction = Transaction.begin();
Department aDept = DepartmentHomeImpl.create("DeptNum1");

// Do some actions on anEmp and aDept, always resuming the appropriate transaction before making changes to the corresponding BO.

if (User Applied Employee Changes)
    empTransaction.commit();
else
    empTransaction.rollback();
deptTransaction.commit();

It is important to note that in Persistence Builder, no SQL is executed until a transaction is committed. The objects transactional state is maintained internally until an explicit rollback or commit occurs.

2.0 API support

The generated methods on the resulting business objects, and their companion management objects are slightly different between the three frameworks. The following table shows the classes and methods used for each function.

(*)Update operations are implied by altering the values on a business object, if the active transaction is committed, the changes will be synchronized with the datastore by issuing the appropriate update statements.

(**)The section Cursor Support shows alternative solutions.

LOB Support

3.0 Quickforms (RAD Features)

4.0 Current Date/Time/Timestamp support

The Data Access Builder tools allow the user to specify "current" on date/time data types, which generates the appropriate SQL. Persistence Builder and Data Access beans do not support this in their tools, but the SQL could be added manually.

5.0 Cursor Support

Data Access Builder supports cursor functions on result sets, such as updateCurrent() or deleteCurrent().

Persistence Builder does not currently support these operations. A good alternative in this case would be to use the Data Access beans feature.

The Data Access beans support cursor functions with the DBNavigator visual part managing the cursor position. The following is a description of all the cursor features:

• Cache support for result sets
• Direct access to specific row in cache
• Scrolling backward and forward
• Support large result sets with user specified options

JDBC v1.0 does not support backward scrolling in a JDBC result set. The Select bean maintains a cache of the result set that allows you to scroll through the result set as well as directly access a specific row. The Select bean has properties that allow you to control the size of the cache. You can fetch the entire result set into the cache (with is the default), or fetch a packet at a time into the cache. The size and number of packets is controlled by the user.

• Provide update/insert/delete support on result set

Once a result set has been obtained, the Select bean provides methods to update, delete or insert rows into the result set. No new SQL has to be written by the user to perform these functions.

Data Access Builder supports asynchronous operation by providing runnable interfaces on its generated classes.

Persistence Builder also provides runnable interfaces for each CRUD operation and one for custom queries. The service object for each business class has the method runAsynch(), which determines the execution type for that class.

Data Access beans supports asynchronous execution through the DBNavigator tool which spawns "DBAction" runnable instances.

Concurrency Issues (locking/isolation levels)

Data Access Builder does have API for setting the database isolation level on the generated datastore class setTransactionIsolation(int).

Persistence Builder maintains its own transactions, and supports the following isolation levels internally.

• Non-locking Repeatable Read
• Non-locking Unrepeatable Read
• Locking Repeatable Read
• Locking Unrepeatable Read.

The Transaction specifies either Repeatable Read or Unrepeatable Read isolation level. The service implementation for the Business class specifies either non-locking or locking implementation. Refer to the Persistence Builder online help for more details about the differences between the levels.

Data Access beans does have API for setting the database isolation level. You can do this by specifying the desired isolation level when you supply the connection information through the custom property editor or via DatabaseConnection.setTransactionIsolation() method.

Part 3: Data Access beans (DAB) features

The mapping for DAB occurs between tables and Select beans. This mapping between a table and Select bean is not 1:1, and thus the Select bean does not represent the table. However, Select Beans can very useful for working with the current row and with a result set. You can create one or two Select Beans that can you can use to perform basic database programming operations on a table. Thus, if you are using DAX for database operations like queries, read, write, update, and delete in a simple, straight forward way, then DAB can be a good replacement for DAX.

You can interact with databases by setting the query property (which is made up of connection information and SQL Query information) of a Select bean.  The connection information contained in the query property can be used by more than one select bean. You can incorporate select beans into your code either visually, using the Visual Composition Editor or manually. 

The following is a general outline on how to create a Select Bean to work with the current row of a customer table. Refer to the online help for more details about how to perform these steps:

1. Open a class in the VCE, create a Select bean, and open the Query property editor.  
2. Enter the necessary connection information and generate a database access class.
3. Specify the Database Access class.Open the SQL Assist SmartGuide.

   

4. Selecting the customer table and specifying the condition that the customer number (cusno) is exactly equal to the parameter CUSTNUM. generates a Select bean for the customer. The Database Access class for this select bean would appear similar to the following:

   

With this Select bean, you can perform basic database operations (read, write, update and delete), on a row in the customer table (when the customer number is specified).  

Creating a second select bean

Another Select bean can be created to work with a result set (that is, do a database query) by going through the same procedure and not specifying any conditions. This second Select bean would allow you take advantage of  DAB result set functionality. The Database Access class for this Select bean would appear similar to the following:

Select beans and custom queries

DAB provides strong support for creating Select beans that use custom queries. As shown below the SQL Assist SmartGuide can assist you in creating a join query, specifying conditions for a query, selecting columns, sorting columns and  mapping fields.

Data Access beans and Stored Procedures

The Procedure Call bean enables you to work with stored procedures. Creating a Procedure Call bean is very similar to creating a select bean. The SmartGuide for stored procedures lists the available stored procedures as shown below.

For more information on using the Procedure Call bean refer to the Data Access beans online help.

Copyright and Notices

© Copyright IBM Corp.1997, 2001. All Rights Reserved.

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 document 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.

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. The licensed program described in this document 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.

IBM, AIX, AS/400, DB2, OS/390, OS/400, RS/6000, S/390, VisualAge and WebSphere are trademarks of IBM Corporation in the United States and/or other countries.

Lotus, Lotus Notes and Domino are trademarks of Lotus Development Corporation in the United States and/or other countries. Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. in the United States and/or other countries. Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation in the United States and/or other countries. Intel and Pentium are trademarks of Intel Corporation in the United States and/or other countries. Other company, product, and service names may be trademarks or service marks of others