Customizing and deploying enterprise TPF Toolkit updates - TPF Toolkit v4.2

Content

Before you begin

If you had prepared custom updates using an internal update site in previous versions of TPF Toolkit, you can no longer reuse your enterprise feature and update site projects directly. Follow the instructions in the Migrate your existing internal update site projects to TPF Toolki 4.2 document to import your existing features and plugins into a new TPF Configuration project.

Objectives

This tutorial guides you through the steps required to create an enterprise configuration for your users. You can create an enterprise configuration to deploy all TPF Toolkit changes (enterprise updates) to your users. The enterprise configurations are uploaded to a particular directory on your remote z/OS or Linux for System z® host. You must then update your dstore environment to specify the config.folder variable to point to the directory that contains the enterprise configuration. When a user connects to a remote host where the dstore specifies a valid config.folder value, the deployed configuration will be discovered automatically and the user will be prompted to take appropriate action.

For detailed information on the elements of an enterprise configuration, see Enterprise configurations.

Description

To create an enterprise configuration, complete the following steps:

• Part 1: Create a TPF Configuration project
• Part 2: Specify general configuration options
• Part 3: Specify enterprise features for the configuration
• Part 4: Customizing the install handler
• Part 5: Removing unnecessary features and files
• Part 6: Uploading the enterprise configuration
• Part 7: Updating the RSE dstore environment
• Part 8: Testing the enterprise configuration
• Part 9: Creating additional updates

Part 1: Create a TPF Configuration project

You must first create a new TPF Configuration project in order to create and deploy enterprise configurations. A TPF Configuration project manages creating and editing enterprise configurations as well as packaging and uploading these configurations to your remote host.

To create a new TPF Configuration project, complete the following steps:

• Switch to the Plug-in Development perspective.
• In the Package Explorer view, right-click anywhere in the view and select New > Project from the pop-up menu to open the New Project wizard.

• Select the Configuration Project wizard from the TPF category, as shown above.
• In the Project name field, type the name of the new project.

Optional. Do one of the following:

· Select the Use default check box to specify that you want to create the project in your local workspace.
· Clear the Use default check box. In the Directory field, type the path where you want to create the new project, or click Browse to browse for the location. All projects must be local.
• Click Finish to create the TPF Configuration project.

Part 2: Specify general configuration options

An enterprise configuration allows you to specify certain general options that apply to the configuration. To specify the general configuration options, complete the following steps:

• Expand your TPF Configuration project. Right-click on the tpftoolkit_config.xml file and select Open With... > TPF Toolkit Configuration Editor from the pop-up menu.
• In the Supported TPF Toolkit version field, specify the version of TPF Toolkit to which this enterprise configuration applies. For example, if you are creating an update that is meant to be installed on TPF Toolkit V4.2.0, enter 4.2.0 in this field.

Tip: If you do not want to restrict this enterprise configuration to a particular version of TPF Toolkit, select the Allow unsupported TPF Toolkit versions checkbox.

• Select the Force TPF Toolkit update if new remote configuration is found checkbox to force your users to apply the deployed configuration. When this setting is enabled, a user does not have the option of continuing to work with TPF Toolkit without applying the configuration.
• In the Update details field, specify a URL where a user can find additional details related to this enterprise configuration. For example, you may link to a change log on an internal site.
• In the Enterprise version field, specify the version of this new enterprise configuration.

Part 3: Specify enterprise features for the configuration

The new TPF Configuration project handles the creation and management of update sites for you. To deploy enterprise features, complete the following steps:

• In the Features section, click the Add feature... button.

Tip: It is recommended that you import any features and plugins that you wish to deploy as part of your enterprise configuration into the same workspace that contains your TPF Configuration project.

• In the Feature selection dialog, select the features you wish to install as part of this enterprise configuration.

Part 4: Customizing the install handler

If you have to make customizations to the TPF Toolkit and want to deploy them to the users, you need to set up the install handler for your enterprise configuration so that the configuration files can be distributed to the right location during the installation.

Complete the following steps to customize the install handler for your enterprise configuration:

• Add customized files.
• Use a user exit to run custom scripts.

Adding customized files

While customizing TPF Toolkit, you might modify some TPF Toolkit configuration files. You must deploy these changed configuration files to your users. For example, if you customize a TPF Toolkit preference setting that you want users to see, you must deploy the tpf_pref.xml file to your users. The distribution of the configuration files is handled by the install handler of the enterprise configuration.

TPF Toolkit tracks preference file changes made by an administrator. You can add them to an enterprise configuration by doing the following:

• Open tpftool_config.xml from the current configuration project, or create a new TPF configuration project and open tpftool_config.xml in the TPF Toolkit Configuration editor.
• Confirm that the supported TPF Toolkit version number and new enterprise update version number exist in the configuration.
• Make any changes to Window > Preferences that you want to ship to the users via the enterprise update.
• Click Add preference collection in the Workstation Copy List section.
• Verify that the correct preference files are added to Workstation Copy List. If mistakes are made, click Reset preference collection to start with an empty list.
• Save the TPF Toolkit Configuration editor. The install handler within your TPF configuration project is now customized to move your files and folders.

You must configure the install handler to specify which files should be installed to where on the users' workstations when the enterprise configuration is applied. To configure the install handler, complete the following steps:

• Create a list of all of the configuration files that you customized.

Tip: For a list of all of the files in TPF Toolkit that can be customized, see Customization files. For detailed instructions on deploying each type of customization, see Deploying enterprise customizations.

• Copy all the changed files into the folder deploy in your TPF Configuration project. For example, your custom TPFToolkit.bat, external tools .launch files, and LPEX preferences.

Tip: You can create sub-folders in deploy to organize your files.

• Using the TPF Toolkit Configuration editor, open the file tpftoolkit_config.xml in your TPF Configuration project.
• For each file or folder that you want to move to users' workstations, add an entry in the Workstation copy list section of the editor that moves that file or folder to the desired location.

Note: You can use environment variables in this line. For example, %TPFHOME%. You can also use the %WORKSPACE% substitution variable to obtain the full path of users' workspaces. For example, if you add a file named My Setup New Project.launch that you want to move to users' workspaces, add the following line in the editor:

deploy\My Setup New Project.launch=%WORKSPACE%\.metadata\.plugins\org.eclipse.debug.core\.launches

• Save the TPF Toolkit Configuration editor. The install handler within your TPF Configuration project is now customized to move your files and folders.

Tip: If your TPFSHARE points to a network driver which is accessible to all the users, you don't need to deploy your customization in TPFSHARE to the users.

Using a user exit to run custom scripts

You can use one of the following user exits to run custom scripts during an update:

· install handler user exit - Use if you need to modify any of the files you transferred before TPF Toolkit is launched following the update.

The install handler user exit is invoked when the install handler finishes transferring files to and removing items from a user's workstation, but before these updates are activated. Updates are activated when TPF Toolkit is launched after the install handler process finishes. You can use this user exit to run custom scripts after the update has been applied. For example, you can use the install handler exit to prompt users for information such as a user ID during the update process.

Note: The install handler completes the process of installing an update, regardless of the outcome of any custom scripts.

To use the install handler user exit, open the tpftoolkit_config.xml file in your TPF Configuration project using the TPF Toolkit Configuration editor. You can set the install handler exit by adding a single line to the After copy script name section of the editor. This line must specify the fully qualified name of the program that you want to run and can include environment variables. For example, to run a program named installexit.bat in the %TPFSHARE% folder, add the following line:

"%TPFSHARE%\installexit.bat"

Tip: If the installexit.bat file is not already installed on the user's workstation, you must customize the install handler to transfer that file to the user's workstation. For example:

Copy the installexit.bat file into the deploy folder within your TPF Configuration project.

Add the following line in the Workstation copy list section:

.\deploy\installexit.bat = %TPFSHARE%

Add the following line After copy script name section:

"%TPFSHARE%\installexit.bat"

· update startup user exit - Use if you need to run any TPF Toolkit-dependent functions, such as running TPFtool services, or you need to use new features that are deployed as part of this update. This exit is run when TPF Toolkit is launched after the update is finished.

The update startup user exit is invoked after updates have been applied and TPF Toolkit is launched for the first time. This user exit is run after TPF Toolkit starts, but before control is passed to users. You can use this user exit to run custom scripts after enterprise configurations have been applied.

The update startup user exit allows you to run TPF Toolkit-dependent functions. For example, you can use this user exit to call TPFtool services. When new plug-ins are copied to users' workstations during an update, these plug-ins are not activated until users launch TPF Toolkit after the update. If you call any TPF Toolkit-dependent functions that are newer than what users have installed prior to the update, your custom scripts will fail since the functions you are calling are not installed yet.

You can set this user exit by editing the startup.bat file in the deploy folder within your TPF Configuration project. The startup.bat file can call any custom scripts or TPFtool services that you want to run when users launch TPF Toolkit after the update. During the update, the startup.bat file must be copied to the %TPFPROJ% directory on users' workstations. When TPF Toolkit starts after an update is applied, it looks for the %TPFPROJ%\startup.bat file. If this file is located, the startup.bat file is run. After the update startup exit runs, the startup.bat file is deleted.

Note: The file ENT_workstation_copy_list.txt already contains an instruction to move the file to the right place.TPF Toolkit will launch, regardless of the outcome of the custom scripts run in update startup user exit.

Part 5: Removing unnecessary features and files

You may want to remove files that were previously installed on your users' workstations.

Complete the following steps to remove a file when the new enterprise feature is installed:

• Open the tpftoolkit_config.xml file in your TPF Configuration project using the TPF Toolkit Configuration editor.
• For each file or folder that you want to remove, add a line with the fully qualified path of the file or folder to the Delete list section of the editor. For example, the following line removes test.bat from the %TPFHOME%\Config directory:

%TPFHOME%\Config\test.bat

Note: Arbitrary removal of files and folders from the workspace or the eclipse directory may corrupt TPF Toolkit.

To remove unnecessary features from the user workstation when the new enterprise feature is installed, complete the following steps:

Note: You should only remove features using this mechanism that were previously installed through an enterprise configuration. For all official IBM optional features - such as PUT help, etc. - use Installation Manager to perform the uninstall.

• Open the tpftoolkit_config.xml file in your TPF Configuration project using the TPF Toolkit Configuration editor.
• For each feature you want to remove, add its ID to the Feature delete list section of the editor. For example, the following line removes some custom feature:

ent.my.custom.feature

Note: Arbitrary removal of features may corrupt TPF Toolkit.

Part 6: Uploading the enterprise configuration

Once you complete the set up of your enterprise configuration, you are ready to upload the feature to your remote z/OS or Linux for System z host.

To upload your enterprise configuration, complete the following steps:

• In the TPF Toolkit Configuration Editor, click the Upload configuration () button.
• In the Upload TPF Toolkit Configurations dialog, select the remote location to which the configuration should be uploaded.
• Click Upload. The enterprise configuration is automatically packaged and uploaded to the specified directory.

Part 7: Updating the RSE dstore environment

You must update your dstore environment to specify the config.folder variable to point to the directory that contains the enterprise configuration. When a user connects to a remote host where the dstore specifies a valid config.folder value, the deployed configuration will be discovered automatically and the user will be prompted to take appropriate action.

You can specify the config.folder variable in the <dstore installation directory>/bin/server.linux file on zLinux or the <dstore installation directory>/bin/rsed.envvars file on z/OS. Here is an example of the change in a server.linux file:

system("java -Xscmx5m -Xsharedclasses:name=RSE%g,groupAccess,nonfatal -Xms10m -Xmx64m -DA_PLUGIN_PATH -DDSTORE_SPIRIT_ON=true -DSPIRITY_EXPIRY_TIME=30 -DSPIRIT_INTERVAL_TIME=30 -DDSTORE_SEARCH_ONLY_UNIQUE_FOLDERS=false -Xgcpolicy:gencon -Dfile.encoding=ISO-8859-1 -DCPP_CLEANUP_INTERVAL=60000 -Dbackupfiles=false -Dconfig.folder=/home/tpftk-configs org.eclipse.dstore.core.server.Server $port $timeout");

Part 8: Testing the enterprise configuration

You can test your enterprise configuration by completing the following steps:

• Start an instance of TPF Toolkit.
• If one does not already exist, create an RSE connection to the remote system that contains your enterprise configuration.
• Connect to the remote system.

An enterprise configuration should be found. You will be prompted to take appropriate action.

Part 9: Creating additional updates

You may wish to update your enterprise configuration in the following situation:

· Your company makes changes. For example, if your company previously used PUT 06 and now uses PUT 07. You can create an update that users apply to install the PUT 07 help and remove the PUT 06 help. When you create a new additional update, you can use your previous TPF Configuration project as a starting point.

Note: The install handler for a particular update must include all customizations that you want to deploy for that update, including any customizations that you have made for previous updates. For example, if you had modified the install handler to deploy a custom user macro file with a 4.2.0.01 update, you must include the custom user macro file in your install handler for a 4.2.0.02 update in order to deploy it again.

Whenever you create a new additional update, ensure that you complete the following steps:

• Start with the previous update material.
• Increment the enterprise version number in the TPF Toolkit Configuration editor.
• Complete your changes and upload your updated configuration to your remote host.

Summary

In this tutorial, you have learned how to create an enterprise configuration that your company can use to deploy your custom TPF Toolkit updates.