Updating applications

When you make changes to the CICS® bundles for the components of an application, update the versions of the CICS bundles, the application bundle, and the application binding, and deploy the new versions on the platform.

Before you begin

When you update an application that is deployed on a platform, the application is unavailable to users from the time when you disable and discard the installed APPLCTN resource in the CICSplex for the previous version of the application, to the time when you install the new APPLDEF resource definition and enable the new version of the application. Plan a suitable time when this can safely occur, or plan an alternative solution for users of the application during that time.

To update an application, you need to edit the application project and the application binding project. 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 as described in these instructions, you might prefer to copy them to another project and then edit the new copies.

About this task

You manage changes to 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 and management bundles to deploy and manage updates in the CICS environment. You cannot use an existing version of an application bundle to install 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 application bundle and application binding whenever you update the CICS bundles for the application.

When you change the version of a management bundle, according to the principles of semantic versioning, the new version should reflect the largest change in a CICS bundle that is included in the management bundle. 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 bundle was previously at Version 2.5.1, it should change to Version 2.6.0.

Procedure

  1. Click Window > Show view > Project Explorer to open the Project Explorer view.
  2. Locate the application project, expand the META-INF folder for the application project, and double-click on the application.xml file or the bundles.xml file. The application editor opens. For a guide to using the application editor, see The application editor.
    Tip: If CICS Explorer® finds an error in the XML files for the application bundle, or another important problem, information about the error or problem is displayed in the Problems view.
  3. To include further CICS bundles in the application bundle, click Add. Select the appropriate CICS bundles from the list of CICS bundles that are available in your workspace.
  4. To remove CICS bundles that are currently included in the application bundle, select the CICS bundles and click Remove.
  5. To edit any of the CICS bundles that are included in the application bundle, double-click on the name of the CICS bundle in the list in the application editor to open the bundle manifest editor.
    1. Use the bundle manifest editor to add and remove dependencies from the CICS bundle, create new application entry points, and define policy scopes.
    2. To edit resources that are defined in the CICS bundle, use the resource editors, as described in Editing resources defined in a CICS bundle project.
    3. When you have updated a CICS bundle, use the bundle manifest editor to increment the major, minor, or micro version numbers for the CICS bundle according to your versioning policy, and save your changes.
    4. Remove the old version of the CICS bundle from the application bundle by selecting it and clicking Remove in the application editor. When you update the version number for the CICS bundle, CICS Explorer marks the old version with an error in the application editor.
    5. 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.
  6. To edit any of the entry points for the application, double-click on the name of the application entry point in the list in the application editor to open the bundle manifest editor. When you have updated the application entry point, use the bundle manifest editor to increment the major, minor, or micro version numbers for the CICS bundle according to your versioning policy, and save your changes. Include the updated CICS bundle containing the application entry point in the application bundle, and remove the old version.
  7. When you have completed your updates to the application, use the Version field in the application editor to increment the major, minor, or micro version numbers for the application according to your versioning policy, then save your changes.
  8. Next, you can either update the existing application binding to specify the new version of the application, or create a new application binding for the new version of the application.
    • To create a new application binding for the new version of the application, click Create an application binding in the application editor to open the application binding wizard, and follow the steps in the wizard.
    • To update the existing application binding, in the Project Explorer view, locate the existing application binding for the application, expand the META-INF folder for the application binding project, and double-click on the application.xml, bundles.xml, or deployment.xml file. The application binding editor opens. For a guide to using the application binding editor, see The application binding editor.
  9. In the application binding editor, click Browse by the application name, and select the new version of the application.
  10. Make any changes that you require to the CICS bundles that are deployed with the application binding.
    1. Click Add or Remove to change the selection of CICS bundles that are deployed with the application binding.
    2. Double-click on any of the CICS bundles to edit them. Update and reversion the CICS bundles and add the new versions to the application binding, in the same way as described in 5 for the CICS bundles for the application.
  11. To edit any of the policies that are deployed with the application binding, double-click on the name of the policy in the list in the application editor to open the bundle manifest editor. When you have updated the policy, use the bundle manifest editor to increment the major, minor, or micro version numbers for the CICS bundle according to your versioning policy, and save your changes. Include the updated CICS bundle containing the policy in the application binding, and remove the old version.
  12. On the Deployment tab of the application binding editor, check that each of the CICS bundles for the application, and each of the CICS bundles deployed with the application binding, is bound to a suitable region type. Use the switch button The switch button to switch between working with the region types, and working with the CICS bundles.
    1. 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.
    2. 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. 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.
  13. When you have completed your updates to the application binding, use the Version field in the application binding editor to increment the major, minor, or micro version numbers for the application binding according to your versioning policy, then save your changes.
    Tip: The version number for the application binding does not have to be the same as the version number for the 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.
  14. Click Export Wizard in the application editor or the application binding editor to deploy the updated application and application binding to the platform home directory on z/OS® UNIX. The new version number is used as part of the name for the directory, so the previous versions of the application and application bundle remain in the platform home directory.
  15. Create a new APPLDEF resource definition to point to the updated application directory. To create an APPLDEF resource definition during the export process, select the checkbox in the export wizard.
  16. Disable and discard the installed APPLCTN resource that represents the previous version of the application.
  17. Install the new APPLDEF resource definition.

Results

The new version of the application is deployed on the platform. The CICS bundles that are included in the new version of the application bundle are installed in the appropriate CICS regions, and the resources that are defined inside the CICS bundles are dynamically created in the CICS regions.