Introduction

The tasks of installing an Eclipse-based IBM® Rational® product in the IBM® Rational® Software Development Platform -- and then updating the product with the latest fixes -- are distinct, and must be performed in sequence. This article explains how to automate the tasks of silently installing and updating an Eclipse-based Rational Software Development Platform product on Microsoft® Windows®, so that administrators who are installing the product on multiple machines over a network can run these tasks in a single step.

This article shows you how to create an installation image for the product on a network drive, and how to create a copy of the product's IBM update site on your local server. It then explains how to install the product silently from the installation image on the network drive, and how to apply updates silently (for both the product and the update tool). Finally, this article shows you how a batch file can be used to install and update the product silently. Figure 1 illustrates the typical components involved in this installation scenario.

This article is intended to supplement -- not replace -- either the installation guide and other documentation provided with the product, or the documentation accompanying product updates and optional features. Much of the information in this article can be found in existing documentation, and these sources are referred to for additional information. Unique to this article is the information on installing and updating the product using a batch file, and the end-to-end presentation of the required steps in order to use this method.

Important: Before you install and update an Eclipse-based Rational Software Development Platform product, you are strongly encouraged to review the installation guide and release notes for each item that you plan to install. In particular, you should check that you meet the hardware and software prerequisites.

Preparing the server for the product installation

Creating the installation image on a network drive

Refer to your product's installation guide for additional information on the tasks described in this section.

You can place a copy of the installation image of the product on a shared drive so that users can install it across a network. To create the installation image on the network drive, you must either copy the contents of the product's CDs to the server, or extract the installation image from a downloaded electronic image of the product.

To copy the files from the CDs:

1. Insert the first installation CD into your CD drive.
2. Create a temporary directory on a network drive where you want to store the image (for example, <network_drive>:\install_image).
3. Under the temporary directory, create a subdirectory called disk1. This subdirectory must be called disk1 and it must be in lower case.
4. Copy all the files and directories on the first installation CD to the disk1 subdirectory in the temporary directory.
5. Repeat steps 3 and 4 to copy the contents of any additional core installation CDs for your product to subdirectories called disk2, disk3, and so on.
6. (Optional) Depending on your product, you may have CDs for optional features that must be installed separately (for example, IBM® WebSphere® Application Server Version 5.x test environments). You may continue repeating steps 3 and 4 to copy the installation CDs for these optional features into your temporary directory. Note that these features must be installed separately.

To download and create the electronic installation image:

1. Download all required parts -- and any optional parts that you choose -- to the same temporary directory. If you decide later to add more optional parts, download the additional optional parts and rerun the extraction tool prior to attempting the installation.
2. Launch the extractor.exe file located in your temporary directory. This starts the wizard that creates the installation image from the downloaded parts.
3. Follow the instructions in the wizard to specify where you want to create the image (for example, <network_drive>:\install_image) and which features you want to include.
4. After the extractor program successfully creates the installation image, clear the Start the installation wizard checkbox so that you can run the installation program later.

Creating a response file for the installation

If you want to silently install one or more optional features (in other words, features that are not installed by default), or change the default installation path, you will need to modify the sample response file that is provided with your product. Otherwise, the installation program will silently install the default features only into the default location. The response file is used to specify installation preferences when silently installing the product. The sample response file, called responsefile.txt, is located in the \disk1\util directory in the directory containing your installation image.

The example in Listing 1 shows the contents of the file responsefile.txt for IBM® Rational® Application Developer:

# -P installLocation=<value>

# -P feature_was6_win32.active=<value>

# -P feature_lang_pack_rad_win32.active=<value>

# -P feature_egl_win32.active=<value>

# -P feature_portal_win32.active=<value>

# -P feature_examples_win32.active=<value>

Refer to your product's installation guide for detailed information on the specific options in your responsefile.txt. For example, the following table describes the response file options and their corresponding entries in the response file for Rational Application Developer.

To create a response file containing your installation preferences when silently installing:

1. Copy the file responsefile.txt to a new file. For example, copy the file and name the new file modified_responsefile.txt.
2. Open the copy of the response file in a text editor.
3. Locate the line containing the entry for the installation feature that you want to change from the default setting, and make the following changes:
   1. Remove the # at the start of the line containing the entry.
   2. Change <value> to the appropriate value:
      • If you are changing the default installation directory by editing the installLocation entry, change <value> to the desired directory.
      • Change <value> to true in order to install an optional feature.
      • Change <value> to false in order to not install a default feature.
4. Save your changes.

In the example shown in Listing 2, the file responsefile.txt file for Rational Application Developer has been modified (and saved, for example, at <network_drive>:\install_image\disk1\util\modified_responsefile.txt) to implement the following preferences:

• The installation path is changed from the default to C:\RAD6.0.
• WebSphere Application Server Version 6.0 test environment will not be installed.
• The language pack is installed.
• The EGL feature is installed.

-P installLocation=C:\RAD6.0

-P feature_was6_win32.active=false

-P  feature_lang_pack_rad_win32.active=true

-P feature_egl_win32.active=true

# -P feature_portal_win32.active=<value>

# -P  feature_examples_win32.active=<value>

Preparing a JRE for running the installation from a batch file

Your goal is to create a batch file that will allow you to run the tasks for both product installation and update in a single step. To simplify the scripting of your batch file, the batch file must easily detect when the installation program has completed, so that it can then start the update program.

If your batch file runs the installation executable file (setup.exe -silent), the call returns immediately, and the batch file cannot detect whether the installation has completed unless you use a process listener. A simpler solution is for the batch file to make calls directly to the Java™ runtime environment (JRE).

In order for the batch file to be able to make calls directly to the JRE, you must perform the following steps:

1. Extract the JRE embedded in the setup.exe file:
   1. On the network server where you created the installation image, navigate to the disk1\setup directory.
   2. Make a copy of the file setup.exe.
   3. Rename the copy of setup.exe as setup.zip.
   4. Extract the contents of setup.zip to a folder on your network server. (For example, extract the contents to <network_drive>:\install_image\IBMJRE.)
2. Modify the jvm file so that it will point to the location of the JRE:
   1. Open the file called jvm (for example, <network_drive>:\install_image\IBMJRE\jvm) in a text editor.
   2. Add the following lines (shown in Listing 3) at the end of the file in order to point to the location of the JRE on the network server:
      
      
      Listing 3. Sample commands for installing the product silently using a response file and not calling the JRE directly
      

      JVM_HOME: network_drive:\install_image\IBMJRE JVM_FILE: network_drive:\install_image\IBMJRE\jvm JVM_TEMP: 1

      
      
   3. Save the jvm file.

Back to top

Preparing the server for the product updates

The sections below describe the tasks for creating a mirror of the product update site on your local server:

1. Downloading and extracting updates.
2. Creating site.xml files.
3. Creating policy.xml files.

The installation instructions provided for each product will refer to or include detailed instructions on creating a local mirror of the product update server. You may also refer to the IBM® Rational® Product Updater online help for more information. (Click Start > Programs > IBM Rational > Rational Product Updater, then in the menu click Help > Help Contents.)

Downloading and extracting the product updates

To find the available updates and optional features for the product at the IBM Support Web site:

1. Go to www.ibm.com/support/.
2. From the navigation bar, select Downloads and drivers.
3. On the next page, in the Category list, select Software > Rational, and in the Sub-category list select the name of your Eclipse-based Rational Software Development Platform product. The downloads available for that product are displayed.
4. In the section Refine your results under Software version, select the most recent version for the product.
5. Click an update or optional feature to display detailed information, including information on downloading and extracting a ZIP file of the update or feature. Note that only updates that are installed using the Rational Product Updater can be included on your local update site.

The installation instructions for the update may link to a document for creating a local mirror of the update site for the product, one that contains a list of all updates and features available for that version. (For example, www3.software.ibm.com/ibmdl/pub/software/rationalsdp/rad/60/install_instruction/6011/install.html.)

Attention: You must download the latest Rational Product Updater to apply the latest updates or optional features.

After you download the updates, extract the files to the server (for example, <network_drive>:\install_image\updates) that will stage your local mirror of the update server. You can extract all the updates to the same target directory. The updates do not overwrite each other.

Creating and updating site.xml files

Generally, an update site and a discovery site exist for each product. The update site contains product fixes, such as interim fixes, fix packs, and refresh packs, and the discovery site contains optional features.

Note: Rational Product Updater does not have a discovery site.

Each product fix that you download and extract contains a site_<identifier>.xml file in the <product>\60\<update>\ directory, and each downloaded and extracted feature contains a site_<identifier>.xml file in the <product>\60\<discovery>\directory (where _<identifier> identifies the version of the product fix or feature and <product> identifies the product). The site_<identifier>.xml files for updates to Rational Product Updater are located in the rpu\60\update\ directory.

Rational Product Updater requires the information contained in this site_<identifier>.xml file in order to install the product update or feature.

Product Updater expects to find at most one site.xml file for product updates and one site.xml file for optional features for a Rational Software Development Platform product. Each product update or feature that you download and extract, however, will contain a site_<identifier>.xml file specific to that update or feature. Therefore, if your local site will contain multiple updates and optional features for a product, you must combine the individual site_<identifier>.xml files for updates for that product into a single site.xml file, and similarly create a single site.xml file for the product's optional features.

