VisualAge(R) for Java(TM), Entry Edition for Windows (R), Version 3.0 README To view this file in HTML format, open readme.htm from the root directory of the CD-ROM. To view this file in text format, open readme.txt from the root directory. For best results when printing this in text format, decrease the printing margins to the minimum allowed and decrease the point size of the font to 10. This will prevent line wrapping. This README file contains information about installing VisualAge for Java, Entry Edition and about installation and uninstallation problems. It also includes the following information: * How to migrate from previous versions of VisualAge for Java * Hardware and software prerequisites for VisualAge for Java * Browser configuration for online help Important: This Entry Edition of the product is limited to the creation of 750 classes. Any additional classes developed will not be saved. 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, Entry Edition. For that information, you should refer to the product Release Notes which you can access by selecting Start > Programs > VisualAge for Java > Release Notes. 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. The online help also contains a "Web Resources" page that contains links to VisualAge resources that are available on the Internet. The VisualAge Developer Domain (VADD) Web site offers information about tools, education, hints, and tips, 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/software/vadd. You can also use this site to request features in upcoming releases of VisualAge for Java, using our new online Feature Request Database. The product home page for VisualAge for Java home page is at http://www.ibm.com/software/ad/vajava Table of Contents 1.0 Prerequisites 2.0 Installation procedures 2.1 Installing VisualAge for Java, Version 3.0 2.2 Installing additional components later 3.0 Migrating from a previous version of VisualAge for Java 3.1 Migrating from VisualAge for Java, Version 2.0 3.2 Reclaiming space lost during a migration from Version 2.0 3.3 Migrating from VisualAge for Java, Version 1.x 4.0 Known problems and limitations 4.1 Known problems and limitations of installation 4.2 Known problems and limitations with uninstallation 5.0 Browser configuration for online help 1.0 Prerequisites This edition of VisualAge for Java, Version 3.0, has the following hardware and software prerequisites: * Windows 95, Windows 98, or Windows NT(R) 4.0 with Service Pack 3 or Service Pack 4. For customers who wish to use the Euro currency symbol on Windows, a free update is available from Microsoft from the following web address: http://microsoft.com/windows/euro.asp. This patch is not required if you are using Windows NT 4.0 with SP4 applied. * TCP/IP installed and configured * Pentium (R) processor or higher recommended * SVGA (800x600) display or higher * a mouse or pointing device * 48 MB RAM minimum (64 MB recommended) If you are migrating from Version 2.0 of VisualAge for Java, your migrated repository will increase in size to include the repository shipped with Version 3.0. You can expect an increase in the size of the repository of at least 35 MB for a basic installation. * Frames-capable Web browser such as Netscape Navigator 4.04 or higher, or Microsoft (R) Internet Explorer 4.01 or higher. Explorer 3.0 is frames-capable, but it does not support cascading style sheets, so the online help will not be displayed properly in it. * Java Development Kit (JDK) (TM) 1.1.7 for deploying all applications 2.0 Installation procedures This section contains information about installing VisualAge for Java, Version 3.0. Important: If you are migrating from a previous version of VisualAge for Java, refer to section 3.0 before installing VisualAge for Java, Version 3.0. 2. 1 Installing VisualAge for Java, Version 3.0 Before you install the product, check the following things: * You must have at least 2 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. * The CLASSPATH must be less than 470 characters. VisualAge for Java for Windows inserts approximately 26 characters into the CLASSPATH during installation. These numbers are based on the assumption the target directory is 8 characters long, for example, IBMVJAVA. To install VisualAge for Java, Version 3.0: 1. Insert the CD-ROM into your CD drive. If you are migrating from a previous version of VisualAge for Java, read the "Migrating from a previous version of VisualAge for Java" section 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. In the Install Selection screen, select Install VisualAge for Java to begin the installation of VisualAge for Java. Follow the on screen instructions. 4. Reboot after installing VisualAge for Java. 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 and select the components you want to install from Custom Setup. If autorun is disabled on your system, you will have to run setup.exe from the root of the CD drive. When prompted, select to update the current installation rather than to install a second copy of VisualAge for Java. 3.0 Migrating from a previous version of VisualAge for Java Refer to section 3.1 for information about migrating from version 2.0 of VisualAge for Java. Refer to section 3.2 for information about reclaiming lost space after migrating for VisualAge for Java, Version 2.0. Refer to section 3.3 for instructions on manually migrating your user data from version 1.x of VisualAge for Java. 3.1 Migrating from VisualAge for Java, Version 2.0 Migration from Version 2.0 to Version 3.0 of VisualAge for Java is automatic. The Version 3.0 installation program automatically upgrades an installed Version 2.0 product to Version 3.0. Follow these steps to migrate from Version 2.0 to Version 3.0: Automatic migration 1. Perform steps 1 to 3 from section 3.3. It is strongly recommended you create backup copies of your repository and resource files in case problems occurs during migration. 2. To install VisualAge for Java, Version 3.0 follow these steps: a) Insert the CD-ROM into your CD drive. b) If autorun is disabled on your system, run setup.exe from the root of the CD drive. c) In the Install Selection screen, select Install VisualAge for Java to begin the installation of VisualAge for Java. Follow the on-screen instructions. 3. The VisualAge for Java, Version 3.0 installation program automatically prompts you to confirm that you want to upgrade to Version 3.0. Select Yes. You do not need to uninstall Version 2.0 as it is automatically upgraded to Version 3.0. If you select No, the installation process is aborted. 4. Upon the completion of a successful upgrade installation, all of your project resources and your repository data are automatically migrated to Version 3.0 when you start the Version 3.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. Follow these steps to recover from a failure and manually migrate your user data: Manual migration 1. Verify you have saved your repository and resource files outside of the Visual Age for directory tree. 2. Uninstall the product completely. All Version 2.0 and Version 3.0 subdirectories and files should be deleted. 3. Reboot and reinstall Version 3.0. 4. Start the IDE. 5. Perform steps 5 to 8 from section 3.3. Once you have verified that your manual or automatic migration is successful, you can delete the backup copies created in step 1. Attention: The coexistence of VisualAge for Java, Version 2.0 and VisualAge for Java, Version 3.0 is not supported . Version 2.0 can be installed on a system that has Version 3.0 installed, but the behavior of both versions of the product will be unpredictable. 3.2 Reclaiming space lost during a migration from Version 2.0 The extra space taken up by the migration process is split into four categories, three of which can be reclaimed: 1. VisualAge for Java, Version 2.0 help system 2. A back up copy of the Version 2.0 repository 3. Version 2.0 documentation (PDF form) To reclaim the space taken up by the help system, follow these steps: 1. From a command prompt, go to the following directory: x:\IMNnq_NT or x:\IMNnq_95, depending on where NetQuestion was installed for Version 2.0. 2. On single byte systems, run the following commands: imnixdel IVJX imndomap -d IVJX where lang_code is ENUS (English), ESES(Spanish), FRFR(French), PTBR (Portuguese), ITIT(Italian), and DEDE(German). On double byte systems, run the following commands: imqixdel IVJX imqdomap -d IVJX where lang_code is JAJP(Japanese), KOKR(Korean), ZHCN(Simplified Chinese), and ZHTW(Traditional Chinese). 3. Go to the following directory: x:\IBMVJava\doc\, where x:\ IBMVJava is your Version 3.0 installation directory. 4. Delete the following files: o VAJAVA.NAV o VAJAVA.TCH o VAJAVA.ZIP To reclaim the space taken up by the back up copy of the Version 2.0 repository: 1. Ensure that VisualAge for Java, Version 3.0 is working correctly. Ensure that any Version 2.0 projects and packages you want to work with are now part of the Version 3.0 repository. 2. Delete the following file: x:\IBMVJava\IDE\Repository\ivj20.dat, where x:\IBMVJava is your Version 3.0 installation directory. To reclaim the space taken up by the PDF documentation files (from the Version 2.0 help system), delete the following directory and its contents: x:\IBMVJava\doc\pdf, where x:\IBMVJava is your Version 3.0 installation directory. 3.3 Migrating from VisualAge for Java, Version 1.x If you have Version 1.x of VisualAge for Java installed on your system, this version must be uninstalled before installing VisualAge for Java, Version 3.0. Follow these steps BEFORE uninstalling Version 1.x if you want to import your Version 1.x repository and resource files into Version 3.0. 1. Version your projects and packages. Only versioned projects and packages can be imported into the VisualAge for Java, Version 3.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. 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. Uninstall Version 1.x, and install Version 3.0. 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. 6. To automatically add the selected projects to the workspace, select the Add most recent project edition to the workspace checkbox. This checkbox is only available when the Projects radio button is selected. 7. Click Finish. 8. Copy your backup copy of your resource files into the subdirectories x:\IBMVJava\ide\project_resources\project, where x:\IBMVJava is the VisualAge for Java, Version 3.0 installation directory and project is the name of the project with which the resources are associated. 9. Once you have verified that your manual migration is successful, you can delete the backup copies that you created in steps 2 and 3. 4.0 Known problems and limitations 4.1 Known problems and limitations of installation The following is a list of issues you should be aware of during installation: * You may encounter the following NetQuestion error: " Index specific error encountered. (rc=8)" when you are using the search function in the online help. This error message does not interfere with the search function, and occurs if the Version 2.0 help system index has not been properly removed. Refer to section 3.2 for instructions on how to remove it. * An "Autoconfigured" warning from the installation program indicates that your proxy exceptions are autoconfigured on Netscape 4.x. Check with your system administrator to ensure that 127.0.0.1 is treated as a local address. * Do not install to a Novell NetWare drive. Installation will fail on a Novell NetWare drive. * You will need write access to the root "\" directory where VisualAge for Java is installed to install the NetQuestion Search Server. * 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). * Do not install to an HPFS network or local drive since Windows 95, Windows 98, and Windows NT 4.0 have trouble handling long file names on HPFS. * If you are installing from an image downloaded from the Web, create a temporary directory on a FAT or NTFS drive (not HPFS) and unzip the web image for the actual install programs. (setup.exe will not run from an HPFS drive with a long file name in its directory). * Windows 95 and Windows 98 have a 500 character restriction for the PATH and CLASSPATH environment variables in autoexec.bat. * On Windows 95 and Windows 98, you should edit your config.sys file to increase the environment space to 32000. Insert the following line: SHELL=X:\COMMAND.COM /E:32000 /P where "X:" is your boot drive. * You must install and configure TCP/IP in order for IBM VisualAge for Java to function properly. For Windows 95 and Windows 98, 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 95 or Windows 98 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. * If your installation fails, delete all the files located in the root install tree, which by default is C:\IBMJAVA. If NetQuestion was installed before the installation failed, you must delete it as well (IMNnq_NT or IMNnq_95). Important: If you are migrating from a previous version of VisualAge for Java, ensure your user data has been safely backed up outside the root install tree before deleting all your files in the root install tree. You will also need to delete the registry entries: \\HKEY_LOCAL_MACHINE\SOFTWARE\IBM\VisualAge for Java for Windows and \\HKEY_LOCAL_MACHINE\SOFTWARE\IBM\NetQuestion 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. Invoke regedit.exe from a command prompt. 3. Expand and select the key \\HKEY_LOCAL_MACHINE\SOFTWARE\IBM\VisualAge for Java for Windows. 4. Select Edit - Delete from the menu bar for this key. 5. Select Yes when asked to confirm deletion of the key. 6. Warning: Only perform steps 6-8 if you know NetQuestion is not being used by other IBM(R) products such as DB2(R), VisualAge C++, or Component Broker. If it is, do not delete the NetQuestion key. Select the key \\HKEY_LOCAL_MACHINE\SOFTWARE\IBM\NetQuestion. 7. Select Edit - Delete from the menu bar for this key. 8. Select Yes when asked to confirm deletion of the key. 9. Select Registry - Exit from the menu bar. Reboot and re-install the product. * If you get a message that indicates that the installation program has detected a Shell Extension for Windows NT, the installation will not be able to 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. Invoke regedit.exe from a command prompt. 3. 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: 1. Invoke regedit.exe from a command prompt. 2. Expand the key \\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon 3. Select the shell name in the name/data pairs for the above key. 4. Select Edit > Modify from the menu bar for the shell name/data pair. 5. Restore the value for the shell name to the value that was recorded in Step 4. Click OK. 6. Select Registry - Exit from the menu bar. 4.2 Known problems and limitations with uninstallation The following is a list of items that you should be aware of during uninstall: * If you migrated from Version 2.0 to Version 3.0, you must remove Version 2.0's NetQuestion indices BEFORE you begin the uninstallation process for Version 3.0. Otherwise, you will not be able to uninstall NetQuestion. Refer to section 3.2 for instructions on how to do this. * 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. * When you uninstall VisualAge for Java on Windows 95 or 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 follow these steps: 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) Run regedit.exe from a command prompt and 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 HTML 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 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. Start regedit.exe from a command prompt. 2. 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. * When you are uninstalling VisualAge for Java, NetQuestion may not be uninstalled. You may have to delete its directory (IMNnq_NT or IMNnq_95) manually. Problems may occur if NetQuestion is not uninstalled and you later attempt to reinstalled the product. 5.0 Browser configuration for online help The VisualAge for Java installation program checks your browser configuration and offers to change it automatically so you can view online help. If you select Yes, localhost: 49213 and 127.0.0.1 are added to your proxy exception settings. If you select No, you may not be able to view online help. If you select No, and later decide you want to view online help, you can manually change your browser configuration to the correct settings. Refer to the Online Help Release Notes for instructions on how to correctly configure your browser for viewing online help. (C) Copyright IBM Corporation 1997, 1999 - All Rights Reserved. Notices Licensed Materials - Property of IBM US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Your use of this product is subject to the terms of the enclosed International Program License Agreement and License Information. Trademarks and service marks The following terms are trademarks of International Business Machines Corporation in the United States, or other countries, or both: * IBM * DB2 * VisualAge Lotus, Lotus Notes and Domino are trademarks or registered trademarks of Lotus Development Corporation in the United States, or other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States or other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks or registered trademarks of Microsoft Corporation in the United States, or other countries, or both. Intel and Pentium are trademarks of Intel Corporation in the United States, or other countries, or both.