CF Structures tab

The CFRM Policy Editor opens with the CF Structures tab in focus. On this tab, you can create, edit, and delete CF structures for the selected CFRM policy.

In a CFRM policy, the STRUCTURE statement specifies the definition of a structure within the scope of the named policy. The limit for the number of structures that can be defined in a policy is established when the CFRM couple data set is formatted.

Authorization requirements for the CFRM Policy Editor

You must have sufficient authorization to use the functions that are available in the CFRM Policy Editor. For more information, see Authorization requirements.

Layout of the CF Structures tab

The CFRM Policy Editor displays the following information about the selected policy:
  • Policy name, which specifies the 1 - 8 character name of the policy. The valid characters are uppercase alphanumeric characters (A-Z and 0-9). The name must begin with an alphabetic character (A-Z).
  • Sysplex name, which specifies the 1 - 8 character name of the sysplex in which the couple data set is to be used. The valid characters are uppercase alphanumeric characters (A-Z and 0-9) and national characters ($,@,#). The name must begin with an alphabetic character (A-Z).
  • Number of CF structures
  • Number of coupling facilities

The central feature of the CF Structures tab is the CF Structures table, which displays the CF structures and their attributes. In this table, you select actions for editing the CF structures.

For a description of the columns in the CF Structures table, see Columns in the CF Structures table. For a description of the actions that you can take for CF Structures, see Actions for the CF Structures tab.

Columns in the CF Structures table

Table 1 describes the columns in the CF Structures table. Notice that each field name in the editor corresponds to a CFRM policy control statement. The CFRM control statements are not visible in the CFRM policy editor; to see them, use the View Content action in the CFRM Administrative Policies view. With the CFRM Policy Editor, you can create, update, and delete CFRM policies without having to write CFRM control statements.

By default, the structure names in the table are sorted in ascending alphabetical order. To sort the table based on the values in one or more columns, click the column header for the columns you want to sort. If a sort is defined for a column, the ascending (▴) or descending (▾) sort icon is shown in the column header.

Table 1. Attributes of CF Structures
Column Policy control statement Description
Structure Name NAME(strname) Specifies the 1-16 character name of the structure. The valid characters are numeric characters, uppercase alphabetic characters, national characters ($,@,#), or an underscore (_). The name must start with an alphabetic character (A-Z). IBM names begin with SYS, or the letters A through I.

Structures that are used for XCF signaling must begin with the letters IXC.

Structure Name is a required parameter.
Maximum Size SIZE(size[u]) Specifies the maximum amount of space to be allocated for the structure in the coupling facility. The number is specified in an integer unit of u, where u is specified as K (kilobytes), M (megabytes), G (gigabytes), or T (terabytes). K is the default unit when no size unit is specified. The number can be 1 - 9 decimal digits long.

The maximum structure size is the largest to which the structure can be altered. If a structure size larger than the maximum is required, you must modify the CFRM policy to specify the larger size. When you start the modified policy, the system can reallocate the new structure, which can be disruptive to your operation.

Specifying too large a maximum structure size can waste coupling facility resources. Especially when the SIZE is significantly larger than INITSIZE, it might even cause the structure to become unallocatable, depending on the coupling facility and its CFLEVEL.

Maximum Size is a required parameter. The largest size that can be specified is 1T. Sizes larger than 1T causes message IXC730I to be displayed indicating that the number specified is not within the allowable range for the keyword value.
Initial Size INITSIZE(initsize[u]) Specifies the initial amount of space to be allocated for the structure in the coupling facility. The number is specified in an integer unit of u, where u is specified as K (kilobytes), M (megabytes), G (gigabytes), or T (terabytes). K is the default unit when no size unit is specified. The number must be 1 - 9 decimal digits long. The INITSIZE value must be less than or equal to the SIZE value. Otherwise, the system issues error message IXC745I.

Initial Size is an optional parameter. If not specified, the system uses the Maximum Size parameter. The largest size that can be specified is 1T. Sizes larger than 1T causes message IXC730I to be displayed indicating that the number specified is not within the allowable range for the keyword value.
Minimum Size MINSIZE(minsize[u]) Specifies the smallest size to which the structure can ever be altered, preventing allocation of an unusable structure. The number is specified in an integer unit of u, where u is specified as K (kilobytes), M (megabytes), G (gigabytes), or T (terabytes). K is the default unit when no size unit is specified.

Structure alter can be initiated by operator command, programming interface, or automatic alter (see ALLOWAUTOALT). Minimum Size also serves as a minimum bound for the structure size on all structure allocation requests with an exception that system-managed rebuild can allocate the rebuild new structure with a size smaller than the MINSIZE value. This can occur when there is not enough space in any of the coupling facilities in the preference list to satisfy the MINSIZE requirement for the allocation of the rebuild new structure, but there is enough space in at least one of the coupling facilities in the preference list to allocate the rebuild new structure with a size that allows in use objects to be copied from the rebuild old structure. In this case, instead of stopping the system-managed rebuild because the MINSIZE requirement is not satisfied, the system allows the rebuild to continue.

The number can be 1 - 9 decimal digits long. The MINSIZE value must be less than or equal to the INITSIZE value, or less than or equal to the SIZE value if INITSIZE is not specified.

Minimum Size is an optional parameter. The largest size that can be specified is 1T. Sizes larger than 1T cause message IXC730I to be displayed indicating that the number specified is not within the allowable range for the keyword value. If not specified and ALLOWAUTOALT(NO) is specified or defaulted to, the MINSIZE is 0. If not specified and ALLOWAUTOALT(YES) is specified, the system sets MINSIZE to 75% of INITSIZE, or to 75% of SIZE if INITSIZE is not specified.
Preference List PREFLIST(cfname1,cfname2,...,cfname8) Specifies an ordered list of coupling facility names from which the system is to choose when allocating a structure in a coupling facility. If ENFORCEORDER(NO) is specified, the system attempts to allocate the structure in the first coupling facility in the preference list that meets the following allocation criteria that are regulated by the duplex site preference, and listed in order of relative importance from most important to least important as described in "How MVS uses the lists" in z/OS MVS Setting Up a Sysplex.

The system assumes certain criteria when selecting a coupling facility for new structure allocation in structure duplexing. The system always assumes LOCATION=OTHER when selecting the coupling facility. The coupling facility that is chosen by the system will, if possible, be failure-independent with respect to the coupling facility containing the old structure. Lastly, if the level of connectivity to the new structure is less than that to the old structure, the action that is taken by the system is LESSCONNACTION=TERMINATE.

In system-managed duplexing rebuild, the system also requires that the coupling facility for the new structure allocation have CF-to-CF connectivity to the coupling facility that contains the structure to be duplexed. See the topic "Selecting a coupling facility for the duplexed pair of structures" in z/OS MVS Setting Up a Sysplex for a description of the criteria used by the system when allocating a duplexed structure in a coupling facility.

If no coupling facility in the preference list meets all of the criteria, the system determines the coupling facility that most closely meets the criteria. See z/OS MVS Setting Up a Sysplex for information about how the system chooses the coupling facility in the preference list that most closely meets the requirements of the connect request.

If the structure you are defining can reside only in a coupling facility with a certain attribute (such as CFLEVEL or non-volatility), be sure to include only those coupling facilities in the preference list for the structure. Two or more coupling facilities are required when you specify DUPLEX(ALLOWED) or DUPLEX(ENABLED).

If ENFORCEORDER(YES) is specified, the system will not reorder the coupling facilities in the preference list, which is regulated, but will attempt to allocate the structure in the exact order specified in the preference list, by the SAMESITEONLY duplex site preference. Therefore, when constructing your preference list, be sure to place the coupling facilities with the preferred attributes before any coupling facilities without the wanted attributes.

For more considerations, see “Developing preference and exclusion lists” in “Understanding Preference and exclusion lists” in z/OS MVS Setting Up a Sysplex.

ENFORCEORDER(YES) is mutually exclusive with EXCLLIST.

PREFLIST is a required parameter.
Exclusion List EXCLLIST(strname1,strname2,...,strname8) Specifies the list of 1 to 8 coupling facility structure names with which this structure should not share the coupling facility. The system attempts to honor the exclusion request, but will not fail a request to allocate a structure when all other requirements for structure allocation are satisfied and the exclusion list cannot be honored. However, if all other attributes are equal, a coupling facility containing only one instance of a duplexed structure from the exclusion list is selected over a coupling facility containing a simplex structure from the exclusion list.

EXCLLIST is mutually exclusive with ENFORCEORDER(YES).

EXCLLIST is an optional parameter.
Duplexing Options DUPLEX(options) Specifies the installation's request for duplexing rebuild of the structure.
DISABLED
Neither user-managed nor system-managed duplexing rebuild can be started for the specified structure. If a duplexing rebuild is in progress, it is stopped.
ALLOWED
The application can initiate its own user-managed or system-managed duplexing rebuild or an operator can start either method of duplexing rebuild with the SETXCF START,REBUILD,DUPLEX command. However, except for duplexing being stopped for the structure and then duplexed again within a REALLOCATE process, the system does not attempt to maintain the duplexed status of the structure. The application or operator must initiate another duplexing operation if the current duplexing is stopped.
ENABLED
The system initiates and attempts to maintain a user-managed or system-managed duplexing rebuild for the structure. When a duplexing rebuild process is stopped, the system attempts to initiate duplexing again. If the operator stops the duplexing operation, the system ensures that, for the system's first attempt to duplex the structure again, the coupling facility that is most recently used to contain the previous instance of the duplexed structure is not used again to contain the structure. However, for any attempts thereafter to duplex the structure again, the system might choose the same coupling facility for allocation that the structure vacated.

Coupling facility maintenance might require you to move an instance of a duplexed structure from a coupling facility. See z/OS MVS Setting Up a Sysplex for more information.

DUPLEX is an optional parameter. DISABLED is the default, when DUPLEX is not specified.

Allow Automatic Alter ALLOWAUTOALT(NO|YES) Specifies the installation's request to allow system-initiated alters (automatic alter) for this structure. For structure alter processing to be started for a structure, alter must be permitted (see the SETXCF MODIFY command) and the exploiter must also allow alter. The ALLOWAUTOALT specification affects the default value for MINSIZE.

See FULLTHRESHOLD and MINSIZE for related information.

ALLOWAUTOALT takes effect immediately with policy activation.

ALLOWAUTOALT is an optional parameter. NO is the default, when ALLOWAUTOALT is not specified.
Full Threshold Percentage FULLTHRESHOLD(value) Specifies a percentage value that is used by the system to control structure full monitoring and automatic alter (see ALLOWAUTOALT). The value specifies a percent full threshold for the structure. For a cache structure, the percent full is based on changed coupling facility structure objects. For a list or lock structure, the percent full is based on in use coupling facility structure objects. This number is specified as a percentage and can be 1 - 3 decimal digits long (0-100). The number must be greater than or equal to 0 and less than or equal to 100.

Specifying 0 results in no structure full monitoring or automatic alter processing for the structure. If a value other than 0 is specified or defaulted to for FULLTHRESHOLD, the value is used as a percent full threshold for structure full monitoring.

If the exploiter allows alter, ALLOWAUTOALT(YES) is specified, starting alter processing for the structure is permitted, and the FULLTHRESHOLD value is reached, automatic alter processing can be initiated. When the FULLTHRESHOLD value is reached, structure full monitoring alerts the installation through an IXC585E message and automatically starts structure alter processing to relieve the storage shortage for the object whose storage is in short supply. Before starting the structure alter, automatic alter issues message IXC588I to the system log to externalize the alter request.

If the exploiter does not allow alter, or starting alter processing for the structure is not permitted, the ALLOWAUTOALT specification is ignored and a nonzero value for FULLTHRESHOLD is only used by structure full monitoring to alert the installation.

FULLTHRESHOLD takes effect immediately with policy activation.

FULLTHRESHOLD is an optional parameter. 80% is the default, when FULLTHRESHOLD is not specified.
Encrypt ENCRYPT(YES|NO) Specifies whether list and cache structure entry data and entry adjunct data that is written to the structure and residing in the structure should be encrypted. The structure entry and entry adjunct data is in an encrypted format while the data is being transferred to and from the coupling facility and while the data resides in the coupling facility structure. Encrypted data is decrypted when read from the structure.

XCF uses Advanced Encryption Standard (AES) 256-bit keys encrypted under an AES primary key to encrypt and decrypt structure data.

See z/OS MVS Setting Up a Sysplex for information on system requirements that must be met before you use ENCRYPT on a structure definition and allocate encrypted structures.

Ensure that users of the CFRM Policy Editor have at least READ access to defined ICSF CSFSERV CSFKGN and CSFSERV CSFKYT resource profiles when ENCRYPT(YES) is specified on a structure definition.

All systems in the sysplex must be at z/OS V2R3 or higher for this parameter to be fully effective. Before you use the ENCRYPT parameter, IBM recommends that you make sure that all systems in the sysplex are running z/OS V2R3 or higher.

Systems running on a lower level of z/OS (V2R2 or earlier) in the sysplex are unable to encrypt and decrypt structure data. Connection requests from a lower-level system to an encrypted structure are not allowed.

Rebuild Threshold Percentage REBUILDPERCENT(value) Specifies, as a percent of lost connectivity to a structure, when MVS™ is to initiate a user-managed rebuild. Use of REBUILDPERCENT requires that all active connections to the structure support user-managed rebuild and that the structure is not being used for XCF signaling.

This number is specified as a nonzero percentage and can be 1 - 3 decimal digits long (1-100).

REBUILDPERCENT takes effect immediately with policy activation.

REBUILDPERCENT is an optional parameter. When REBUILDPERCENT is not specified, the default value is 1%.

See z/OS MVS Setting Up a Sysplex for information about MVS-initiated rebuild.
Recovery Priority RECPRTY(value) This statement specifies the priority to be given to the structure for LOSSCONN recovery (system loses connectivity to a coupling facility) and policy-initiated duplexing for DUPLEX(ENABLED) structures. The system might defer processing for a "less important" (higher numeric priority value) structure to prevent the "less important" recovery processing from interfering with recovery processing for a "more important" (lower numeric priority value) structure. LOSSCONN recovery for a "more important" structure might be impacted when that recovery depends on processing for a "less important" structure. For this reason, be careful when assigning a RECPRTY value.

This number is specified as a 1-digit decimal value (1-4).

RECPRTY does not apply to XCF signaling structures.

RECPRTY takes effect immediately with policy activation.

RECPRTY is an optional parameter. When RECPRTY is not specified, the system takes a default. When the structure name is ISGLOCK, the default is 1. Otherwise, the default is 3.
Maximum SCM size SCMMAXSIZE(scmmaxsize[u]) Specifies the maximum amount of storage-class (flash) memory that is assignable for use by this structure in the coupling facility. The number is specified in an integer unit of u, where u is specified as K (kilobytes), M (megabytes), G (gigabytes), or T (terabytes). K is the default unit when no size unit is specified. Valid values for the number are 1 - 9 decimal digits long and greater than 0 if this keyword is specified.

Storage-class memory is not allocated to the structure until required for use. Therefore, it is possible to over-commit the storage-class memory that is configured to the coupling facility. It is possible to define the CFRM policy such that the sum of the SCMMAXSIZE values for allocated structures exceeds the total amount of storage-class memory that is available to the coupling facility.

Note: Do not over-commit storage-class memory. This ensures that you have the wanted amount of storage available if of an application failure that causes the structure to fill up.
SCMMAXSIZE is an optional parameter. If not specified, the coupling facility does not spill excess structure objects into storage-class memory for this structure. The following values are the largest values that you can specify:
  • 15T
  • 16383G
  • 16777215M
  • 999999999K or 999999999

For information about the use of storage-class memory to reduce the probability of structure-full conditions, see z/OS MVS Setting Up a Sysplex.
SCM Algorithm SCMALGORITHM(algorithm) Identifies the algorithm that the coupling facility uses to control the movement of structure objects between coupling facility real storage and storage-class memory to mitigate the performance penalty associated with its use.

The valid values of SCMALGORITHM and the structures that they support are described in the following table.

Note: Specification of SCMMAXSIZE and the related keywords for inappropriate structure types might have unpredictable results, potentially including connect failures or performance degradation.
SCMALGORITHM Value Description Structure Types
KEYPRIORITY1 The high-order byte of the list entry key is treated as a migration priority indicator for lists 1 - 512. Valid values for the priority byte are:
  • '00'x - '09'x, where lower values indicate higher priority.
  • 'F4' - 'F6'x are application-specific values.
 IBM MQ application structure

SCMALGORITHM is a required parameter when SCMMAXSIZE is specified and is not allowed for specification otherwise.
Enforce CF Order ENFORCEORDER(NO|YES) When ENFORCEORDER(YES) is specified, allocation attempts adhere to the PREFLIST more closely, giving it a higher priority than such factors as system weight connectivity and optimum size. Use of this option can help ensure failure-isolation between a coupling facility and the systems that use it (for example, when these resources reside on the same CEC).

ENFORCEORDER is an optional parameter. ENFORCEORDER(NO) is the default, when ENFORCEORDER is not specified.
Allow Reallocate ALLOWREALLOCATE(YES|NO) Specifies the installation's request for REALLOCATE processing when evaluation of the allocated structure determines that the structure needs rebuild processing. The REALLOCATE process recognizes the need for rebuild processing when:
  • There is a change to the policy definition for the structure affecting the structure size or location.
  • The structure is not optimally located.

The ALLOWREALLOCATE option provides the installation with a structure-level control to preclude REALLOCATE processing from targeting structures for relocation or policy change activation. This can be useful for structures for which rebuild processing is disruptive based on workload or usage.

By evaluating an allocated structure, the REALLOCATE process can recognize that the structure is optimally located and immediately complete a change to the policy definition for the structure when the change does not affect the size. Specifying ALLOWREALLOCATE(NO) does not preclude this capability of the REALLOCATE process because completing the pending policy change does not require relocation of the structure instances.

See the SETXCF START/STOP command in z/OS MVS System Commands for a description of the REALLOCATE process. See the topic "Using REALLOCATE or POPULATECF to relocate coupling facility structures" in z/OS MVS Setting Up a Sysplex for information about using REALLOCATE or POPULATECF to relocate coupling facility structures.

YES
The REALLOCATE process evaluates the allocated structure. When a policy change for size or location is pending or structure instances are not optimally located, the structure is selected as the target of the REALLOCATE process. The REALLOCATE process uses structure rebuild processing to make the adjustments.
NO
The REALLOCATE process evaluates the allocated structure but does not select the structure as the target of the REALLOCATE process for relocation or policy change activation. When NO is specified, it is still possible for the REALLOCATE process to take the following actions if they are applicable:

Changes to the ALLOWREALLOCATE specification take effect immediately with policy activation.

ALLOWREALLOCATE is an optional parameter. When ALLOWREALLOCATE is not specified, the default value is YES.
Sublist Notification Delay Interval (μs) SUBNOTIFYDELAY (delaytime) Specifies the number of microseconds for sublist notification delay time (SLND time). This value refers to delay between the time when a single selected shared message queue exploiter instance is notified of sublist transition from the empty to not-empty state and the time when the other instances are notified. It can be that the other instances are never notified depending on the processing that is done by the initial exploiter. See z/OS MVS Programming: Sysplex Services Guide for an explanation of the sublist monitoring function.

The value that is specified for SUBNOTIFYDELAY can be 1 - 7 decimal digits in a range of 0 to 1000000 (1 million) microseconds.

SUBNOTIFYDELAY applies only to structures that meet certain criteria and is ignored for all other structures. The structure criteria for the SUBNOTIFYDELAY parameter are:
  • The structure must be allocated as a keyed list structure.
  • The structure must have EMCs allocated.
  • The structure must be allocated in a CFLEVEL 16 or higher.

SUBNOTIFDELAY takes effect immediately with policy activation.

The SUBNOTIFYDELAY value cannot exceed the CF model-dependent Notification Delay Limit (NDL) value that is determined by the CF where the structure is allocated. Therefore, the SUBNOTIFYDELAY value that takes effect is the smaller of the SUBNOTIFYDELAY value and the CF-dependent NDL value.

SUBNOTIFYDELAY is an optional parameter. When SUBNOTIFYDELAY is not specified, the default value is 5000 microseconds.
List Notification Delay Interval (μs), LISTNOTIFYDELAY(listnotifydelay) Specifies the number of microseconds for the list notification delay time (LND time). This value refers to the delay between the time when a single registered list monitor is notified of a list state transition from the empty to not-empty state and the time when the other registered list monitor instances of a list are notified. It can be that the other instances are never notified, depending on the processing done by the initial notified monitor. See z/OS MVS Programming: Sysplex Services Guide for an explanation of the list monitoring function.
The value that is specified for LISTNOTIFYDELAY can be 1 - 7 decimal digits, in a range of 0 to 1000000 (1 million) microseconds. LISTNOTIFYDELAY applies only to structure meeting certain criteria and is ignored for all other structures. The structure criteria for the LISTNOTIFYDELAY parameter is as follows:
  • The structure must be allocated as a list structure.
  • The structure must be allocated in a CFLEVEL=22 or higher.

LISTNOTIFYDELAY takes effect immediately with policy activation. The LISTNOTIFYDELAY value cannot exceed the CF model-dependent NDL (Notification Delay Limit) value that is determined by the CF where the structure is allocated. Therefore, the LISTNOTIFYDELAY value that takes effect, is the smaller of the LISTNOTIFYDELAY value and the CF-dependent NDL value.

LISTNOTIFYDELAY is an optional parameter. When LISTNOTIFYDELAY is not specified, the default value is 0 microseconds.
Key Range Notification Delay Interval (μs) KEYRNOTIFYDELAY(value) Specifies the number of microseconds for the keyrange notification delay time (KRND time). This value refers to the delay between the time when a single registered keyrange monitor is notified of a keyrange state transition from the empty to not-empty state and the time when the other registered keyrange monitoring instances of a list keyrange are notified. It can be that the other instances are never notified, depending on the processing done by the initial notified monitor. See z/OS MVS Programming: Sysplex Services Guide for an explanation of the list monitoring by keyrange function.
The value that is specified for KEYRNOTIFYDELAY can be 1 - 7 decimal digits, in a range of 0 to 1000000 (1 million) microseconds. KEYRNOTIFYDELAY applies only to structure meeting certain criteria and is ignored for all other structures. The structure criteria for the KEYRNOTIFYDELAY parameter is as follows:
  • The structure must be allocated as a keyed list structure.
  • The structure must be allocated in a CFLEVEL=22 or higher.

KEYRNOTIFYDELAY takes effect immediately with policy activation. The KEYRNOTIFYDELAY value cannot exceed the CF model-dependent NDL (Notification Delay Limit) value that is determined by the CF where the structure is allocated. Therefore, the KEYRNOTIFYDELAY value that takes effect, is the smaller of the KEYRNOTIFYDELAY value and the CF-dependent NDL value.

KEYRNOTIFYDELAY is an optional parameter. The default value is 0 microseconds.

Actions for the CF Structures tab

The actions are described in the following tables:
  • Targeted actions. Actions that apply to the selected items. To use a targeted action, you must select one or more items.
  • Tab-level actions. Actions that apply to the entire tab. No selection of table items is required to enable these functions.
Table 2. Targeted actions for the CF Structures table
Action Description
Modify Display the Modify CF Structure page so that you can modify the properties of the selected structure. To enable this action, select one structure only. For more information, see Modify a CF structure.

It is possible to modify multiple CF structures at one time. For more information, see Modify multiple CF structures.
Rename Display the Rename CF Structure page so that you can change the name of the selected structure. To enable this action, select one structure only. For more information, see Rename a CF structure.
Copy Display the Copy CF Structure page so that you can work with the selected workflow. To enable this action, select one workflow only. For more information, see Copy a CF structure.
Delete Display the Delete CF Structure page so that you can permanently delete the selected structure. You can select multiple structures. For more information, see Delete a CF structure.
Export to CSV Downloads a CSV file containing the selected structures.

The format of the file name is {{Policy}}_Structure_{{date}}_{{random}}.csv,for example ALTERPOL_Structure_2022-2-15-10-6-18_6567280780785600008.csv.

Tab-level actions for the CF Structures tab

The CF Structures tab includes the actions Add, Close, and Submit.

Table 3 describes the tab-level actions for the CF Structures tab.
Table 3. Tab-level actions for the CF Structures tab
Action Description
Add Display the Add CF Structure page so that you can define a CF structure for one or more coupling facilities.

For more information, see Add a CF structure.
Close Exit the CFRM Policy Editor. Any unsaved changes to the policy are discarded.
Submit Submit all outstanding updates for the selected policy. This action saves your policy changes to the CFRM couple data set. You are prompted to confirm your action. After you submit the policy, you cannot undo your updates.

For more information, see Submit updates for a policy.