In general, to combine the site_<identifier>.xml files:

1. Navigate to the <product>\60\<update>\ directory.
2. If you do not already have a combined file named site.xml, copy one site_<identifier>.xml file into a new file named site.xml in the same directory.
3. Copy the <feature> information (including the <feature> tags) from the remaining site_<identifier>.xml files into the site.xml file between the <site> tags.
4. Save the site.xml file.
5. Navigate to the <product>\60\<discovery>\ directory and repeat steps 2-3.
6. Delete outdated feature information in the <product>\60\<discovery>\ file.
7. Save the site.xml file.

Creating a policy.xml file for updating the product

After you place the files for product updates and optional features on your local site, you must configure Rational Product Updater to use your local site instead of the default IBM update site. An XML file named policy.xml tells Rational Product Updater where to find the site.xml files for updates and optional features for products on your local site.

Each product fix and feature that you download contains a <product>\policy_<identifier>.xml file (for example, rad\policy_601.xml) that references its corresponding site_<identifier>.xml file. You must combine all of the <product>\policy_<identifier>.xml files into a single policy.xml file. After you create this policy.xml file, it can be used for all product updates, and will reference the site.xml files that you created in the previous section.

To create the policy.xml file, complete the following steps:

1. Open a product\policy_identifier.xml file with a text editor.
2. In the main directory of your mirror site, save the file as policy.xml.
3. Edit the URL map to point to site.xml instead of site_identifier.xml. Ensure that you specify a universally accessible absolute path to the site.xml file. For example, if your mirror site is on a Web server named server1, your policy.xml file will be similar to that shown in Listing 4.
   
   
   
   Listing 4. Sample policy.xml file that refers to a local update site
   

   <?xml version="1.0" encoding="UTF-8"?> <update-policy> <url-map pattern="com.ibm.rational.application.developer.update" url="http://server1/updates/rad/60/update/site.xml"/> </update-policy>

   
   
4. Add the URL map information from all of the other <product>\policy_identifier.xml files.
   
   For each product that you can update from your local mirror of the update server, you should have one URL map for the update site, and another URL map for the discovery site. Additional URL maps are required for feature discovery sites. The patterns are provided in each <product>\policy_identifier.xml file.
   
5. Edit each URL map to point to site.xml instead of site_identifier.xml. Your file will be similar to Listing 5.
   
   
   
   Listing 5. Sample policy.xml file has local discovery site added
   

   <?xml version="1.0" encoding="UTF-8"?> <update-policy> <url-map pattern="com.ibm.rational.application.developer.update" url="http://server1/updates/rad/60/update/site.xml"/> <url-map pattern="com.ibm.rational.application.developer.discovery" url="http://server1/updates/rad/60/discovery/site.xml"/> </update-policy>

   
   
   
6. Create a URL map for the updates to Rational Product Updater by typing a universally accessible absolute path to its site.xml file. Listing 6 shows an example.
   
   
   Listing 6. Sample commands for installing the product silently using a response file and not calling the JRE directly.
   

   <url-map pattern="com.ibm.orca.product.updater" url="http://server1/updates/rpu/60/update/site.xml"/>

   
   Your policy.xml file should now look similar to Listing 7.
   
   
   Listing 7. Sample policy.xml file has Rational Product Updater update site added
   

   <?xml version="1.0" encoding="UTF-8"?> <url-map pattern="com.ibm.orca.product.updater" url="http://server1/updates/rpu/60/update/site.xml"/> <update-policy> <url-map pattern="com.ibm.rational.application.developer.update" url="http://server1/updates/rad/60/update/site.xml"/> <url-map pattern="com.ibm.rational.application.developer.discovery" url="http://server1/updates/rad/60/discovery/site.xml"/> </update-policy>

   
   
7. Save the policy.xml file.
8. Close your text editor.

Creating a policy.xml file for updating Rational Product Updater

Your batch file that automates the installation and update tasks must also separately update Rational Product Updater to the latest required version first, before silently installing updates for other products.

As per the section Downloading and extracting the product updates, you must download and extract the latest updates for Rational Product Updater into your local mirror of the update server. Then, similar to the previous section (Creating a policy.xml file for updating the product), you need to configure Rational Product Updater to install its updates from your mirror site by creating a policy.xml file.

