zPET - IBM Z and z/OS Platform Evaluation and Test - Group home

The Coupling Facility Resource Management (CFRM) policy describes the definition and properties of Coupling facilities (CF) and CF structures that can be used in a Parallel Sysplex. The CFRM policy is stored in a Couple Data Set (CDS). Traditionally, when the definitions of CFs or structures needed to be modified, a z/OS system programmer had to modify the CFRM policy’s text and then submit the administrative data utility, IXCMIAPU, via JCL to write the policy to the CFRM CDS. This method, which has been used for decades, requires the system programmer write the corresponding CF or CF structure attribute definition very carefully. It is easy to introduce human error, and it is not efficient when many changes need to be made.

Recently, IBM z/OSMF released an important feature, the CFRM Policy Editor, that provides support for modifying CFRM policy definitions through the graphical user interface of z/OSMF, without having to know or understand JCL or CFRM policy control syntax. As you work, the editor checks your changes for correct syntax. This feature can help simplify CFRM policy modification operations by providing easy-to-use options for viewing and modifying CFRM policies as well as allowing more efficient batch modifications of structure definitions and thereby reducing the opportunity to make human errors.

To see more details about CFRM Policy Editor, please refer to https://www.ibm.com/docs/en/zos/2.5.0?topic=policies-cfrm-policy-editor

In this article, we will share some insights from our test team on using the CFRM Policy Editor.

1. Modifying the properties of multiple CF structures in batch

(1) First, click the Add button in the Coupling Facility page of the CFRM Policy Editor as follows:

(2) In the popup window, enter the properties of the new CF and click the Add button to add structures to it as follows:

(3) In the option "Select CF Structures" we select a dozen structures and then in the Preference List option, select First as follows:

(4) Click the OK button will return to the previous window with the structures we have selected listed as follows:

(5) Continue clicking the OK button and click the Submit button in the pop-up window to submit the changes as follows.

(6) The following message box will pop up after a successful submission, telling the user their selected policy has been updated:

(7) At this point, the policy modification in the CFRM CDS has been completed. To Activate, simply select policy name, then select Activate from the Actions drop-down menu. As follows:

Batch modifications to multiple structures can occur in many scenarios. For example, suppose we deployed an application a few years ago, for which we defined several CF structures. As the business grew, the amount of data increased accordingly. The structure sizes we defined before may not be able to support the growing business data adequately. Assuming the memory needs for multiple structures increased by 20% due to this growth, with the CFRM Policy Editor, we can now select these structures from within a policy and enter a 20% increase in the Modify CF Structures window’s Relative tab. We show this example below, after which simply clicking OK will increase the memory definition for all selected structures by 20%.
 
 
Activating the updated policy from the CFRM Administrative Policies page is all that is needed to make it effective, making this a simple 3 step point and click exercise versus multiple batch steps with error-probe text editing.

2. Backing up CFRM policy data

As we mentioned, the traditional way to modify a CFRM policy is to write the definitions of CF and structures in syntactically correct text form and then submit the administrative data utility, IXCMIAPU, to read this text as input via JCL to write the policy to the CFRM CDS.
However, when using z/OSMF CFRM Policy Editor to modify the policy, we directly modify the definitions of CF and structures in the CFRM CDS. If the CFRM CDS is damaged, we lose the definitions of CF and structures. We have used several methods to back up the policy definitions from the CFRM CDS which we’ll share here:

(1)  Schedule batch JCL to periodically export the policy for backup

The first way is to periodically back up the policy in CFRM CDS using JCL to run the IXCMIAPU with the REPORT(YES) option. To do this, we configured our test environment automation policy to run such JCL once a week to perform a backup of the policy's REPORT(YES) output using GDGs. The advantage of this method is that it is automatically and periodically executed without manual intervention. A new backup is saved every week. In case of problems, we can fall back to the latest saved version for recovery. The disadvantage is that changes made between the last backup and the current time are not saved. It requires the policy administrator to manually perform some adjustments after recovery to ensure full data integrity. Therefore, we require that every modification of our CFRM CDS be recorded using an established change management process, to facilitate the search of all modifications for any given timeframe.
Here is sample JCL of how we accomplish the backup:

The output is put into one GDG data set and looks like:

(2) Use the Export function to back up the CFRM policy

The second method is to use the Export function of z/OSMF CFRM Policy Editor to export the policy definition directly from the CDS to a data set or a USS file.
Simply select Export from the Actions and provide the output data set name or USS filename from the popup window as below.

 It is important to note that either the data set or the file under USS must be manually predefined in advance. Here is an example of a data set defined in our test environment.

Specifying the data set name in the Export panel will successfully export the policy definition.

Pre-creating files under USS is as simple as using the touch command, as shown in the following example:

The policy definition in CFRM CDS can be successfully exported to this file by naming the USS file in the Export panel. The contents of the exported file will look like this, the same as the contents of the exported data set.

Similarly, when needed, select Import from the Actions and provide the input data set name or USS filename from the popup window and it then can import the policy successfully.

A very important tip that we’ve learnt using these first 2 methods: we all know that technology cannot solve every problem, and strict change management is of great importance to the resilience of enterprise systems like z/OS. Adopting the use of the Export function to back up the definition of the policy in CFRM CDS requires that each policy administrator export the policy according to the predefined change management rules established by your team after modifying the policy using the CFRM Policy Editor, so that in case of problems, you can use this newly exported data set or USS file for recovery.

(3) Use modern REST APIs for backups

Another option is to back up the policy is to use the z/OSMF-provided REST APIs for Sysplex management services. You can find the complete reference for the Sysplex management services at https://www.ibm.com/docs/en/zos/2.5.0?topic=services-sysplex-management.

For example, we can use the GET method /zosmf/sysplex/rest/v1/policies/CFRM/<pol- name> to programmatically make a backup of the CFRM policy called pol-name.
Here is a partial example of the output of GET policy call:

You can see that the output is in JSON format . We then can use the REST POST service to recover using this exported JSON as input when needed.

Finally, the Sysplex management REST services method not only allows for easily backing up our policy, but also provides fully equivalent support for an application or automation tool to programmatically edit and modify the policy using the POST method.

The examples and tips we shared above are just some of the use cases we’ve found useful with the z/OSMF CFRM Policy Editor, and we have embraced them all for managing our zPET CFRM policies. We hope that they show how the CFRM Policy Editor and Sysplex management services allow for multiple ways to easily update the policy definition in CFRM CDS with zOSMF. We welcome your feedback and want to hear about your usage of the CFRM Policy Editor, so please reach out.

Authors：

Zhao Yu Wang

wangzyu@cn.ibm.com

Kieron Hinds

kdhinds@us.ibm.com