CFRM parameters for administrative data utility

The CFRM policy information describes the coupling facilities (CF) and structures (STRUCTURE) that can be used in the sysplex once an administrative policy is activated.

The syntax of the CFRM parameters for the Administrative Date Utility is shown in Figure 1
Figure 1. Syntax of CFRM parameters for the Administrative Data Utility

DEFINE POLICY NAME(polname) REPLACE(NO | YES | timestring)
CF NAME(cfname)
   TYPE(tttttt)
   MFG(mmm)
   PLANT(pp)
   SEQUENCE(nnnnnnnnnnnn)
   PARTITION(h | hh)
  [SIDE(0 | 1)]
  [CPCID(nn)]
  [DUMPSPACE(size[u])]
  [SITE(SITE1 | SITE2)]
STRUCTURE NAME(strname)
   SIZE(size[u])
  [INITSIZE(initsize[u])]
  [MINSIZE(minsize[u])]
  [SCMMAXSIZE(scmmaxsize[u])]
  [SCMALGORITHM(algorithm)]
  [ALLOWAUTOALT(NO | YES)]
  [FULLTHRESHOLD(value)]
   PREFLIST(cfname1,cfname2,...,cfname8)
  [EXCLLIST(strname1,strname2,...,strname8)]
  [REBUILDPERCENT(value)]
  [DUPLEX(DISABLED | ALLOWED[,dupopts] | ENABLED[,dupopts])]
  [RECPRTY(value)]
  [SUBNOTIFYDELAY(delaytime)]
  [LISTNOTIFYDELAY(listnotifydelay)]
  [KEYRNOTIFYDELAY(keyrnotifydelay)]  
  [ENFORCEORDER(NO | YES)]
  [ALLOWREALLOCATE(YES | NO)]
  [ENCRYPT(NO | YES)]
The SETXCF START,POLICY,TYPE=CFRM operator command is used to activate an administrative policy. If no policy is active for CFRM, then the specified administrative policy is activated immediately. Otherwise, a transition to the newly activated policy is required. For an allocated structure, some subparameters can take effect immediately. STRUCTURE subparameters that take effect immediately include:
  • ALLOWAUTOALT
  • FULLTHRESHOLD
  • REBUILDPERCENT
  • DUPLEX (see the DUPLEX parameter for special conditions)
  • ALLOWREALLOCATE
  • RECPRTY
  • SUBNOTIFYDELAY
  • LISTNOTIFYDELAY
  • KEYRNOTIFYDELAY

When running under z/VM®, see Setting up a guest coupling environment under z/VM for information about values that you must specify in the CFRM policy.

DEFINE POLICY NAME(polname)
Specifies the beginning of the definition of a new administrative policy. The limit for the number of policies that can be defined in a couple data set is established when the couple data set is formatted.

polname specifies the name of the policy. The name can be from 1 - 8 characters in length. Valid characters are A-Z and 0-9. The policy name must start with an alphabetic character.

A policy name can be defined only once in a single run of the administrative data utility.

See Coding the administrative data utility for other utility control statements; included here are only the portion that applies only to CFRM.

REPLACE(NO)
REPLACE(YES)
REPLACE(timestring)
See the REPLACE parameter under Coding the administrative data utility.
CF
Specifies the definition of a coupling facility within the scope of the named policy. The location of the information that is needed to define the coupling facility in a CFRM policy depends on the processor on which the coupling facility is installed.

The limit for the number of coupling facilities that can be defined in a policy is established when the CFRM couple data set is formatted.

The coupling facility must appear in the preference list of at least one coupling facility structure that is defined within the policy or the administrative policy utility flags the statement as an error.