However, unlike the case in the previous section -- where Rational Product Updater can refer to a policy.xml file stored on a server on your network -- in this case Rational Product Updater must refer to a policy.xml file stored on the local file system (stored at <installdir>\updater\eclipse\configuration\policy.xml, where <installdir> is the installation directory for the Rational Software Development Platform product). Then, once Rational Product Updater has updated itself, the policy.xml file must be deleted from the local machine.

Therefore, for this scenario -- where you will use a batch file to automate the installation and update of the product on multiple machines over a network -- it is recommended that you create and store the policy.xml file for Rational Product Updater on the network server. Your batch file will copy the policy.xml file from the network server to the local file system running Rational Product Updater at the appropriate time, and then delete the policy.xml file when it is no longer needed.

To create a policy.xml file for Rational Product Updater:

1. On the network server, create and save a file named policy.xml. For example, create <network_drive>:\install_image\RPU\policy.xml.
2. Using a text editor, open policy.xml and enter the text shown in Listing 8.
   
   Listing 8. Contents of policy.xml file for Rational Product Updater that points to a local update site
   

   <?xml version="1.0" encoding="UTF-8"?> <update-policy> <!-- RPU Update Site --> <url-map pattern="com.ibm.orca.product.updater" url="http://<server1>/updates/rpu/60/update/site.xml"/> <url-map pattern="com.ibm" url=""/> </update-policy>

   
   

   Notes:

   1. You must replace <server1> with the name of your network server.
   2. This policy file assumes that, for the Rational Product Updater, you merged all site_<identifier>.xml files (or if there were only one site_<identifier>.xml file, renamed it) into a file named site.xml.
3. Save and close policy.xml.

Refer to the next section for information on silently updating Rational Product Updater.

Installing and updating the product silently

This section describes how to manually run a silent installation and silent update of an Eclipse-based Rational Software Development Platform product.

Installing the product silently

