 |
Deploying Customized TPF Toolkit Updates using an Internal Update Site
|
| | | Abstract | Many administrators customize the TPF Toolkit product for the environment, setup, and processes that are used in their company. Initially, administrators can customize TPF Toolkit, and then deploy this customized version to users. However, when IBM provides an update for TPF Toolkit, administrators might want to make customizations to the update. For example, if a new feature is added to the product, administrators might want to customize the settings for this feature before deploying it to users. By using an internal update site, you can control which updates users receive. You can remove from, add to, and customize the update before deploying it to users.
This article provides TPF Toolkit administrators with guidance on customizing and deploying updates to users. It also provides background information helpful for creating an update site, explains the general steps for creating the update site, and then steps through a detailed example. | | | | | | Content |
Introduction
Overview of initial deployment
Overview of update site setup Install handler
Template for update site changes
What to customize on your update site
Creating an internal update site Create future updates
A detailed example Troubleshooting
Introduction
Many administrators customize the TPF Toolkit product for the environment, setup, and processes that are used in their company. Initially, administrators can customize TPF Toolkit, and then deploy this customized version to users. However, when IBM provides an update for TPF Toolkit, administrators might want to make customizations to the update. For example, if a new feature is added to the product, administrators might want to customize the settings for this feature before deploying it to users. By using an internal update site, you can control which updates users receive. You can remove from, add to, and customize the update before deploying it to users.
This article provides TPF Toolkit administrators with guidance on customizing and deploying updates to users. It also provides background information helpful for creating an update site, explains the general steps for creating the update site, and then steps through a detailed example.
This article was written when Interim Fix v2.0.8 was the most current update. Although many of the examples in this article are based on Interim Fix v2.0.8, the information generally applies to all Interim Fixes.
Back to Top
Overview of initial deployment
For the purposes of this article, it is assumed that when you initially deployed TPF Toolkit to users, you completed steps similar to the following:
1. Install the GA product using the install wizard.
2. Install the latest Interim Fix using the Update Manager.
3. Install the host components in a shared location.
4. Complete customizations, such as: - Creating custom actions and menus.
- Setting default preferences for compile and assemble options.
- Tailoring command headers and footers.
- Creating external tools actions.
- Customizing the help.
5. Set up a shared location for TPFSHARE.
6. Edit the TPFToolkit.bat file to set TPFHOME, TPFPROJ, TPFSHARE, and BBSHOME.
7. Clean up your workspace.
8. Zip up TPF Toolkit, including the workspace.
9. Unzip this file onto each workstation.
Back to Top
Overview of update site setup
An update site contains the following components: - site.xml file
- plugins directory
- features directory
Back to Top
site.xml file
The site.xml file lists the updates that are available on the update site. For example, the following site.xml file is displayed on the IBM TPF Toolkit for WebSphere Studio update site:
<?xml version="1.0" encoding="UTF-8" ?>
<site url="">
<description>IBM TPF Toolkit for WebSphere Studio Update Site.</description>
<feature id="com.ibm.tpf.toolkit" version="2.0.1" url="features/com.ibm.tpf.toolkit_2.0.1.jar">
<category name="toolkit 2.0.1"/>
</feature>
<feature id="com.ibm.tpf.toolkit" version="2.0.2" url="features/com.ibm.tpf.toolkit_2.0.2.jar">
<category name="toolkit 2.0.2"/>
</feature>
<feature id="com.ibm.tpf.toolkit" version="2.0.3" url="features/com.ibm.tpf.toolkit_2.0.3.jar">
<category name="toolkit 2.0.3"/>
</feature>
<feature id="com.ibm.tpf.toolkit" version="2.0.4" url="features/com.ibm.tpf.toolkit_2.0.4.jar">
<category name="toolkit 2.0.4"/>
</feature>
<feature id="com.ibm.tpf.toolkit" version="2.0.5" url="features/com.ibm.tpf.toolkit_2.0.5.jar">
<category name="toolkit 2.0.5"/>
</feature>
<feature id="com.ibm.tpf.toolkit" version="2.0.6" url="features/com.ibm.tpf.toolkit_2.0.6.jar">
<category name="toolkit 2.0.6"/>
</feature>
<feature id="com.ibm.tpf.toolkit" version="2.0.7" url="features/com.ibm.tpf.toolkit_2.0.7.jar">
<category name="toolkit 2.0.7"/>
</feature>
<feature id="com.ibm.tpf.toolkit" version="2.0.8" url="features/com.ibm.tpf.toolkit_2.0.8.jar">
<category name="toolkit 2.0.8"/>
</feature>
<feature id="com.ibm.tpftoolkit.doc.put18" version="2.0.6" url="features/com.ibm.tpftoolkit.doc.put18_2.0.6.jar">
<category name="toolkit doc put18 2.0.6"/>
</feature>
<category-def label="TPF PUT18 Documentation 2.0.6" name="toolkit doc put18 2.0.6"/>
<category-def label="TPF Toolkit 2.0.1" name="toolkit 2.0.1"/>
<category-def label="TPF Toolkit 2.0.2" name="toolkit 2.0.2"/>
<category-def label="TPF Toolkit 2.0.3" name="toolkit 2.0.3"/>
<category-def label="TPF Toolkit 2.0.4" name="toolkit 2.0.4"/>
<category-def label="TPF Toolkit 2.0.5" name="toolkit 2.0.5"/>
<category-def label="TPF Toolkit 2.0.6" name="toolkit 2.0.6"/>
<category-def label="TPF Toolkit 2.0.7" name="toolkit 2.0.7"/>
<category-def label="TPF Toolkit 2.0.8" name="toolkit 2.0.8"/>
<category-def label="Eclipse" name="eclipse"/>
</site>
|
This site.xml file contains an update for each Interim Fix, with each update in a separate category. Most of the updates are for the com.ibm.tpf.toolkit feature, but there is also an update for the com.ibm.tpf.tpftoolkit.doc.put18 feature. To restrict the updates that are available on your update site, remove any updates that you do not want to be available from the site.xml file. Since each update is cumulative, when users install the most recent update they also receive the content from all previous updates.
Back to Top
plugins directory
A plug-in contributes some type of functionality to TPF Toolkit. Many plug-ins work together to provide the features in TPF Toolkit. The plugins folder contains a .jar file for each plug-in that has changed in an update hosted on the site. If a plug-in has changed in multiple updates, there are multiple .jar files for that plug-in. Each time that a plug-in changes, the version number of the plug-in is updated. The .jar file for the plug-in contains the version number so that each .jar file name is unique. For example, on the IBM TPF Toolkit for WebSphere Studio update site, the following .jar files appear in the plugins directory: - com.ibm.tpf.installHandler_2.0.1.jar
- com.ibm.tpf.installHandler_2.0.2.jar
- com.ibm.tpf.installHandler_2.0.3.jar
- com.ibm.tpf.installHandler_2.0.3.1.jar
- com.ibm.tpf.installHandler_2.0.3.4.jar
- com.ibm.tpf.installHandler_2.0.5.jar
- com.ibm.tpf.installHandler_2.0.6.jar
- com.ibm.tpf.installHandler_2.0.7.jar
- com.ibm.tpf.installHandler_2.0.8.jar
Not every plug-in changes in every update. When the update site is created, all of the plugins and features required for TPF Toolkit are posted to the update site; for each future update, only the changed plug-ins need to be posted. When an update is applied, only the changed content is downloaded to users' machines. Updates are also cumulative. This means that if a user who did not apply 2.0.7 attempts to update to 2.0.8, and there is a plug-in that was changed in 2.0.7 and not 2.0.8, then the 2.0.7 version of the plug-in is downloaded when the user applies 2.0.8.
Back to Top
features directory
A feature is used to group plug-ins. A feature can also include other features. The update site uses features as the basis of updates. The features directory includes a .jar file for each feature that is required by one of the updates available on the site. Each feature has a feature.xml file that contains information about that feature. Each time a feature or plug-in within a feature changes, the version number of the containing feature is updated. Each feature.xml file lists the plug-in versions and feature versions included in the feature. In TPF Toolkit, the main feature that includes all other required features is called com.ibm.tpf.toolkit. The feature.xml file within a feature is used to list all required features and plug-ins. For example, since the main TPF Toolkit feature requires the LPEX feature, the %TPFHOME%\eclipse\features\com.ibm.tpf.toolkit_2.0.8\feature.xml file contains the following:
<includes
id="com.ibm.lpex"
version="1.4.8"
match="equivalent"/>
Since the main TPF Toolkit feature also requires the com.ibm.tpf.menumanager plug-in, the %TPFHOME%\eclipse\features\com.ibm.tpf.toolkit_2.0.8\feature.xml file also contains the following:
<plugin
id="com.ibm.tpf.menumanager"
download-size="0"
install-size="0"
version="2.0.7"/>
The com.ibm.tpf.toolkit feature also includes other features and plug-ins. For each feature and plug-in that is included, a version number is mentioned. When users access the update site to update a feature, the feature.xml file is used to decide what needs to be downloaded to the user's machine. For example, the com.ibm.tpf.toolkit feature.xml file mentions that the com.ibm.lpex feature is required at version 1.4.8. If the user does not already have version 1.4.8 of the com.ibm.lpex feature, it is downloaded and installed when they update from this update site.
Not all plug-ins and features are changed in an update. Plug-ins and features that have not been updated are not downloaded to a user's machine when they update. However, the update site must include each feature and plug-in that is required for the update in case the user did not install the previous update and does not have the required version.
The site.xml file specifies which features a user can update using the update site. In the case of TPF Toolkit, all of the updates are based on different versions of the main feature, com.ibm.tpf.toolkit. A main feature is used to encompass all of the other features and plug-ins so that users are only required to update one feature when they udpate from the update site. This prevents users from updating different fragments of the product at different levels.
Back to Top
Install handler
When a user applies an update from an update site, the feature that they install might have an associated install handler. An install handler runs when the user installs or updates the feature. In TPF Toolkit, the install handler does the following: - Copies changed files to the refresh directory.
- Migrates LPEX preference files from the old location to the new location (since 2.0.4).
- Migrates Menu Manager configuration files from the old location to the new location (since 2.0.4).
When you create an update site, you can reuse the TPF Toolkit install handler to move your own files around on a user's machine. You can customize the TPF Toolkit install handler by modifying the following files: - ENT_workstation_copy_list.txt - This file specifies the files that you included on the update site (in the install handler feature .jar file) and want to copy to any location on the user's workstation. You can add a line to this file for each file that you want to copy. You can use environment variables to specify the locations where these files should be moved. You can also use the special %WORKSPACE% variable in paths if you want to copy something into the user's workspace. You can use this file to copy external tools actions to a user's workspace or create backups on a user's machine. For example, to provide custom LPEX preferences to a user, you can use this file to back up their current preferences, and then copy your LPEX preference file to their workspace.
- ENT_host_copy_list.txt - Similar to ENT_workstation_copy_list.txt, this file also contains a list of files that you want to copy. However, you should use this file to copy files to the user's workstation that you want the user to transfer to the host system. Although it is recommended that you use a shared location for host files, you can use this file to transfer updates to the host files. However, users must still promote the files from their workstation to the host system.
- ENT_delete_list.txt - Using this file, you can delete files and folders from a user's machine. For example, if you deployed a user exit in a previous installation that you no longer require, you can use this file to remove the old user exit.
- ENT_feature_delete_list.txt - This file allows you to delete features from a user's machine. For example, if your company previously used PUT 15, but is now using PUT 16, you can use this file to delete the PUT 15 help since it is no longer required.
Each plug-in and feature has a .jar file on the update site. When you customize the install handler, you can add files to the .jar that you want to copy to users' workstations.
When a customized install handler runs, the following actions occur:
1. Copy all required plug-ins and features to the user's machine.
2. Run install handlers of included features - any customized feature that you deploy includes the TPF Toolkit feature. When your customized feature is installed, the TPF Toolkit feature is installed first, and then the TPF Toolkit install handler runs to completion.
3. Copy files and folders listed in ENT_workstation_copy_list.txt.
Note: If a file or folder is copied to a destination where that file or folder already exists, the original file or folder is deleted and replaced by the version being copied from the install handler. For example, if you deploy custom help in one update, and then ship new versions of the help files, the old help files are replaced by the new versions.
4. Copy files and folders listed in ENT_host_copy_list.txt.
Note: If a file or folder is copied to a destination where that file or folder already exists, the original file or folder is deleted and replaced by the version being copied from the install handler.
5. Delete files and folders listed in ENT_delete_list.txt.
6. Delete features listed in ENT_feature_delete_list.txt.
Back to Top
Template for update site changes
Templates are provided to help you create a customized update site. You can use these templates to customize Interim Fix 2.0.8 and above. Using these templates, you can customize Interim Fix updates without modifying the IBM provided features and plug-ins. The templates use a new feature called com.ent.customized.toolkit to wrap the IBM provided com.ibm.tpf.toolkit feature and your customizations. The com.ent.customized.toolkit feature includes the com.ibm.tpf.toolkit feature, a new com.ent.customized.installHandler feature, and a com.ent.customized.toolkit plug-in for you to customize.
In the provided templates, set up the following: - com.ent.customized.toolkit feature
- com.ent.customized.toolkit plug-in
- com.ent.customized.installHandler features
com.ent.customized.toolkit feature
This feature will become the primary feature for TPF Toolkit. The primary feature determines the branding aspects of the product, such as the splash screen and the welcome page. The template provides a special TPFToolkit.bat file that starts TPF Toolkit using the com.ent.customized.toolkit feature as the primary feature. The advantage of creating a custom primary feature is the ability to set the update site URL for future updates and to customize the welcome page.
The com.ent.customized.toolkit feature is based on the com.ibm.tpf.toolkit feature, however, the following changes have been made:
- It was given version number V.R.M.1, where V.R.M is the Interim Fix version, release, and modification number. For example, if you use the 2.0.8 template to customize Interim Fix 2.0.8, the com.ent.customized.toolkit feature is given version number 2.0.8.1. If you make multiple customizations to Interim Fix 2.0.8, you must increment the last digit each time that you deploy additional customizations.
- It was updated to require the corresponding version of the com.ibm.tpf.toolkit feature. For example, if you use the 2.0.8 template to customize Interim Fix 2.0.8, the com.ent.customized.toolkit feature requires version 2.0.8 of the com.ibm.tpf.toolkit feature.
- It was updated to require the com.ent.customized.toolkit plug-in.
- It was updated to require the com.ent.customized.installHandler feature.
- The update site URL was updated to point to the internal update site. In the template, the internal update site is set to file:\C:\CompanyUpdateSite. To change this to the address of the internal update site that you want to use, search for this address, and then replace it with the address of your internal update site.
- The plugin attribute was changed to reference the com.ent.customized.toolkit plug-in.
- All the % variables in feature.xml were replaced with values so that a feature.properties file is not required.
com.ent.customized.toolkit plug-in
This plug-in provides all of the information required to support the primary feature. It contains product images, content for the about dialog, and the welcome.xml file for the welcome page. The com.ent.customized.toolkit plug-in is based on the com.ibm.tpf.toolkit plug-in, however, the following changes have been made:
- It was assigned version number V.R.M.1, where V.R.M is the Interim Fix version, release, and modification number. For example, if you use the 2.0.8 template to customize Interim Fix 2.0.8, the com.ent.customized.toolkit plug-in is assigned version number 2.0.8.1.
- All the % variables were replaced with values so that a plugin.properties file is not required.
- The plug-in customization content was deleted. Plug-in customization data controls items such as the default perspective that should not be changed. Although the primary plug-in usually specifies the plug-in customization data, you do not need to customize that data; the TPFToolkit.bat file will be updated with a command line option to reuse the plug-in customization files from the com.ibm.tpf.toolkit plug-in.
com.ent.customized.installHandler features
This feature provides an install handler that is run when users apply updates for the com.ent.customized.toolkit feature. You can customize the install handler to install additional files, as required. The com.ent.customized.installHandler feature is based on the com.ibm.tpf.installHandler feature, however, the following changes have been made:
- The feature id was changed to com.ent.customized.installHandler.
- The plugin attribute was removed from the feature.xml file.
- The plugin element was removed from the feature.xml file.
- All the % variables in the feature.xml file were replaced with values so that a feature.properties file is not required.
- The IBM_workstation_copy_list.txt, IBM_host_copy_list.txt, and IBM_delete_list.txt files (and all files referenced by these files) were removed.
- The com.ent.customized.installHandler was given version number V.R.M.1, where V.R.M is the Interim Fix version, release, and modification number. For example, if you use the 2.0.8 template to customize Interim Fix 2.0.8, the com.ent.customized.toolkit plug-in is assigned version number 2.0.8.1.
- The ENT_feature_delete_list.txt file was updated to delete the Administrator feature.
- A customized TPFToolkit.bat file was added so that it can be copied to the user's machine.
Note: The provided TPFToolkit.bat file contains the following:
@echo off
rem (C) Copyright IBM Corp. 2003, 2004
set TPFHOME=%~d0%~p0
set TPFPROJ=%TPFHOME%Config\project
set TPFSHARE=%TPFHOME%Config\TPFSHARE
set BBSHOME=%TPFHOME%Config\bin
start /MIN /D"%~d0%~p0eclipse" eclipse.exe -feature com.ent.customized.toolkit -plugincustomization .\plugins\com.ibm.tpf.toolkit_2.0.8\plugin_customization.ini -vmargs -Xj9 -Xmx256M
The items specified in blue are not included in the original TPFToolkit.bat file shipped with TPF Toolkit. These new items are:
- set TPFHOME - sets the TPFHOME variable to the directory where TPFToolkit.bat resides. This is useful if you installed TPF Toolkit using the "unzip" method and did not set environment variables at the system level.
- set TPFPROJ, set TPFSHARE - sets the TPFPROJ and TPFSHARE variables to the default locations. If you use a shared location for TPFSHARE, modify the setting here. If you already set these variables as environment variables on the user's machine, you are not required to set these variables in TPFToolkit.bat.
- set BBSHOME - sets the BBSHOME environment variable so that the Performance Analyzer can be used. If this variable is already set as an environment variable on the user's machine, you do not need to set this variable.
- -feature - this option specifies the name of the feature that will be used as the primary feature.
- -plugincustomization - this option specifies where the plugin customization settings should be picked up from. By default, they are picked up from the primary feature. However, you have not customized these settings and want to use the settings from the com.ibm.tpf.toolkit plug-in.
Warning: When you make customizations in TPFToolkit.bat and a user applies an update that contains these changes, the changes do not take affect until the user manually restarts TPF Toolkit. The restart that is performed as part of the update wizard does not use the new TPFToolkit.bat file when restarting.
- The ENT_workstation_copy_list.txt file was updated to copy the TPFToolkit.bat file to the user's workstation.
When using the template to customize an Interim Fix for the first time, complete the following steps:
1. Add the files that you want to copy to the user's machine to the com.ent.customized.installHandler feature.
2. Update the ENT_workstation_copy_list.txt file to copy the files that you added to the install handler.
3. Set the update site URL in the feature you are deploying to the location where users will get your customized updates.
4. Update your com.ent.customized.toolkit feature to include references to other plug-ins and features that you want to include in your update.
5. Customize the ENT_delete_list.txt and ENT_feature_delete_list.txt files in com.ent.customized.installHandler to remove any files and features that users do not require.
6. JAR the features you modified, and then place them on your update site.
7. Update the site.xml file on your update site to include your customized update.
Back to Top
What to customize on your update site
All customizations in TPF Toolkit are dictated by a particular file being in a particular location. When you apply an update, you must ensure that all of the appropriate files are placed in the correct locations. In TPF Toolkit, items are stored in four possible locations:
- TPFSHARE
- Workspace
- Plugins
- Other
You can create a customized install handler to move the appropriate files to the appropriate locations. The following list summarizes how to manage updating files in these locations:
- TPFSHARE stores items such as TPF Toolkit preferences, customized header and footer files, customized action files, user exits, and Menu Manager configuration files.
Network TPFSHARE location: When IBM provides an Interim Fix, complete the following steps: 1. Install the Interim Fix and complete your customizations.
2. Copy all of the TPFSHARE files to your network TPFSHARE location, replacing any existing versions with new versions. Since all user workstations point to the network location for TPFSHARE files, they automatically get the customizations. Local TPFSHARE location: When IBM provides an Interim Fix, complete the following steps: 1. Install the Interim Fix and complete your customizations.
2. Customize the install handler so that it copies all of the files from your TPFSHARE directory to the TPFSHARE directory on each user's workstation.
You might also want to customize the install handler so that it creates a backup of all of the users' TPFSHARE files before you overwrite their files with your changes. When a user applies your customized update, the new files are copied to their workstation. - The workspace stores items such as external tools actions, workbench preferences, RSE preferences, and debug preferences.
For customizations that are stored in the workspace, you must determine which files you changed in the update, and then customize the install handler to copy the changed files to the user's workspace. It is highly recommended that you back up any files you are replacing so that you do not inadvertently erase a user's customizations.
- Plugins store items such as the custom help, a customized welcome page, and the URL for update lookups.
Move the files and folders that contain your customizations by customizing the install handler.
- Other locations store items such as the TPFToolkit.bat file.
For customizations that are stored in other locations, you must determine which files you changed in the update, and then customize the install handler to copy the changed files to the correct location on the user's workstation.
The following table provides a list of files that you might change as part of your customization:
| Location | File Name | Content | | TPFSHARE |  | <User Exits> | If you created user exits to run when a user creates projects or submits a JCL, these exits should be stored in TPFSHARE. | | <Custom Action Files> | If you created custom actions and menus in the Menu Manager, the files that contain these actions and menus should be stored in TPFSHARE. | | bbshtpf.bbs
bbsftpf.bbs
bbshcmd.bbs
bbsfcmd.bbs | These files store commands to be run when a remote action is run. | | ENTDeleteConfig.xml. | If you used the Administrator preferences page (TPF Toolkit > Administrator) to remove IBM provided action files, the settings are stored in this file. | | ENTActionsConfig.xml | If you promoted your custom action files from the Administrator preferences page (TPF Toolkit > Administrator), the settings are stored in this file. | | tpfhlasm.dat | If you deleted macro definitions provided by IBM, they are deleted from the tpfhlasm.dat file. | | <Macro Definition File> | If you created custom macro definitions for the TPF HLAsm Parser, the files that contain these definitions should be stored in TPFSHARE. | | TPFPROJ | | tpf_pref.xml | This file stores all changes made in the following TPF Toolkit preference pages: - TPF Toolkit
- TPF Toolkit > Build Mechanism
- TPF Toolkit > Build Target
- TPF Toolkit > Default Build Actions
- TPF Toolkit > Loadset Systems
- TPF Toolkit > Menu Manager *
- TPF Toolkit > Remote Assemble
- TPF Toolkit > Remote Compile
- TPF Toolkit > TPF Make Configuration
- TPF Toolkit > User Variables and Exits
* Actions and menus created using the Menu Manager are stored in separate files. The list of files known to the Menu Manager is also stored in a separate configuration file.
Tip: TPF Toolkit combines values from %TPFPROJ%\tpf_pref.xml and %TPFSHARE%\tpf_pref.xml to create the preference settings. Settings in %TPFPROJ%\tpf_pref.xml override settings in %TPFSHARE%\tpf_pref.xml.
When TPF Toolkit ships, %TPFSHARE%\tpf_pref.xml contains IBM provided defaults for all of the preferences. As you make customizations, your customizations are stored in %TPFPROJ%\tpf_pref.xml. When you deploy preference settings to users, replace the IBM provided defaults in %TPFSHARE%\tpf_pref.xml with your customizations. To prevent having to merge your %TPFPROJ%\tpf_pref.xml and the IBM provided defaults in %TPFSHARE%\tpf_pref.xml, place a copy of the IBM provided tpf_pref.xml in the %TPFPROJ% folder, and then make your customizations. When you deploy your preference settings, users will receive your customizations, as well as the IBM defaults for any values that you did not change. | | sysprop.xml | System level properties. | | Workspace | | ...\.metadata\.plugins\com.ibm.etools.systems.core\fileTransferMode.xml | This file stores changes made in the Files preferences page (Remote Systems > Files). For example, if you create a new file type, and then associate that file type with the binary transfer mode, it is stored in this file. | | ...\.metadata\.plugins\org.eclipse.ui.workbench\pref_store.ini | This file stores changes made in the File Associations preferences page (Workbench > File Associations). For example, if you add a new file type, and then associate it with the TPF Toolkit LPEX editor, it is stored in this file. | | ...\.metadata\.plugins\com.ibm.lpex\Editor.properties | This file stores all changes made in the following preference pages:
- LPEX Editor > Parsers > Parser Associations
- LPEX Editor > Parsers > TPF C/CPP Parser
- LPEX Editor > Parsers > TPF HLAsm Parser
For example, if you add commands that you want to run each time a file is opened with the TPF HLAsm Parser, these commands are saved in this file. Also, if you create custom macro definitions for the TPF HLAsm Parser, the name of the file that contains these customizations is stored in this file. | | ...\.metadata\.plugins\com.ibm.lpex\auto_comment.properties | Stores changes made to the auto comment settings using the Auto Comment preferences page (LPEX Editor > TPF LPEX Editor > Auto Comment). | | ...\.metadata\.plugins\org.eclipse.debug.core\.launches folder | Stores any External Tools actions that you create. | | ...\.metadata\.plugins\org.eclipse.debug.ui\launchConfigurationHistory.xml | Stores a history of the External Tools actions that exist on the External Tools menu. | | Plug-ins | | com.ibm.tpf.custom.doc | Stores custom help. | | Other | | TPFToolkit.bat | Stores additional options to use when launching TPF Toolkit, environment variable settings, etc.
Warning: If you make customizations in TPFToolkit.bat, and then a user applies an update containing these changes, the changes do not take affect until the user manually restarts TPF Toolkit. The restart that is performed as part of the update wizard does not use the new TPFToolkit.bat file when restarting. | | | |
Back to Top
Creating an internal update site
Back to Top
Step 1 - Populate the update site with IBM provided updates
Before you can customize the update site, you must initially populate the update site with the IBM provided versions of all plug-ins and features. Once you have all of the IBM provided versions, users can use your site to apply updates supplied by IBM.
You have two options for choosing an update site location:
1. An internal web site - If you host the update from a web site, users can update by selecting Help > Software Updates > New Updates.
2. A local folder - You can host an update site from your workstation. When users apply an update, they set up a mount point to the location on your machine that contains the update, and then apply the update from this location. Even if you plan to use an internal web site to host your update site, it is recommended that you use a local folder first for testing purposes. Once you test the update, you can move it from your local testing folder to the actual internal web site.
To create your initial update site:
1. Create a folder named <CompanyUpdateSite> on your workstation.
2. Unzip the following into the <CompanyUpdateSite> folder:
IBM Provided Update Site Content (2.0.8)
3. Unzip one of the following into the <CompanyUpdateSite> folder:
IBM Provided Update Site Delta (2.0.10)
IBM Provided Update Site Delta (2.0.11)
IBM Provided Update Site Delta (2.0.12)
For example, if you are customizing Interim Fix v2.0.10, use the 2.0.10 delta.
You now have an update site that can be used to apply the Interim Fix update as provided by IBM. If you want to test the update site at this point, complete the following steps:
1. Open an installation of TPF Toolkit that has not been updated to the Interim Fix that you are customizing. If you do not have such an installation, you can create one by installing the GA version of TPF Toolkit without applying any updates.
2. In the workbench, select Window > Open Perspective > Other > Install/Updates to open the Install / Update perspective.
3. In the Feature Updates view, expand the My Computer node and locate the <CompanyUpdateSite> folder that you created.
4. Expand the TPF Toolkit <V.R.M> category and double-click the IBM TPF Toolkit for WebSphere Studio <V.R.M> update.
Note: <V.R.M> is the version, release, and modification number of the Interim Fix that you want to customize.
5. In the Preview view, click Update Now.
6. Follow all instructions to apply the update and restart TPF Toolkit.
7. To verify that the update was installed, select Help > About IBM TPF Toolkit for WebSphere Studio and look at the feature details.
Back to Top
Step 2 - Customize the install handler
Now that you have an update site that contains the IBM provided updates, you can customize the update. In this step, you can modify the install handler so that it moves all of your customized files to the correct locations. The recommended steps for modifying the install handler are:
1. Unzip one of the following files to provide a starting point for your customized update:
Customization Template (2.0.8 Based)
Customization Template (2.0.10 Based)
Customization Template (2.0.11 Based)
Customization Template (2.0.12 Based)
When you unzip this file, a MyCustomizedUpdate folder is created. This folder contains the base for your update.
2. Change the internal update site URL to the address of the internal update site that you are using:
- You can specify the location of your update site as the location where TPF Toolkit checks for future updates. TPF Toolkit checks for updates when you select Help > Software Updates > New Updates.
- To set the location where TPF Toolkit should look for updates, modify the feature.xml file in the <MyCustomizedUpdate>\features\com.ent.customized.toolkit\feature.xml file. In the feature.xml file, locate the following line, and then modify it to point to your internal update site:
<url>
<update label="Customized TPF Toolkit Update Site" url="file:C:\CompanyUpdateSite\"/>
</url>
Note: In the template, the example assumes that the internal update site is hosted on a workstation and file: is used to specify a drive letter path. If you host your update site on a web site, use an http address. For example, the following URL points to the IBM update site:
<url>
<update label="TPF Toolkit Update Site" url="http://www3.software.ibm.com/ibmdl/pub/ps/products/tpftoolkit/updates/"/>
</url>
If you want users to mount your update site using the U drive letter, specify the URL as:
<url>
<update label="Customized TPF Toolkit Update Site" url="file:U:\"/>
</url>
3. Copy each file or folder that you customized into the <MyCustomizedUpdate>\features\com.ent.customized.installHandler folder. For example, copy your custom help plug-in, external tools .launch files, and LPEX preferences.
4. In a text editor, open the ...\<MyCustomizedUpdate>\features\com.ent.customized.installHandler\ENT_workstation_copy_list.txt file.
5. For each file or folder that you want to move to a user's machine, add a line to the ENT_workstation_copy_list.txt file to move the file or folder to the desired location. The format for this line is:
<relative file or folder name>=<absolute folder path of destination folder>
Note: You can use environment variables, such as %TPFHOME%. You can also use the %WORKSPACE% substitution variable to get the full path of the user's workspace.
For example, if you add a file named My Setup New Project.launch that you want to copy to the user's workspace, type:
My Setup New Project.launch=%WORKSPACE%\.metadata\.plugins\org.eclipse.debug.core\.launches
6. Save the ENT_workstation_copy_list.txt file.
The com.ent.customized.installHandler feature has now been customized to move your files.
Back to Top
Step 3 - Add additional plug-ins
As of Interim Fix 2.0.5, the PUT level specific help is shipped as separate features that must be installed separately from the Interim Fix updates. If your company uses a particular PUT level, you can add that to the update so that users do not need to install it as a separate update.
In the customization template that you unzipped in Step 2: Customize the install handler, a feature was created to list all of the items that your customized update requires. This feature is named com.ent.customized.toolkit; the feature.xml initially contains the following content:
<?xml version="1.0" encoding="UTF-8"?>
<feature
id="com.ent.customized.toolkit"
label="IBM TPF Toolkit for WebSphere Studio (Customized)"
version="2.0.8.1"
provider-name="Enterprise"
plugin="com.ent.customized.toolkit"
os="win32"
ws="win32"
arch="x86"
image="wsFeat.gif"
primary="true"
application="org.eclipse.ui.workbench">
<description>
IBM TPF Toolkit for WebSphere Studio (Customized)
</description>
<license url="license.html">
Feature License Agreement
Use of this feature is subject to the same terms and conditions which govern the use of the Product which included this feature.
</license>
<url>
<update label="Customized TPF Toolkit Update Site" url="file:C\CompanyUpdateSite"/>
</url>
<includes
id="com.ibm.tpf.toolkit"
version="2.0.8"
match="equivalent"/>
<includes
id="com.ent.customized.installHandler"
version="2.0.8.1"/>
<plugin
id="com.ent.customized.toolkit"
download-size="0"
install-size="0"
version="2.0.8.1"/>
</feature> |
This feature currently includes two other features, com.ibm.tpf.toolkit and com.ent.customized.installHandler. It also includes the com.ent.customized.toolkit plugin. If you want your com.ent.customized.toolkit feature to install a PUT level help feature, you can add an includes item to the ...features\com.ent.customized.toolkit\feature.xml file. For example, if you want to add the PUT 16 help feature, add the following includes element to the feature.xml file:
<includes
id="com.ibm.tpftoolkit.doc.put16"
version="2.0.5"/>
Including the PUT 16 help feature ensures that the update manager will install the PUT 16 help feature on a user's machine when the user installs your customized feature (com.ent.customized.toolkit) from the internal update site.
If your feature requires a PUT level help feature, you must add the appropriate .jar files for the PUT level help that your feature requires. The following list provides the PUT help JAR files:
Unzip the required PUT help JAR files into your internal update site. For example, if you require PUT 18 help, and your internal update site is C:\MyCompanyUpdateSite, then unzip the put18help.zip file into C:\MyCompanyUpdateSite. Two new JAR files are added to the C:\MyCompanyUpdate site folder: \features\com.ibm.tpftoolkit.doc.put18_<V.R.M>.jar and \plugins\com.ibm.tpf.doc.put18_<V.R.M>.jar.
Tip: If you choose which PUT level help to include, you should also set the TPF HLAsm Parser preferences to use the PUT level help that you installed. If you do not complete this setp, users will not be able to access the F1 help in the parser. To set the PUT level in the parser, complete the following steps:
1. Open an assembly file in the TPF Toolkit LPEX editor.
2. In the workbench, select Window > Preferences to open the Preferences window.
3. In the left navigation pane, double-click the LPEX Editor node to open the tree of available preferences pages.
4. Double-click the node for the assembly file you currently have open.
5. Click TPF HLAsm Parser to open the TPF HLAsm Parser preferences page.
6. From the PUT Level drop-down list, set the PUT level.
7. Click Use as custom defaults, and then click OK to save your changes.
8. Add the .....workspace\.metadata\.plugins\com.ibm.lpex\Editor.properties file to your custom install handler (<MyCustomizedUpdate>\features\com.ent.customized.installHandler).
9. Update the ENT_workstation_copy_list.txt file to copy the file to the user's machine. Note: It is recommended that you use the ENT_workstation_copy_list.txt file to back up the user's copy of the file before replacing it.
If you created your own plug-ins (such as a plug-in for the custom help, an LPEX user action, or a plug-in to contribute buttons to the toolbar), you need to deploy these plug-ins. There are two methods for deploying additional plug-ins: - Customize the install handler to copy the folder that contains your plug-in to the plugins directory.
- Version your plug-in and add it to the update. Although creating versions for your plug-in is more work, it makes it possible for users to apply an update, and then later remove the update and restore a previous version. If you have done all the work to create a plug-in, changing the version will seem simple.
If you want to ship a version of your plug-in as part of the update, complete the following steps:
1. In your plugin.xml file, set a version for your plug-in. Since this is the first time that you are shipping this plug-in, you can choose any version number. However, it makes sense to use the same version number that you used for the com.ent.customized.toolkit feature (e.g. 2.0.8.1).
2. Package your plug-in for the update site. The easiest way to do this is from the Plug-in Development perspective: - Right-click your project and select Export > Deployable Plug-ins and Fragments from the pop-up menu.
- In the wizard, choose Individual JAR archive for the Update site.
- Select the plugins folder of your update site as the location for the .jar file.
- Update the com.ent.customized.toolkit feature to require your plug-in. Open ...\<MyCustomizedUpdate>\features\com.ent.customized.toolkit\feature.xml and add a reference for your plugin in the following format:
<plugin
id="com.example.something"
download-size="0"
install-size="0"
version="2.0.8.1"/>
You have now added your deployable plug-in to the update site and updated the main toolkit feature to reference your plug-in so that it is included in the update.
Back to Top
Step 4 - Remove unnecessary plug-ins and files
There might be certain IBM provided plug-ins that you do not want users to have. For example, you might not want users to have the Administration feature that contributes the Administration preferences pages. You can remove these plug-ins and features from the user's workstation by customizing the ...\<MyCustomizedUpdate>\features\com.ent.customized.installHandler\ENT_feature_delete_list.txt file to include the ID of any feature that you want to delete. In the sample template, the Administration feature is already set up to be deleted. The following lines in ENT_feature_delete_list.txt file delete the Administration feature and plug-ins:
com.ibm.tpf.administrator
Another example of when you might want to delete a feature is if you shipped a feature in a previous update that you do not want users to use anymore. You can use ENT_feature_delete_list.txt file to remove the feature and associated plug-ins. For example, if you shipped the PUT 16 help in a 2.0.8.1 update, you might want to remove the PUT 16 help and ship the PUT 17 help in a subsequent update. To remove the PUT 16 help, add the following lines to the ENT_feature_delete_list.txt file:
com.ibm.tpftoolkit.doc.put16
If you use a shared location for remote host files, you can also delete the host files that are copied to the user's workstation for them to upload. The following line has already been added to the ENT_delete_list.txt file in the template to accomplish this:
%TPFHOME%\Config\host
Notes: - You must use the ENT_feature_delete_list.txt file to delete features; ENT_delete_list.txt is only used to delete files or folders. If you use ENT_delete_list.txt to delete plug-in or feature folders, it causes problems when a user tries to apply future updates using the update manager.
- Most features cannot be removed because they are required by TPF Toolkit. In TPF Toolkit, any feature that is not mentioned in the com.ibm.tpf.toolkit feature is not required and can be removed. For example, the PUT level help features are not mentioned in the com.ibm.tpf.toolkit feature because they are standalone features that can be deleted.
Tip: The Administrator feature and all PUT level help features are safe to delete. However, if you delete something other than these features, you should verify that you have not created an invalid configuration. If TPF Toolkit has an invalid configuration, updates cannot be applied. To verify if TPF Toolkit has a valid configuration, apply your custom update that removes features, and then check for errors in the Install\Update perspective. If you can expand all items in the current configuration and view the details in the Preview view without seeing the Problem Occurred dialog box, then the current configuration is valid. The following example displays an invalid configuration:
- The id for a feature is the value of the id attribute in the feature.xml file of that feature. To find the id of an installed feature, complete the following steps:
1. From the main menu bar, select Help > About IBM TPF Toolkit for WebSphere Studio.
2. Click Feature Details.
3. Use the ID found in the Feature Id column.
Back to Top
Step 5 - Push changes to update site
The sample template contains batch files to prepare the required .jar files for the update site. To use these batch files, complete the following steps:
1. Install a Java SDK.
2. Change the path "C:\Program Files\IBM\Java141\bin" in prepareupdate.bat to the location where your Java SDK is installed.
These script files create the necessary JAR files for your update site. To run the tool, do the following:
1. From a command prompt, cd to the ..\<MyCustomizedUpdate> directory.
2. Run the command by typing:
prepareupdate <versionNumber> <localUpdateSiteFolder>
For example:
prepareupdate 2.0.8.1 C:\CompanyUpdateSite
Note: If your output folder contains spaces in the name, you need to put quotes around the argument. For example:
prepareupdate 2.0.8.1 "D:\Company Update Site"
After the command runs, the new .jar files appear in your update site folder.
Note: If you do not want to install a Java SDK, you can JAR the files yourself. You must name the JAR files using the following format:
<feature or plug-in id>_V.R.M.C.jar
Where: - <feature or plug-in id> matches the id attribute in the plugin.xml or feature.xml file for which you are creating the .jar.
- V.R.M.C is the IBM Version, Release, and Modification and C is your customization number. For example, if you want to jar the com.ent.customized.toolkit feature included in the template and this is your first customization on 2.0.8, create a jar named com.ent.customized.toolkit_2.0.8.1.jar.
The JAR files should contain the content that appears in the folder for the plug-in or feature.
To create a .jar file for the com.ent.customized.toolkit feature, complete the following steps:
1. Open the C:\MyCustomizedUpdate\features\com.ent.customized.toolkit folder.
2. Select all of the files in the com.ent.customized.toolkit folder.
3. Add the selected files to a .jar file named com.ent.customized.toolkit_V.R.M.C.
Where V.R.M.C. is the IBM Version, Release, and Modification and C is your customization number.
The contents of the JAR file should be similar to the following:
Now that all of your changed plug-ins and features are in your update site folder, the last thing you need to do is to update the site.xml file to mention your new update. This site.xml file indicates which updates are available on your update site. Typically, you want your site to only contain the most recent update so that there is no confusion as to which update users should apply. A site.xml file that lists the 2.0.8.1 update is available from the CustomizedDelta folder in the template. If you want your update site to only contain the 2.0.8.1 update, copy this file to your <CompanyUpdateSite> folder.
If this is not your first customization and you want to include both updates on your update site, add a new category and a new update in this category:
1. In a text editor, open ...<CompanyUpdateSite>\site.xml.
2. At the end of the file, add a category for your new update. For example, to add a category for a 2.0.8.2 update, add the following:
<category-def
label="TPF Toolkit 2.0.8.2"
name="toolkit 2.0.8.2"/>
3. Before the categories are listed in the file, add an entry for the updated feature that users can now update. For example, to allow users to download com.ent.customized.toolkit at version 2.0.8.2, add the following:
<feature
id="com.ent.customized.toolkit"
version="2.0.8.2"
url="features/com.ent.customized.toolkit_2.0.8.2.jar
<category name="toolkit 2.0.8.2"/>
</feature>
Note: The category name matches the name you used for the category in step 2.
4. Save the changes to the site.xml file.
Back to Top
Step 6 - Test the update site
Now that the update site has all of the required changes, you can test the update site by completing the following steps:
1. Create a copy of the installation that you initially deployed to your users.
2. Look for updates on your update site by doing one of the following: - If this is the first update that you created:
a. Select Window > Open Perspective > Other > Install/Update to open the Install/Update perspective.
b. In the Feature Updates view, expand the My Computer node and locate your <CompanyUpdateSite> folder.
c. Expand the categories within <CompanyUpdateSite> and locate the category that you created.
Note: All of the features that are included by your customized feature are displayed when you expand your update. For example, your feature includes the main com.ibm.tpf.toolkit feature which includes all of the other features and plug-ins required for TPF Toolkit. Your feature also includes your customized install handler and any PUT level features that you added.
d. Open the page for your update and click Update Now to apply the update. - If this is not the first update that you customized and you set up an update site URL that points to a web site, use the method described above to get the update from your local machine.
- If this is not the first update that you customized and you set up an update site URL that points to the location where you placed your update, use Help > Software Updates > New Updates to get your update.
3. Once you apply the update and restart TPF Toolkit, ensure your customizations are there.
Tip: If any of the files that should be moved by the install handler were not moved, check the TPFToolkitInstallHandler.log file. This file is located in the backup directory in the location where TPF Toolkit is installed.
Back to Top
Creating future updates
You might want to create another update for your update site in the following scenarios:
1. IBM ships a new Interim Fix.
2. Your company makes changes. For example, your company was previously using PUT 16 and now they are using PUT 17. You can create an update that users can apply to install the PUT 17 help and remove the PUT 16 help.
When you create a new update, you should always use your previous update as a starting point for the new update. The reason that the install handler customizations are cumulative is because the install handler only runs for the update that is being applied. For example, you might create a 2.0.8.1 update in which you customize the install handler to ship a user macro file that contains definitions of your HLAsm macros. Later, you ship a 2.0.8.2 update; since you did not make any changes to the user macro file, you do not ship it. If a user does not apply the 2.0.8.1 update and they get the 2.0.8.2 update, they will not get the user macro file that you shipped in 2.0.8.1 since the 2.0.8.1 install handler will not run.
Whenever you create a new update, remember to complete the following steps: - Start with the previous update material.
- Increment the version number. The easiest way to do this is to search all files in your update material containing the old version number, and replace all occurrences of the old version number with the new version number. When choosing a version number, you should choose a version number that uses the same V.R.M as the Interim Fix you are customizing, and then add another digit to represent the customization you are making. For example, if you are customizing Interim Fix 2.0.8 and this is your second customization, choose 2.0.8.2 as your version number. Although IBM used the fourth digit for Interim Fix updates in the past, in the future this digit will be reserved for customer use.
- Ensure that your update site has all the most recent IBM provided plug-ins and features before adding your own customized JAR files.
If the update you are shipping is based on an IBM Interim Fix, you must also do the following: - Open ...\<MyCustomizedUpdate>\features\com.ent.customized.toolkit\feature.xml and ensure that your feature includes the most current com.ibm.tpf.toolkit feature. The template that is provided requires the main com.ibm.tpf.toolkit feature version 2.0.8. However, each time that IBM ships an Interim Fix, the version number of the main com.ibm.tpf.toolkit feature is incremented and must be changed in your com.ent.customized.toolkit feature.
- Copy the most recent about information from the com.ibm.tpf.toolkit plug-in to your com.ent.customized.toolkit plug-in. The provided template includes a com.ent.customized.toolkit feature that is used to customize the welcome page. This plug-in is a primary plug-in that also specifies information for the about dialogs in the product. The about information is updated in each Interim Fix. To copy the about information, do the following:
- In a TPF Toolkit that you set up for testing purposes, install the most recent Interim Fix, as provided by IBM.
- Copy the following files from %TPFHOME%\eclipse\plugins\com.ibm.tpf.toolkit_V.R.M to <MyCustomizedUpdate>\plugins\com.ent.customized.toolkit:
- about.html
- about.mappings
- about.properties
Where V.R.M is the version, release, and modification of the Interim Fix that you are customizing.
Back to Top
A detailed example
Back to Top
Step 1 - Populate the update site with IBM provided updates
For this example, the update site is C:\CompanyUpdateSite. To populate the update site:
1. Create a folder named CompanyUpdateSite on your C drive.
2. Unzip the following file into C:\CompanyUpdateSite:
IBM Provided Update Site Content (2.0.8)
Note: This example assumes that you are using C:\CompanyUpdateSite as your test update site. If you are using a different folder, change the URL of the update site in the com.ent.customized.toolkit feature. The com.ent.customized.tooklit feature is included in the Customization Template that you will download in the next step.
3. If you are not going to be customizing 2.0.8, unzip one of the following files into C:\CompanyUpdateSite:
IBM Provided Update Site Content (2.0.10)
IBM Provided Update Site Content (2.0.11)
IBM Provided Update Site Content (2.0.12)
Back to Top
Step 2 - Customize the install handler
In this step, you will customize the install handler, assuming that the following changes were made: - You changed some TPF Toolkit preferences (a TPFSHARE change).
- You added a new External Tools action (a workspace change).
- You added some new HTML files to your custom help (a plug-in change).
- You changed the welcome page to contain a link to your custom help (a plug-in change).
- You modified TPFToolkit.bat to display the workspace location in the title bar (an 'Other' change).
To customize the install handler with the above changes, complete the following steps:
1. Unzip one of the following files to your C:\ drive to provide a starting point for your customized update:
Customization Template (2.0.8 Based)
Customization Template (2.0.10 Based)
Customization Template (2.0.11 Based)
Customization Template (2.0.12 Based)
When you unzip this file, a C:\MyCustomizedUpdate folder is created. This folder contains the base for your update.
2. To include the TPF Toolkit preference changes:
- Save tpf_pref.xml to the C:\MyCustomizedUpdate\features\com.ent.customized.installHandler folder.
- Add the following line to C:\MyCustomizedUpdate\features\com.ent.customized.installHandler\ENT_workstation_copy_list.txt to copy this file to the %TPFSHARE% folder on the user's workstation:
tpf_pref.xml=%TPFSHARE%
Note: In this example, the provided tpf_pref.xml file contains a user variable (USR_COMPANY_NAME) and a setting to turn on the tpftool server when TPF Toolkit is started. In general, when you customize preferences in TPF Toolkit the changes are saved to %TPFPROJ%\tpf_pref.xml.
The preferences in TPF Toolkit are composed of values found in %TPFSHARE%\tpf_pref.xml and %TPFPROJ%\tpf_pref.xml. IBM ships all default values in %TPFSHARE%\tpf_pref.xml. To ensure that you get all of the correct default values in addition to your customized values, copy %TPFSHARE%\tpf_pref.xml to your %TPFPROJ% folder, make your customizations, and then copy the tpf_pref.xml file from your %TPFPROJ% folder to the com.ent.customized.installHandler folder.
3. To include a new external tools action:
- Save the projectsetup.bat file called by the external tools action to C:\MyCustomizedUpdate\features\com.ent.customized.installHandler.
- Save the My_Setup_New_Project.launch file that contains the external tool action definition to C:\MyCustomizedUpdate\features\com.ent.customized.installHandler.
Tip: After you download the My_Setup_New_Project.launch file, rename the file to My Setup New Project.launch.
- Save the launchConfigurationHistory.xml file that contains a menu item for the new external tools action to C:\MyCustomizedUpdate\features\com.ent.customized.installHandler.
- Add the following lines to the ENT_workstation_copy_list.txt file to copy the external tools action files to the appropriate location on the user's workstation:
projectsetup.bat=%TPFSHARE%
My Setup New Project.launch=%WORKSPACE%\.metadata\.plugins\org.eclipse.debug.core\.launches
launchConfigurationHistory.xml=%WORKSPACE%\.metadata\.plugins\org.eclipse.debug.ui
Note: In this example, one external tools action named "My Setup New Project" is included in the update. The action calls %TPFSHARE%\projectsetup.bat which makes a call to tpftool to create a new project. projectsetup.bat is passed the value of the USR_COMPANY_NAME user variable.
In general, the external tools actions are stored in ...\eclipse\workspace\.metadata\.plugins\org.eclipse.debug.core\.launches. Each external tools action is stored in a separate file named after the action. For example, the external tools action in this example is named "My Setup New Project" and it is saved in a file named: ...\eclipse\workspace\.metadata\.plugins\org.eclipse.debug.core\.launches\My Setup New Project.launch. For each external tools action that you want to deploy in the update, copy the .launch file for the action into the ...MyCustomizedUpdate\features\com.ent.customized.installHandler folder. Also, when using external tools actions, you might want the action you create to appear on the Run menu when deployed to users. If you already used the external tools action in your test installation, then the action appears on your Run menu. The ...eclipse\workspace\.metadata\.plugins\org.eclipse.debug.ui\launchConfigurationHistory.xml file stores a history of all of the external tools actions that have been used. You can add launchConfigurationHistory.xml to com.ent.customized.installHandler so that users also see the action on the Run menu when they apply the update.
4. Add the folder that contains the customized help:
- Unzip com.ibm.tpf.custom.doc_2.0.0 to C:\MyCustomizedUpdate\features\com.ent.customized.installHandler.
- Add the following line to ENT_workstation_copy_list.txt:
com.ibm.tpf.custom.doc_2.0.0=%TPFHOME%\eclipse\plugins
Note: In this example, the customized help contributes a new book to the help. Since you might forget exactly which files you changed in your custom help for each update, it is recommended that you include the entire com.ibm.tpf.custom.doc folder in your updates. When the install handler copies files or folders, it reuses the original folder name when it creates the new folder. Since your customized help should replace the com.ibm.tpf.custom.doc_2.0.0 folder, ensure that you rename your folder to match the current version shipped by IBM. For example, com.ibm.tpf.custom.doc_2.0.0.
5. Add the customized welcome page. To customize the welcome page, modify the <MyCustomizedUpdate>\plugins\com.ent.customized.toolkit\welcome.xml file. In this example, the following item was added to this file to add a link from the welcome page to the custom help:
<item>
To launch MY ENTERPRISE help, click <topic href="/com.ibm.tpf.custom.doc/html/entintro.html">here</topic>
</item>
Save the modified welcome.xml to <MyCustomizedUpdate>\plugins\com.ent.customized.toolkit\ (replace the existing version).
6. Include the customized TPFToolkit.bat file. Save TPFToolkit.bat to C:\MyCustomizedUpdate\features\com.ent.customized.installHandler to replace the existing version.
In general, the -showLocation option determines if the workspace location appears in the title bar. The customized TPFToolkit.bat file in this example adds the -showLocation option to the start command so that the workspace location appears in the title bar of TPF Toolkit. The environment variables are also set in TPFToolkit.bat since it is assumed that when TPF Toolkit was initially deployed, the environment variables were not set on the user's machine. Instead, TPFToolkit.bat is used to set up the environment for users each time that they start TPF Toolkit.
Notes: - The sample TPFToolkit.bat contains the following line:
start /MIN /D"%~d0%~p0eclipse" eclipse.exe -showLocation -feature com.ent.customized.toolkit -plugincustomization .\plugins\com.ibm.tpf.toolkit_2.0.8\plugin_customization.ini -vmargs -Xj9 -Xmx256M
This line assumes that you are customizing Interim Fix v2.0.8. If you are customizing a different Interim Fix, correct the path in TPFToolkit.bat.
- The following line has already been added to the ENT_workstation_copy_list.txt file to copy the file:
TPFToolkit.bat=%TPFHOME%
At this point, verify the following:
- In C:\MyCustomizedUpdate\features\com.ent.customized.installHandler you have six new items:
Tip: Ensure that none of the file extensions were modified when you downloaded the files. Sometimes a .txt extension (as well as other file name extensions) is added to the files when they are downloaded.
- ENT_workstation_copy_list.txt has been updated and contains the following lines:
TPFToolkit.bat=%TPFHOME%
tpf_pref.xml=%TPFSHARE%
projectsetup.bat=%TPFSHARE%
My Setup New Project.launch=%WORKSPACE%\.metadata\.plugins\org.eclipse.debug.core\.launches
launchConfigurationHistory.xml=%WORKSPACE%\.metadata\.plugins\org.eclipse.debug.ui
com.ibm.tpf.custom.doc_2.0.0=%TPFHOME%\eclipse\plugins
Back to Top
Step 3 - Add additional plug-ins
In this example, you will add the PUT 16 help to the update that you are deploying to users. To add the PUT 16 help, complete the following steps:
1. Update the com.ent.customized.toolkit feature to require the PUT 16 help feature:
- Add the following to the C:\MyCustomizedUpdate\features\com.ent.customized.toolkit\feature.xml file:
<includes
id="com.ibm.tpftoolkit.doc.put16"
version="2.0.5"/>
- Unzip PUT level help plug-ins and features (PUT 16) to C:\MyCustomizedUpdate\CustomizedDelta.
2. Update the TPF HLAsm Parser preferences to use PUT 16. In general, the PUT level that the HLAsm parser uses to parse a file is set at the file level. However, you can create custom defaults that override the IBM defaults. Users can still change the PUT level used to parse an individual file. To set custom defaults, open a file that uses the HLAsm parser, and then open the Preferences window (Window > Preferences) to locate the node for this file in the LPEX Editor section. A node for the TPF HLAsm Parser is displayed within the node for your open file. Change the settings in this preferences page and click Save as custom defaults to save the settings that all files use by default. The custom defaults are stored with all of the other LPEX preferences in the ....eclipse\workspace\.metadata\.plugins\com.ibm.lpex\Editor.properties file. In this example, the Editor.properties file that is provided contains all of the shipped LPEX defaults, with the exception of the PUT 16 setting. The shipped default is to have the parser accept all levels of macros. However, when no specific default is used, the parser uses PUT 17 when looking for help for a macro. Since you are not installing the PUT 17 help, the F1 help only works if you explicitly set the PUT level to 16.
3. Save Editor.properties to C:\MyCustomizedUpdate\features\com.ent.customized.installHandler.
Tip: When you save this file, ensure that no extension is added to the file name.
4. Add the following line to the ENT_workstation_copy_list.txt file to back up the user's current LPEX preferences:
%WORKSPACE%\.metadata\.plugins\com.ibm.lpex\Editor.properties=%TPFHOME%\backup\UpdatedIn2.0.8.1
5. Add the following line to the ENT_workstation_copy_list.txt file:
Editor.properties=%WORKSPACE%\.metadata\.plugins\com.ibm.lpex
In this example, you also assume that you have a new plug-in that you need to ship to users. This plug-in contributes a toolbar button that runs the "My Setup New Project" external tools action.
Note: Since instructions on how to create such a plug-in are the topic of another article, this article provides the plug-in and minimal details for changing the plug-in. If you want to experiment with the provided code, do the following:
1. Unzip the sample project to the your TPF Toolkit workspace folder:
com.example.mytoolbarbuttons
2. Select Window > Open Perspective > Other > Plug-in Development.
3. Select Window > Preferences to open the Preferences window.
4. In the left navigation pane, double-click the Plug-in Development node to open the tree of available preferences pages.
5. Click Target Platform to open the Target Platform preferences page.
6. Click Select All to select all available plug-ins.
7. Click OK to save the your changes and close the Preferences window.
8. Select File > Import to open the Import wizard.
9. Select Existing Project Into Workspace, and then click Next.
10. Select the com.example.mytoolbarbuttons project that you saved.
11. Click Finish to complete the import.
Now that the project is in your workspace, you can view and modify the source. The source is automatically recompiled when you save source file changes. If you want to test your changes, you can launch a run-time workbench by selecting Run > Run As > Run-time workbench from the main menu in TPF Toolkit. To run the action, you must start the tpftool server in your run-time workbench, and then install the "My Setup New Project" external tools action in your run-time workbench. You can install the external tools action in the default workspace for the run-time workbench (...eclipse\runtime-workspace).
To add the new plug-in to the update:
1. Unzip com.example.mytoolbarbuttons into C:\MyCustomizedUpdate\features\com.ent.customized.installHandler.
2. Add the following line to the ENT_workstation_copy_list.txt file:
com.example.mytoolbarbuttons=%TPFHOME%\eclipse\plugins
Note: You can also add the new plug-in to the update by adding a reference to the plug-in in the com.ent.customized.toolkit feature. However, this requires more work since you need to package your plug-in in a .jar file with the correct version, and then include the plug-in in the com.ent.customized.toolkit feature. This example uses the simple method to deploy a new plug-in.
Back to Top
Step 4 - Remove unnecessary plug-ins and files
In this example, you will remove the Administration feature that contributes the Administration preferences pages. In the example template, the Administration feature is already set up to be deleted. The following line in the ENT_feature_delete_list.txt file deletes the Administration feature and plug-ins:
com.ibm.tpf.administrator
In this example, it is assumed that a shared location for remote host files is used, and you can delete the host files that are copied to the user's workstation for them to upload. The following line has already been added to the ENT_delete_list.txt file in the template to accomplish this.
%TPFHOME%\Config\host
Back to Top
Step 5 - Push changes to the update site
Note: This step uses the batch files provided in the template to create the .jar files for the update site. To use these batch files, you need to do the following:
1. Install a Java SDK.
2. In the prepareupdate.bat file, change the C:\Program Files\IBM\Java141\bin path to the location where you installed the Java SDK.
In this example, you will run the tools and create the JAR files in a temporary folder before saving them to your update site folder. To create the JAR files, complete the following steps:
1. From a command prompt, cd to the C:\MyCustomizedUpdate directory.
2. Run the command by typing:
prepareupdate 2.0.8.1 C:\MyCustomizedUpdate\CustomizedDelta
After the command runs, the new .jar files are displayed in the CustomizedDelta folder.
In this example, you will only host this update (2.0.8.1) on your update site. The C:\MyCustomizedUpdate\CustomizedDelta\site.xml file already lists the 2.0.8.1 update; you do not need to customize it.
Once you create your .jar files and the site.xml file lists the correct update, you can promote everything to the C:\CompanyUpdateSite folder. To copy the files:
1. Create a .zip file that contains all of the content in the C:\MyCustomizedUpdate\CustomizedDelta folder.
2. Unzip the file to the C:\CompanyUpdateSite folder.
Back to Top
Step 6 - Test the update site
To test the update site, complete the following steps:
1. Create a copy of the installation that you initially deployed to your users.
2. Start TPF Toolkit using the installation that you initially deployed to your users.
3. Select Window > Open Perspective > Other > Install/Update to open the Install/Update perspective.
4. In the Feature Updates view, expand the My Computer node and locate your C:\CompanyUpdateSite folder.
5. Expand the categories within C:\CompanyUpdateSite and locate the TPF Toolkit 2.0.8.1 category.
Note: All of the features that are included by your customized feature also appear when you expand your update. For example, your feature includes the main com.ibm.tpf.toolkit feature that includes all of the other features and plug-ins required for TPF Toolkit. Your feature also includes your customized install handler and any PUT level features that you added.
6. In the TPF Toolkit 2.0.8.1 category, select the IBM TPF Toolkit for WebSphere Studio (Customized) 2.0.8.1 update.
7. In the Preview view, click Install Now to apply the update.
8. Follow the instructions in the installation wizard. When prompted to restart TPF Toolkit, click No.
Note: After the update is applied, update manager restarts using the same options that were used to start TPF Toolkit before the update. Since some of the options have been changed in this example, you must manually restart using the new TPFToolkit.bat file.
9. Shut down TPF Toolkit, and then restart it using the TPFToolkit.bat file.
Once TPF Toolkit is running, test the following:
- Check %TPFHOME%\backup\TPFToolkitInstallHandlerLog.txt to ensure no errors occurred. If there are any error messages in this file, verify that you specified all of the paths correctly in the ENT_workstation_copy_list.txt and ENT_delete_list.txt files. One way to do this is to search for the word failed in the file.
- Verify that the preference changes were made:
- Check that the tpftool server was started when TPF Toolkit opened; a message should be displayed in the TPF Console.
- Check that the USR_COMPANY_NAME user variable is set in the User Variables and Exits preferences page (Window > Preferences > TPF Toolkit > User Variables and Exits).
- The Administration preferences page does not appear since the feature was removed.
- Ensure that when you select the Run menu, the My Setup New Project action appears.
- Ensure that an item to launch the enterprise help was added to the Welcome page.
- Open the Help and verify that a new book called Enterprise Help appears.
- In the Reference section of the help, verify that the PUT 16 help is the only PUT level help that appears.
- Verify that the workspace location is displayed in the title bar.
- Open a .asm file in the TPF Toolkit LPEX Editor, select a macro name in the file, and then press F1. Ensure that the PUT 16 help appears for the selected macro. You can also issue the following command to verify that the parser is using PUT 16:
queryPUTLevel
- The button to launch the external tools action might not be displayed. If this button does not appear, customize the perspective to display the button by doing the following:
- From the main menu, select Window > Customize Perspective...
- In the Other section, select the Sample Action Set check box.
- Click OK to save your changes. The button should appear on the toolbar.
- To verify that the action runs and creates a new project, click My Project Setup Action and ensure that the action runs and creates a new project. The sample action creates a new project with the value of the user variable that was set in the preferences. If you change the user variable value and run the action again, it creates a project with a different name.
Back to Top
Step 7 - Create another update
Before IBM ships another Interim Fix, you might need to make additional updates. For example:
- A new macro has been added and you want to deploy a custom macro definition file and help for this new macro.
- You are now using PUT 17 instead of PUT 16; you want to remove the PUT 16 help and add the PUT 17 help.
To create a new update, complete the following steps:
1. Rename your C:\MyCustomizedUpdate folder to C:\MyCustomizedUpdate_2.0.8.1.
2. Create a copy of C:\MyCustomizedUpdate_2.0.8.1 and name it C:\MyCustomizedUpdate_2.0.8.2. Base the next update off of the previous update.
3. The previous update was version number 2.0.8.1. Since that version number has already been used for an update, you must increment the version number to 2.0.8.2. Search within C:\MyCustomizedUpdate_2.0.8.2 for 2.0.8.1 and replace it with 2.0.8.2. There are five files that contain references to 2.0.8.1; change all references in these files:
4. Change the install handler to include the new macro definitions file:
- Save the mymacros.dat file that contains the syntax definition for MACA to C:\MyCustomizedUpdate_2.0.8.2\features\com.ent.customized.installHandler.
- Delete the com.ibm.tpf.custom.doc_2.0.0 folder from C:\MyCustomizedUpdate_2.0.8.2.
- Unzip com.ibm.tpf.custom.doc_2.0.0 to C:\MyCustomizedUpdate_2.0.8.2\features\com.ent.customized.installHandler. This contains the help that was shipped in the first update, as well as the new help page and an updated table of contents.
- Delete C:\MyCustomizedUpdate_2.0.8.2.\Editor.properties.
- Save the Editor.properties file that contains the LPEX preferences for the user macro file and the link to the table of contents file for the F1 help to C:\MyCustomizedUpdate_2.0.8.2\features\com.ent.customized.installHandler.
- Add the following line to the ENT_workstation_copy_list.txt file:
mymacros.dat=%TPFSHARE%
Note: The following lines should already appear in this file from the previous update:
com.ibm.tpf.custom.doc_2.0.0=%TPFHOME%\eclipse\plugins
Editor.properties=%WORKSPACE%\.metadata\.plugins\com.ibm.lpex
%WORKSPACE%\.metadata\.plugins\com.ibm.lpex\Editor.properties=%TPFHOME%\backup\UpdatedIn2.0.8.2 (This line was edited when you replaced all occurrences of 2.0.8.1 with 2.0.8.2.)
In this example, one macro definition for the macro MACA was added to the mymacros.dat file. You also added a help file for this macro and set up F1 help for the new macro. In general, the name of the user macro file being used is specified in the TPF HLAsm Parser preferences page (Window > Preferences > LPEX Editor > Parsers > TPF HLAsm Parser). Once you create a macro definitions file, you set the name and location of the file in the TPF HLAsm Parser preferences page. If you have custom help and set up a table of contents file for your custom help, you can specify the name of your table of contents file in the TPF HLAsm Parser preferences page. This allows the F1 help in the editor to link to your custom help.
5. Change the install handler to include PUT 17 help and remove PUT 16 help:
1. Update the com.ent.customized.toolkit feature to require the PUT 17 help feature:
- Open the C:\MyCustomizedUpdate_2.0.8.2\features\com.ent.customized.toolkit\feature.xml file and change:
<includes
id="com.ibm.tpftoolkit.doc.put16"
version="2.0.5"/>
to
<includes
id="com.ibm.tpftoolkit.doc.put17"
version="2.0.5"/>
- Unzip PUT level help plug-ins and features (PUT 17) to C:\MyCustomizedUpdate_2.0.8.2\CustomizedDelta.
- The site.xml file only allows users to get the 2.0.8.2 update; you can delete the PUT 16 .jar files since the 2.0.8.2 update does not require them.
2. Update the TPF HLAsm Parser preferences to use PUT 17. When you updated the LPEX preferences to use the new user macro file, it was also updated to use PUT 17; the Editor.properties file in C:\MyCustomizedUpdate_2.0.8.2\features\com.ent.customized.installHandler already contains the correct setting. You also changed the ENT_workstation_copy_list.txt file to back up the user's previous Editor.properties file and to copy the revised Editor.properties to the correct location. Everything for this step has already been completed.
In this example, you changed the install handler to install PUT 17 help, remove the PUT 16 help, and modify the TPF HLAsm Parser preferences so that the PUT level used by the parser is PUT 17. In general, you can customize the install handler to remove a feature using the ENT_delete_list.txt file to delete the feature and all plug-ins used by that feature.
6. Promote to the update site:
- From a command prompt, cd to the C:\MyCustomizedUpdate_2.0.8.2 directory.
- Run the command by typing:
prepareupdate 2.0.8.2 C:\MyCustomizedUpdate_2.0.8.2\CustomizedDelta
After the command runs, the new .jar files appear in the CustomizedDelta folder.
Tip: You can remove the 2.0.8.1 jar files from the C:\MyCustomizedUpdate_2.0.8.2\CustomizedDelta folder.
- Create a .zip file that contains all of the content in the C:\MyCustomizedUpdate_2.0.8.2\CustomizedDelta folder.
- Unzip the file to the C:\CompanyUpdateSite folder.
Back to Top
Step 8 - Test the 2.0.8.2 update
To test the update site, complete the following steps:
1. Start TPF Toolkit using the installation that you already updated to 2.0.8.1.
Note: You can start with the TPF Toolkit installation that you originally deployed to users and everything should work exactly the same. However, for the purposes of this example, test the scenario of updating from 2.0.8.1 to 2.0.8.2.
2. Select Help > Software Updates > New Updates. In the 2.0.8.1 update, the com.ent.customized.toolkit feature was installed. In the com.ent.customized.toolkit feature, the URL of the internal update site (C:\CompanyUpdateSite) was added. Now TPF Toolkit knows to look on the internal update site for updates and should find the 2.0.8.2 update.
3. Follow the wizard for updating to 2.0.8.2.
4. Restart TPF Toolkit when prompted.
Once TPF Toolkit is running, test the following:
- Check %TPFHOME%\backup\TPFToolkitInstallHandlerLog.txt to ensure that no errors occurred. You should be able to see output from both the 2.0.8.1 update and the 2.0.8.2 update. If there are any error messages in this file, verify that you specified all the paths correctly in the ENT_workstation_copy_list.txt and ENT_delete_list.txt files.
Note: If you attempt to delete files that were already deleted in the 2.0.8.1 update, you might receive deletion failure messages.
- To test that the user macro file is being used and that the new help page is installed:
- Open a .asm file in the TPF Toolkit LPEX editor.
- Type MACA in the .asm file.
- Select MACA, and then press F1.
The help should open the MACA help page in the Enterprise Help book.
- Verify that the correct PUT level is being used:
- In your .asm file, type the following command on the LPEX command line:
queryPUTLevel
Verify that PUT 17 is being used.
- In the help, ensure that only the PUT 17 help appears in the Reference book.
Back to Top
Troubleshooting
| Symptom | Cause \ Resolution | | | | Preparing update site content | | | When trying to run prepareupdate.bat, an error message appears. | - You do not have a Java SDK installed.
- You did not update the path of the installed Java SDK in prepareupdate.bat.
- You are not running prepareupdate.bat from the folder that contains your features and plugins folders.
| | | | In the Install/Update perspective | | | No customized update appears in the customized update folder. Only the uncustomized 2.0.8 is displayed. | - You did not modify the site.xml in your update site folder to include your update.
- You did not copy the site.xml file that you modified into your update site folder.
| When looking for your 2.0.8.1 update, you see the following:
| - You are not looking in the "C:\CompanyUpdateSite" folder, you are looking at a location that only contains the plug-ins and features you changed. Go to the "C:\CompanyUpdateSite" folder where the base Interim Fix v2.0.8 update and the customized plug-ins and features reside.
- The JAR file that corresponds to the feature is not on the internal update site.
- There is a syntax error in the feature.xml file.
| | | | After applying an update | | | | | In the TPF Toolkit perspective | | | When you check for new updates, no updates are available. | - If this is your first update, use the Install/Update perspective to get the update.
- If this is not your first update, ensure that you updated the site.xml file with a newer version, and that %TPFHOME%\eclipse\features\com.ent.customized.toolkit\feature.xml uses the correct internal update site address.
- Ensure that the current configuration is valid. If the current configuration was corrupted by a previous update, new updates cannot be applied. Verify that the current configuration is valid by doing the following:
- Open the Install/Update perspective.
- In the Install Configuration view, expand the IBM TPF Toolkit for WebSphere Studio (Customized) node.
- Locate the IBM TPF Toolkit for WebSphere Studio (Customized) V.R.M.C node.
- Verify that when you click this node, you can see the details in the Preview view. If an error dialog box with the title Problem Occurred appears, the current configuration is invalid.
- If the current configuration is invalid, shut down TPF Toolkit, and then delete the ...workspace\.metadata\.config\platform.cfg file.
Important: If you find that your update has caused an invalid configuration, you must change your update until it does not cause the current configuration to be invalid. If you deploy an update that causes an invalid configuration to users, they will not be able to apply future updates. To resolve the problems in your update, do the following: - Ensure that you do not remove any plug-in or feature folders in the ENT_delete_list.txt file.
- In the ENT_feature_delete_list.txt file, ensure that you only remove standalone features. Standalone features include all of the PUT level help features and the Administrator feature.
| | When you check for new updates, updates that should not be listed appear. | This is a known problem in TPF Toolkit. | | Many of the actions are missing from the pop-up menu. | When you customized tpf_pref.xml, you did not start with the version in the TPFSHARE folder. The %TPFSHARE%\tpf_pref.xml file contains default values for items such as the base menu assignments. If you do not use the %TPFSHARE%\tpf_pref.xml file as the base for your customizations, you will be missing many of the default preferences.
You can fix this problem in the TPF Toolkit that you used to make your customizations. Save the %TPFSHARE%\tpf_pref.xml file to your %TPFPROJ% folder. Make your customizations again and include %TPFPROJ%\tpf_pref.xml in your update. | | The custom button contributed in the example does nothing when you click it. | Ensure that the External Tools action "My Setup New Project" was installed. Also, verify that the projectsetup.bat file used by the action was installed in the TPFSHARE folder. | | Some of the customizations are missing. | Verify that there were no errors copying any of the files. The %TPFHOME%\backup\TPFToolkitInstallHandlerLog.txt file contains a log of all of the install handler activity. Check the TPFToolkitInstallHandlerLog.txt file to ensure that there were no errors.
If the missing customizations are controlled by the TPFToolkit.bat file, restart TPF Toolkit.
Note: After applying an update, the update manager restarts using the same settings that were used the last time TPF Toolkit was started; it does not use TPFToolkit.bat to complete the restart. You must close TPF Toolkit, and then start it using the new customized TPFToolkit.bat file to see the changes. |
Back to Top | | | | | | Cross Reference information | | Segment | Product | Component | Platform | Version | Edition | | Software Development | IBM TPF Toolkit for WebSphere Studio | Installation | Windows 2000, Windows XP | 2.0.8 | |
| | |
|
|
|
| IBM, the IBM logo and ibm.com are trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml. |
|
|
|
|
| Please take a moment to complete this form to help us better serve you. |
|
 |
|
|
|
|
|
|
| Product categories: |
|
| | Software | |
| | Software Development | |
| | Traditional Progamming Language & Compilers | |
| | IBM TPF Toolkit | |
| | Installation | |
|
| Operating system(s): |
| |
Windows 2000, Windows XP
|
|
| Software version: |
| |
2.0.8
|
|
| Reference #: |
| |
7005916
|
|
| IBM Group: |
| | Software Group |
|
| Modified date: |
| | 2005-11-30 |
|
|