NAME(cfname)
Specifies the 1 - 8 character length name of the coupling facility. The valid characters are uppercase alphabetic characters (A-Z), numeric characters (0-9), national characters ($,@,#), or an underscore (_). The cfname must start with an alphabetic character (A-Z).

Consider defining your coupling facility name to match the name of the LPAR in which the coupling facility is to run.

NAME is a required parameter.

The following set of parameters describe the unique coupling facility that is defined in the policy.

TYPE(tttttt)
Specifies the 6-character machine type. The valid characters are uppercase alphabetic characters (A-Z) and numeric characters (0-9), padded with leading zeros if necessary. TYPE is a required parameter.
MFG(mmm)
Specifies the 3-character manufacturer identification. The valid characters are uppercase alphabetic characters (A-Z) and numeric characters (0-9). MFG is a required parameter.
PLANT(pp)
Specifies the 2-character plant of manufacture code. The valid characters are uppercase alphabetic characters (A-Z) and numeric characters (0-9). PLANT is a required parameter.
SEQUENCE(nnnnnnnnnnnn)
Specifies the 12-character serial number. The valid characters are uppercase alphabetic characters (A-Z) and numeric characters (0-9), padded with leading zeros if necessary. SEQUENCE is a required parameter.
PARTITION(h) or (hh)
Specifies the 1- or 2-hexadecimal digit qualifier to uniquely identify and associate a coupling facility to a specific PR/SM partition.
  • If the coupling facility is defined on a System z9®, z990, and z890 processor, then the PARTITION value must match the partition ID associated on the activation profile for the CF image on the support element or hardware master console.
  • If the coupling facility is defined on a pre-z990 or pre-z890 or earlier processor, then the PARTITION value must match the partition number specified by HCD/IOCP in the IOCDS for that partition and can be in the range of 01-0F.
  • Otherwise, the PARTITION value can be in the range of 0-F and is the same as the partition number defined in HCD.

See Configuring a processor and a coupling facility for information about specifying the partition identifier.

PARTITION is a required parameter.

SIDE(0)
SIDE(1)
Specifies the 1-numeric character to identify the coupling facility to a specific physical side of a CPC running in Physically Partitioned mode. You should not split or merge physical sides on which a coupling facility resides.

Use caution when splitting or merging physical sides of a processor that contains a coupling facility.

SIDE is an optional parameter. Its omission implies that the coupling facility resides on a single image CPC.
  • SIDE(0) — Side 0 of a physically partitioned machine. Do not specify for a Single Image CPC.
  • SIDE(1) — Side 1 of a physically partitioned machine. Do not specify for a Single Image CPC.
CPCID(nn)
Specifies the 2-hexadecimal digit qualifier (00-FF) to identify a coupling facility to a specific CPC in a CMOS processor. CPCID is an optional parameter.
DUMPSPACE(size[u])
Specifies the amount of space to be reserved in the coupling facility for dumping structures allocated 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 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.

DUMPSPACE is an optional parameter. If omitted, no storage in the coupling facility is reserved for dumping.

For information about specifying the amount of dump space, see Determining the amount of coupling facility dump space.

SITE(SITE1)
SITE(SITE2)
Specifies the site at which the coupling facility resides. When specified, this information (along with status information from a Recovery Manager (for example, GDPS®)), will be used in break duplexing decisions to keep the structure instance at the recovery site. SITE changes take effect when the policy is activated.
Note: With APAR OA31601, the recovery site provided to XCF through IXCCFCM is ignored. The recovery site does not affect which structure is kept when coupling facility structure duplexing is stopped. IXCQUERY or the DISPLAY XCF command does not provide the recovery site. Because using the recovery site might cause you to lose duplexed coupling facility structure data in the event of a coupling facility failure at the recovery site, disabling use of the recovery site with APAR OA31601 helps you avoid the problem.

This keyword should be considered when specifying the DUPLEX dupsite and dupmode parameters as part of the STRUCTURE definition.

STRUCTURE
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.
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 strname 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.

NAME is a required parameter.

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 likely will 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.

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.

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.

INITSIZE is an optional parameter. If not specified, the system uses the 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.

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). MINSIZE will also serve as a minimum bound for the structure size on all structure allocation requests that occur on systems at OS/390® Release 10 and above (including connect and rebuild connect) 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 inuse objects to be copied from the rebuild old structure. In this case, instead of stopping the system-managed rebuild because the MINSIZE requirement could not be 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.

MINSIZE is an optional parameter. The largest size that can be specified is 1T. Sizes larger than 1T will 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 used will be 0. If not specified and ALLOWAUTOALT(YES) is specified, the system will set MINSIZE to 75% of INITSIZE, or to 75% of SIZE if INITSIZE is not specified.

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. It is therefore possible to overcommit 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 overcommit storage-class memory. This ensures that you have the desired amount of storage available in the event 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 on the use of storage-class memory to reduce the probability of structure-full conditions, see Requesting the use of storage-class memory.
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 in an effort 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.
Table 1. SCMALGORITHM value descriptions
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.
ALLOWAUTOALT(NO)
ALLOWAUTOALT(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.

FULLTHRESHOLD(value)
Specifies a percentage value 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 will result 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, then the value will be 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 will alert the installation through an IXC585E message and automatically start structure alter processing to relieve the storage shortage for the object whose storage is in short supply. Before starting the structure alter, automatic alter will issue 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.

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 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 Identifying the coupling facility structures.

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. As mentioned previously, the coupling facility 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 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 containing the structure to be duplexed. See Selecting a coupling facility for the duplexed pair of structures for a description of the criteria used by the system when allocating a duplexed structure in a coupling facility.

If there is no coupling facility in the preference list that meets all these criteria, then the system determines the coupling facility that most closely meets the criteria. See How MVS uses the lists 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 only reside in a coupling facility with a certain attribute (such as CFLEVEL or nonvolatility), 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, but will attempt to allocate the structure in the exact order specified in the preference list, regulated 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 desired attributes when ENFORCEORDER(YES) is specified.

Refer to “Developing preference and exclusion lists” in “Understanding Preference and exclusion lists” in Identifying the coupling facility structures for additional considerations.

ENFORCEORDER(YES) is mutually exclusive with EXCLLIST.

PREFLIST is a required parameter.

EXCLLIST(strname1,strname2,...,strname8)
Specifies the list of 1 to 8 coupling facility structure names with which this structure should not share the same 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 have been 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.

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 Specifying a rebuild threshold for information about MVS-initiated rebuild.

DUPLEX(DISABLED)
DUPLEX(ALLOWED[,dupopts])
DUPLEX(ENABLED[,dupopts])
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[,dupopts]
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, with the exception of duplexing being stopped for the structure and then duplexed again within a REALLOCATE process, the system does not make any attempts to maintain the duplexed status of the structure. The application or operator must initiate another duplexing operation if the current duplexing is stopped.
ENABLED[,dupopts]
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 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 just vacated.

Coupling facility maintenance might require you to move an instance of a duplexed structure from a coupling facility. In order to do this, see Guidelines for coupling facility reconfiguration for more information.

dupopts
One or more of the following, each separated by a comma:
dupsite
dupmode | (dupmode) | (dupmode1,dupmode2)
dupsite
The dupsite parameter is used to determine how a CF SITE is used when determining CF importance and eligibility for duplexed CF structure allocation. All systems in the sysplex must be at z/OS V2R2 or higher for this parameter to be fully effective. Because lower-level systems in the sysplex are unaware of this parameter, any CF structure allocation decisions performed by them are processed as if the dupsite parameter were not specified.
Specify the CROSSSITE, SAMESITE, or SAMESITEONLY keywords to influence CF structure allocation decisions. The dupsite parameter can be specified as one of the following values:
ANYSITE
CF SITE specification is not used when determining CF importance and eligibility for duplexed CF structure allocation. This is the default when the dupsite parameter is not specified.
CROSSSITE
It is preferred that the duplexed structure instances be allocated across sites according to the CF SITE specification.
SAMESITE
It is preferred that the duplexed structure instances be allocated in the same site according to the CF SITE specification.
SAMESITEONLY
It is required that the duplexed structure instances be allocated in the same site according to the CF SITE specification.
dupmode|dupmode1|dupmode2
This parameter is used to determine whether synchronous or asynchronous duplexing should be used. This parameter can only be used when the couple data set is formatted with ASYNCDUPLEX. All options can be used for lock structures. Only the default option can be used for other structure types.

This parameter can be used in a pair of parameters that determine whether synchronous or asynchronous duplexing should be used. When used as a pair, the more synchronous option applies to same-site duplexing. The other option is used for other configurations. For example, if one of the options is SYNCONLY, same-site duplexing is done synchronously. If one of the options is ASYNCONLY, same-site duplexing uses the other option.

SYNCONLY
The structure is duplexed by using synchronous duplexing only. Either user-managed duplexing or system-managed synchronous duplexing is used. This is the default when the dupmode parameter is not specified.
ASYNCONLY
The structure is duplexed by using asynchronous duplexing only. System-managed asynchronous duplexing is used.

When this keyword is used, system-managed duplexing rebuild allocation for the structure requires a CFLEVEL that supports asynchronous duplexing (CFLEVEL>=21).

ASYNC
The structure is duplexed by using asynchronous duplexing, if possible. If not possible, the structure is duplexed by using synchronous duplexing. Asynchronous duplexing might not be possible due to CFLEVEL or due to lack of connector or application support.

DUPLEX(DISABLED) and the default dupmode of SYNCONLY both indicate that a structure will be allocated without the ability to participate in asynchronous duplexing. Other uses of dupmode indicate a structure should be allocated with the ability to participate in asynchronous duplexing. A policy change becomes pending if it changes the asynchronous duplexing indication. Otherwise, a change to the DUPLEX parameter takes effect immediately with policy activation.

Examples: You might want to consider asynchronous duplexing for a structure that uses DUPLEX(DISABLED). You might have not done duplexing because the “mainline” costs were too high. You might want to introduce asynchronous duplexing given that it does not have the “mainline” overhead of synchronous duplexing, and the benefits of asynchronous duplexing outweigh the costs of not duplexing. The structure would be changed to DUPLEX(ENABLED,ASYNCONLY).

You might want to consider asynchronous duplexing for a structure that uses DUPLEX(ENABLED). You would like to migrate to asynchronous duplexing to eliminate the “mainline” overhead of synchronous duplexing. The structure would be changed to DUPLEX(ENABLED,ASYNC).

You might want to consider asynchronous duplexing for a structure that uses DUPLEX(ENABLED,SAMESITEONLY). For SAMESITE duplexing, you might not want to introduce the potential duplexing failover penalty that is associated with asynchronous duplexing. But you might want to introduce CROSSSITE asynchronous duplexing given that it does not have the “mainline” overhead of synchronous duplexing, and the benefits of asynchronous duplexing outweigh the costs of NOT duplexing. The structure could be changed to DUPLEX(ENABLED,(SYNCONLY,ASYNCONLY)).

You might want to consider asynchronous duplexing for a structure that uses DUPLEX(ENABLED,SAMESITE). For SAMESITE duplexing, you might not want to introduce the potential duplexing failover penalty that is associated with asynchronous duplexing. But you might want to eliminate the “mainline” overhead of asynchronous duplexing when duplexed CROSSSITE. The structure would be changed to DUPLEX(ENABLED,(SYNCONLY,ASYNC)).

Table 2. DUPLEX keywords. This table shows the relationships between duplexing mode and the DUPLEX keyword.
DUPLEX keywords Duplexing mode Same-site duplexing Cross-site duplexing
DISABLED - - -
+SAMESITEONLY ,ASYNCONLY Async -
+SAMESITEONLY ,ASYNC Async/Sync -
+SAMESITEONLY [,SYNCONLY] Sync -
*other ,ASYNCONLY Async Async
*other ,(ASYNC,ASYNCONLY) Async/Sync Async
*other ,(SYNCONLY,ASYNCONLY) Sync Async
*other ,ASYNC Async/Sync Async/Sync
*other ,(SYNCONLY,ASYNC) Sync Async/Sync
*other [,SYNCONLY] Sync Sync
+ = {ALLOWED|ENABLED}
*other = {ALLOWED|ENABLED} [,SAMESITE|ANYSITE|CROSSSITE]

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

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 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 to 7 decimal digits in a range of 0 to 1000000 (1 million) microseconds.

SUBNOTIFYDELAY only applies to structures meeting 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. The default value when SUBNOTIFYDELAY is not specified is 5000 microseconds.

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 to 7 decimal digits, in a range of 0 to 1000000 (1 million) microseconds. LISTNOTIFYDELAY only applies 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. The default value when LISTNOTIFYDELAY is not specified is 0 microseconds.

KEYRNOTIFYDELAY(KEYRNOTIFYDELAY)
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 to 7 decimal digits, in a range of 0 to 1000000 (1 million) microseconds. KEYRNOTIFYDELAY only applies 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 when KEYRNOTIFYDELAY is not specified is 0 microseconds.

ENFORCEORDER(NO)
ENFORCEORDER(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 utilize 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.

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. Note that 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 extremely 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.

ALLOWREALLOCATE(YES)
ALLOWREALLOCATE(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. As one example, IMS batch (DLI batch) jobs are terminated with U3303 abends when a structure rebuild is initiated for certain IMS structures. To prevent the REALLOCATE process from targeting these IMS structures for relocation or policy change activation, the installation can activate an administrative policy with ALLOWREALLOCATE(NO) specified for these specific IMS structures.

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.

In addition, REALLOCATE processing is a triggering event for MVS-initiated duplexing rebuild when DUPLEX(ENABLED) is specified for the structure in the CFRM policy and the structure is not duplexed. Specifying ALLOWREALLOCATE(NO) does not prevent MVS-initiated duplexing rebuild, because by specifying DUPLEX(ENABLED) the installation is requesting MVS to attempt to maintain the duplexed status of the structure.

See the SETXCF START/STOP command in z/OS MVS System Commands for a description of the REALLOCATE process. See Using REALLOCATE or POPULATECF to relocate coupling facility structures 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:
  • Complete a pending policy update when the pending change does not affect the size or location
  • Trigger an MVS-initiated duplexing rebuild when DUPLEX(ENABLED) is specified for the structure and the structure is not duplexed

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.

ENCRYPT(YES)
ENCRYPT(NO)
Specifies whether list and cache structure entry data and entry adjunct data 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 Master Key to encrypt and decrypt structure data.

See Encrypting coupling facility structure data for information on system requirements that must be met prior to using the ENCRYPT parameter on a structure definition and allocating encrypted structures.

In addition to authorizing the use of the utility (see Authorizing use of the utility) for updating CFRM policies and CFRM couple data sets, you must ensure that users of the utility must have at least READ access to defined ICSF CSFSERV CSFKGN and CSFSERV CSFKYT resource profiles when ENCRYPT(YES) is specified on a structure definition.

Note that all systems in the sysplex must be at z/OS V2R3 or higher for this parameter to be fully effective. IBM recommends that before using the ENCRYPT parameter, 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 below) 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.

Note: For report and for the purpose of messages, the size unit that is specified on DUMPSPACE, SIZE, INITSIZE, and MINSIZE can be converted to the largest size unit that can be used to represent the size and avoids any rounding. For example, specifying INITSIZE(1048576K) might cause INITSIZE to be converted to INITSIZE(1G) in messages. Specifying INITSIZE(120000K) will not cause INITSIZE to be converted because it is not an even multiple of megabytes, gigabytes, or terabytes.

See Requesting structure size for more information about requesting the size for structures. See Allowing a structure to be altered automatically for more information about system-initiated alter processing.