(Refer to your product's installation guide for more detailed information on silent installation.)

The general steps to silently install an Eclipse-based Rational Software Development Platform product from an installation image on a network drive are:

1. Connect to the network drive using the net use command.
2. Change to the disk1\setup directory in the directory containing the product installation image.
3. Run the installation program in silent mode. To add a response file as an argument, add the -options parameter and the fully qualified name of your response file. Refer to Creating a response file for the installation for information on using a response file during a silent installation.

   Important: If you are invoking the installation program using a batch file, you will need to call the JRE directly. Refer to Preparing a JRE for running the installation from a batch file for information on prerequisite steps for calling the JRE directly when installing the product.

Listing 9 shows commands for installing a product silently, with a response file and without calling the JRE directly:

net use x: \\server1 

x: 


cd install_image\disk1

setup.exe -silent -options
x:\install_image\disk1\util\modified_responsefile.txt

Listing 10 shows how to install a product silently by calling the JRE directly:

net use x: \\server1 

x: 

cd
install_image\disk1 

x:\install_image\IBMJRE\jre\bin\java.exe
-cp setup.jar -Dis.jvm.home="x:\install_image\IBMJRE" 
-Dis.jvm.temp="1"
 -Dis.media.home="x:\install_image\disk1\setup" 
 -Dis.jvm.file="x:\install_image\IBMJRE\jvm"
-Dis.external.home="x:\install_image\disk1"  -Xms48m -Xmx128m run
-silent -options x:\install_image\disk1\util\modified_responsefile.txt

Note that in this example, the JRE is located in a directory named \install_image\IBMJRE. Refer to Preparing a JRE for running the installation from a batch file for information on extracting a JRE for the installation program.

Updating the product silently

This section describes how to silently install updates for Rational Product Updater from a local update site, followed by updates for your Eclipse-based Rational Software Development Platform product.

As stated in Creating a policy.xml file for updating Rational Product Updater, updates for Rational Product Updater must be installed first and separately before installing updates for the product. If Rational Product Updater has already been updated to the latest version, then you would skip to Step 2 in the procedure.

To silently install updates for Rational Product Updater and an Eclipse-based Rational Software Development Platform product:

1. Update Rational Product Updater.
   1. Create the policy.xml file as per the instructions in Creating a policy.xml file for updating Rational Product Updater.
   2. Copy the policy.xml file to the <installdir>\updater\eclipse\configuration\ directory.
   3. From a command line, change to the directory <installdir>\updater\eclipse: cd <installdir>\updater\eclipse
   4. Enter the following command to install the updates for Rational Product Updater: jre\bin\java.exe -cp startup.jar org.eclipse.core.launcher.Main -auto

      The -auto command line option is used instead of the -installUpdates,because the initial version of Rational Product Updater did not have the -installUpdates option.

      When Rational Product Updater begins installing the update (for example, version 6.0.1.0h) it will produce output in the console stating that the update is being installed.

   5. After Rational Product Upater has been updated, delete the policy.xml file that you saved in the directory <installdir>\updater\eclipse\configuration\.
2. Update the product.
   1. Run the following command to silently install the product updates on your local mirror site (Important: you must have a connection to the network server in order for Rational Product Updater to use the policy.xml file): jre\bin\java.exe -cp startup.jar org.eclipse.core.launcher.Main -policyFile <ServerPath>\policy.xml -installUpdates

      Note that <ServerPath> is the path to the policy.xml file on a network server. (For example, \\server1\rational_updates\rad\.)

      Note also that if the policy.xml file is available on your intranet, then you could use the following command: jre\bin\java.exe -cp startup.jar org.eclipse.core.launcher.Main -policyURL <PolicyFileURL> -installUpdates

      In this case, <PolicyFileURL> is the URL of the policy.xml file (for example, http://server1/rational_updates/rad/policy.xml).

   2. Run the following command to install the latest optional features on your local mirror site: jre\bin\java.exe -cp startup.jar org.eclipse.core.launcher.Main -policyFile <ServerPath>\policy.xml -installFeatures

      Similar to the previous step, if the policy.xml file is available on your intranet you could use the -policyURL option instead of -policyFile.

Creating a batch file to automate the installation and update tasks

This section shows an example of a batch file that will automate the following three tasks:

1. Silently install the product from the installation image. A response file is used to override the default installation settings.
2. Silently update Rational Product Updater with the latest updates.
3. Silently update the product with the latest updates, and install new optional features.

The installation image, updates and optional features are located on the network server.

Listing 11 shows an example of a batch file that automates all three tasks:

@echo off 

set DRIVE=%1 



echo
Installing Product... 

%DRIVE% 

cd
 install_image\disk1 

%DRIVE%\install_image\IBMJRE\jre\bin\java.exe
-cp setup.jar 
-Dis.jvm.home="%DRIVE%\install_image\IBMJRE"  
-Dis.jvm.temp="1"
-Dis.media.home="%DRIVE%\install_image\disk1\setup" 
-Dis.jvm.file="%DRIVE%\install_image\IBMJRE\jvm"
-Dis.external.home="%DRIVE%\install_image\disk1"
 -Xms48m -Xmx128m run -silent -options  
 %DRIVE%\install_image\disk1\util\modified_responsefile.txt 



echo
Updating Rational Product Updater

xcopy  %DRIVE%\updates\RPU\policy.xml <installdir>
 \updater\eclipse\configuration 

cd <installdir>\updater\eclipse 

jre\bin\java.exe
-cp startup.jar org.eclipse.core.launcher.Main -auto 


del /f/q installation_directory\updater\eclipse\configuration\policy.xml 



echo
Updating Product



jre\bin\java.exe
-cp startup.jar org.eclipse.core.launcher.Main -policyFile  %DRIVE%\updates\policy.xml
-installUpdates

Notes:

• <install_image> is the directory on the network drive containing the installation image.
• <install_image>\IBMJRE is the directory on the network drive where the JRE was extracted.
• The response file is named rad_response.txt and is located in the \disk1\util directory of the installation image.
• The policy.xml file that has been created for Rational Product Updater is located on the network server in the updates\RPU directory.
• The product is installed on the local machine at <installation_directory>. You must change <installation_directory> in your batch file to the appropriate value. You could use either the default installation directory for the product or the value specified in the response file.
• The policy.xml file for the product updates and features is located in the updates directory on the network server.
• This batch file only installs product updates. To install optional features, you would need to add the following line: jre\bin\java.exe -cp startup.jar org.eclipse.core.launcher.Main -policyFile %DRIVE%\updates\policy.xml -installFeatures

If the batch file is name install.bat and is found at \\server1\install_image\, then enter the text in Listing 12 at a command line on the local machine to run the batch file:

net use x: \\server1 

x:\install_image\install.bat X: 

Now you know how to use a batch file to install and update a Rational Software Devolopment Platform product.

Resources

Learn

• Stay current with developerWorks technical events and Webcasts.
  
  

Get products and technologies

• IBM Rational Application Developer: Download a free trial version from developerWorks.
  
  
• Build your next development project with IBM trial software, available for download directly from developerWorks.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Participate in developerWorks blogs and get involved in the developerWorks community.
  
  
• Rational Software Architect, Data Architect, Software Modeler, Application Developer and Web Developer forum: Ask questions about these IBM Rational products.
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Preparing the server for the product installation
• Preparing the server for the product updates
• Installing and updating the product silently
• Creating a batch file to automate the installation and update tasks
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into Rational on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers