Using editors for platforms, applications, and policies

The platform, application, and application binding editors open automatically after you create a project of that type. To open the bundle manifest editor after you create a CICS bundle project, or to open any of the editors at a later time, go to the Project Explorer view in the CICS Cloud perspective. Expand the META-INF folder for the project and double-click on any of the .xml files for the bundle, except the manifest.xml file. As an alternative to double-clicking, you can right-click the file and click Open With, then select the name of the editor. When the editor opens, the editor name tab displays the name of the platform, application, application binding, or CICS bundle.

If you do not have a versioned backup system that enables you to revert to a previous version of the projects, instead of editing the existing projects directly, you might prefer to copy them to another project and then edit the new copies.

When you work with projects for applications, check that the CICS Platform project for the target platform is present in your local workspace, as CICS Explorer requires this project to validate your applications and application bindings.

Errors and warnings during the editing process are displayed in the main editor window, the Problems tab in the perspective, or the status field in the workbench.

To reverse one or more of your changes before you save them, use the Undo function. On the main menu for the workbench, click Edit > Undo, or press Ctrl+Z (cmd+Z for OS X).

When you have completed your updates to an application bundle, application binding bundle, or CICS bundle, always update the major, minor, or micro version numbers for the bundle according to your versioning policy. CICS validates the version numbers when you install an application in the platform, and you must update the version numbers for the application bundle and application binding whenever you update the CICS bundles for the application. Platform bundles do not use version control. For information about versioning, see Version control.

To save your changes, click on the Save icon , or press Ctrl+S (cmd+S for OS X). If you attempt to close the editor without saving the changes, a dialog is displayed so that you can choose whether to save your changes.

After you save your changes, export the platform or application to the platform home directory in zFS. Select the export action from the Overview tab of the editor to open the export wizard. An application, its application binding, and their associated CICS bundles are exported together as a single process. The new version number is used as part of the directory name, so the previous versions of the bundles remain in the platform home directory.

To install the platform or application in the CICSplex, you need a new PLATDEF or APPLDEF resource definition that points to the correct platform or application directory in the platform home directory. To create this resource definition during the export process, select the checkbox in the export wizard.

After you have installed an application in the CICSplex, you can view it in the online application editor. You can use this editor to enable, disable, or disable and discard the installed application, and to view its private resources. To work with an installed application, go to the Cloud Explorer view in the CICS Cloud perspective. In the CICSplex where the platform is located, select the installed application version and either double-click the application name, or right-click the application name then click Open.

Platform editor

Use the platform editor to work with platform bundles that have not yet been installed in a CICSplex. After a platform is installed and active, you can use menus in the CICS Cloud perspective to add and remove individual CICS regions in region types, and you can add and remove CICS bundles that are deployed with the platform. However, you cannot modify the region types in an installed platform, so use the platform editor to finalize your region types before installing the platform bundle. If you do edit a platform bundle for a platform that is already installed, you must stop, discard, reinstall, and restart the platform to implement the changes.

The platform editor has three tabs: Overview, Region Types, and Deployment. The list of actions on the Overview tab explains a process for editing the platform project, and has links to the wizards and tabs to perform each task.

Use the Overview tab of the platform editor for these tasks:

• Changing the ID, description, or platform home directory for the platform.
• Adding and removing region types for the platform. The Overview tab has basic functions to create new region types, or adopt region types from an existing topology. To modify the region types and work with the CICS regions in them, use the Region Types tab. Double-clicking on the name of a region type takes you to that region type in the Region Types tab.
• Adding and removing CICS bundles that are deployed with the platform. To edit any of these CICS bundles, double-click on the name of the bundle in the list in the platform editor to open the bundle manifest editor.

Use the Region Types tab of the platform editor for these tasks:

• Adding and removing region types for the platform. You can create new region types, or adopt region types from an existing topology.
• Creating new CICS region definitions in created region types.
• Specifying or editing the basic properties for CICS region definitions in created region types.
• Adding and removing CICS region definitions in created region types, and sharing them between created region types. Any orphaned CICS region definition that is not currently in a region type is displayed at the top of the list. Select the region to add it to a region type.

The platform editor does not connect to the target CICSplex, so you cannot use it to add, remove, or share CICS regions in adopted region types. You can only work with CICS region definitions in created region types.

Use the Deployment tab of the platform editor to map the CICS bundles that are deployed with the platform to the region types in the platform. Use the switch button to switch between working with the region types, and working with the CICS bundles.

Application editor and bundle manifest editor

Use the application editor and bundle manifest editor to update your applications. Updating applications describes the process to follow to update an application and deploy the new version of the application on your platform. You must also update the application binding when you update the application. Check that the CICS Platform project for the target platform is present in your local workspace before you start working with an application or application binding.

The application editor has a single tab: the Overview tab. The list of actions on the Overview tab has links to wizards that you can use to create new CICS bundles or an application binding for the application, and to export the application and application binding to the platform home directory.

Use the Overview tab of the application editor for these tasks:

• Changing the ID, description, or version number for the application.
• Adding and removing CICS bundles for the application.
• Accessing the bundle manifest editor to update CICS bundles for the application.
• Accessing the bundle manifest editor to update application entry points.

To update a CICS bundle or application entry point, double-click on its name in the list in the application editor to open the bundle manifest editor. The bundle manifest editor has three tabs, Overview, Entry Points, and Policy Scopes. You can use the bundle manifest editor to create new resource definitions in the CICS bundle, remove resource definitions from the CICS bundle, add and remove dependencies on imported resources, create and edit application entry points, and define policy scopes. You can also access the resource editors to edit existing resources that are defined in the CICS bundle. Remember to increment the version number for the CICS bundle when you have completed your updates.

When you edit a CICS bundle or an application entry point (which is defined in a CICS bundle) for the application, and increment the version number for the CICS bundle, CICS Explorer® marks the old version with an error in the application editor. Remove the old version of the CICS bundle from the application bundle by selecting it and clicking Remove in the application editor. Include the updated CICS bundle in the application bundle by clicking Add in the application editor, and selecting the new version of the CICS bundle from the list of CICS bundles that are available in your workspace.

When you have completed all the updates to the application and the associated CICS bundles, remember to update the major, minor, or micro version numbers for the application bundle to reflect the level of changes that you have made, as described in Version control.

Application binding editor

Use the application binding editor to update the deployment information for your applications. Updating applications describes the process to follow to update an application and an application binding, and to use the application binding to deploy the new version of the application on your platform. Check that the CICS Platform project for the target platform is present in your local workspace before you start working with an application or application binding.

The application binding editor has two tabs: the Overview tab and the Deployment tab. The list of actions on the Overview tab has links to wizards that you can use to create CICS bundles to deploy with the application binding, and to export the application and application binding to the platform home directory.

Use the Overview tab of the application binding editor for these tasks:

• Changing the ID, description, or version number for the application binding.
• Changing the platform or application that are referenced by the application binding.
• Adding and removing CICS bundles that are deployed with the application binding.
• Accessing the bundle manifest editor to update CICS bundles that are deployed with the application binding.
• Accessing the bundle manifest editor to update policies for the application.

To update a CICS bundle or a policy, double-click on the name of the bundle or policy in the list in the application binding editor to open the bundle manifest editor. When you update a CICS bundle or a policy, remove the old version of the CICS bundle from the application binding bundle and add the new version, in the same way as for the application editor.

Use the Deployment tab of the application binding editor to map the CICS bundles for the referenced application, and also the CICS bundles that are deployed with the application binding, to the region types in the target platform. Use the switch button to switch between working with the region types, and working with the CICS bundles.

• Any CICS bundles that are not yet bound to any region type are marked with the letter X. Working with the CICS bundles, select each new CICS bundle and use the check boxes to specify the region types where it is to be deployed.
• Any region types that are specified in the application binding, but cannot be found in the current version of the platform project associated with the application binding, are marked with an exclamation point. Check that you are working with the correct version of the platform project, and view the platform project in the platform editor to verify the region types. If you have removed the region type from the platform, or changed to a platform that does not include the region type, clean up the application binding project. Working with the region types, select each unwanted region type and uncheck all the CICS bundles specified for that region type.

When you have completed all the updates to the application binding and the associated CICS bundles, remember to update the major, minor, or micro version numbers for the application binding bundle to reflect the level of changes that you have made, as described in Version control.

Version control

You manage different versions of applications by using version control. Each CICS bundle, application bundle, and application binding has an ID and version information to uniquely identify it. The version uses major, minor, and micro identifiers, so you can indicate the significance of a change and manage the dependencies between bundles. This concept is called semantic versioning and is taken from the OSGi Alliance. Although it focuses on Java™ packages, you can use the same principles to apply to bundles in general.

Semantic versioning provides a way to increment the major, minor, or micro parts of a version to indicate the compatibility or incompatibility with previous versions of a bundle. For example, bug fixes might increment the micro part of the version, compatible changes increment the minor part of the version, and incompatible changes increment the major part of the version. For more information about semantic versioning, see Semantic Versioning Technical Whitepaper.

You must apply a versioning policy to your CICS bundles, application bundles, and application bindings to deploy and manage updates in the CICS environment. You cannot use an existing version of an application bundle to deploy new versions of the CICS bundles for the application, and you cannot use an existing version of an application binding with a new version of an application bundle. You must update the versions of the application bundle and application binding whenever you update the CICS bundles for the application.

When you change the version of an application, according to the principles of semantic versioning, the new version should reflect the largest change in a CICS bundle that is included in the application. For example, you might change one CICS bundle for an application from Version 1.0.1 to Version 1.0.2, which is a micro version change, and change another CICS bundle for the application from Version 1.2.0 to Version 1.3.0, which is a minor version change. The application bundle that includes these two CICS bundles should therefore have a minor version change, so if the application was previously at Version 2.5.1, it should change to Version 2.6.0.

The version number for the application binding does not have to be the same as the version number for the associated application. However, according to the principles of semantic versioning, you should update the version number for the application binding to reflect the largest change in the application, or in the CICS bundles deployed with the application binding.

Online application editor

Use the online application editor to view applications that are installed on a platform. You cannot make changes to the format of the installed application using this editor.

The online application editor has three tabs, Overview, Private Resources, and Attributes. The list of actions on the Overview tab has links to the other tabs.

Use the Overview tab of the online application editor for viewing general information about the installed application version, including the ID, description, and version number, the status of the application version, the CICS bundles that are part of the application, and the application entry points.

• You can make the application version available to callers through its application entry points using the Make Available and Make Unavailable buttons on this tab.
• You can enable, disable, or discard the application version using the Enable and Disable buttons on this tab.
• The option to discard the application version is available as a selection from the Disable button.

You cannot make changes to the format of the installed application using this editor. To change the format of the installed application, modify and reversion the application project in your local workspace from the Project Explorer view, then export and install the new version of the application.