Coding the couple data set format utility

See the following figures for examples of how to set up your JCL to format different types of couple data sets:

For a sysplex couple data set, see Formatting a sysplex couple data set
For an ARM couple data set, see Formatting an automatic restart management couple data set
For a CFRM couple data set, see Formatting a CFRM couple data set
For a LOGR couple data set, see Formatting a LOGR couple data set
For an SFM couple data set, see Formatting an SFM couple data set
For a z/OS® UNIX couple data set, see Formatting a UNIX System Services couple data set
For a WLM couple data set, see Formatting a WLM couple data set.

The utility control statements are described below:

PGM=IXCL1DSU

The format utility program that is shipped with z/OS.

STEPLIB

Identifies the SYS1.MIGLIB library.

SYSPRINT

Describes where the output messages from the format utility are to be written. The SYSPRINT DD statement is required.

SYSIN

Describes the utility control statements used to format one or more couple data sets.

DEFINEDS

Specifies the beginning of the definition of a new couple data set. There is no limit to the number of DEFINEDS statements that you provide, and therefore to the number of couple data sets that you format. The couple data set to be created should not have previously existed and must not be found by the format utility either on the specified volume or in the catalog. This prevents the format program from being run against a couple data set that is in use.

Specific Couple Data Set Information: The information for the type of couple data set being formatted is identified with parameters of the DEFINEDS statement. For a description of the keywords to format a couple data set type, see the respective topic:

The physical attributes of the couple data set are controlled with the following parameters of DEFINEDS.

SYSPLEX(sysplex-name)

Specifies the 1 - 8 character name of the sysplex in which the couple data set is to be used. The valid characters are alphanumeric characters (A-Z and 0-9) and national characters ($,@,#). The first character of the name must be alphabetic. The sysplex name is a required parameter.

MAXGROUP(total-group) THIS STATEMENT CAN BE USED ONLY ON A DEFINEDS STATEMENT WHEN FORMATTING A SYSPLEX COUPLE DATA SET. IT IS MAINTAINED FOR COMPATIBILITY WITH MVS/ESA SP VERSION 4 STATEMENTS.

IBM recommends use of DATA TYPE(SYSPLEX) with ITEM NAME(GROUP) instead of the MAXGROUP keyword. Specifies the number of groups to be supported by the new sysplex couple data set. If this parameter is omitted, a default of 10 is used. The maximum allowable value for this parameter is release dependent. In z/OS, the maximum supported is 2045. The minimum value of MAXGROUP allowed is 10.

Note that if DATA TYPE(SYSPLEX) is specified, the maximum number of groups allowed is expected to be specified using ITEM NAME(GROUP).

If MAXGROUP and DATA TYPE(SYSPLEX) are both specified:

If ITEM NAME(GROUP) is specified, message IXC291I will be issued stating that the MAXGROUP value was overridden by the ITEM NAME(GROUP) value.
If ITEM NAME(GROUP) is omitted, message IXC291I will be issued stating that MAXGROUP is incompatible with DATA TYPE(SYSPLEX) and the data set will not be formatted.

MAXMEMBER(members-per-group) THIS STATEMENT CAN BE USED ONLY ON A DEFINEDS STATEMENT WHEN FORMATTING A SYSPLEX COUPLE DATA SET. IT IS MAINTAINED FOR COMPATIBILITY WITH MVS/ESA SP VERSION 4 STATEMENTS.

IBM recommends use of DATA TYPE(SYSPLEX) with ITEM NAME(MEMBER) instead of the MAXMEMBER keyword. Specifies the maximum number of members in any one XCF GROUP. If this parameter is omitted, a default value is taken. The default number of members in a group is calculated to be the number of members which can be accommodated on one track on the device type on which the sysplex couple data set resides. The maximum allowable value for this parameter is release dependent. In z/OS, the maximum supported is 1023. The minimum value of MAXMEMBER allowed is 8. Systems joining the sysplex obtain the MAXMEMBER value from the sysplex couple data set. The actual number defined by the format utility might be larger than the number specified. This is due to the fact that XCF adds one member for its own use and rounds the number of members to the next larger multiple of four.

Note that if DATA TYPE(SYSPLEX) is specified, the maximum number of members allowed is expected to be specified using ITEM NAME(MEMBER).

If MAXMEMBER and DATA TYPE(SYSPLEX) are both specified:

If ITEM NAME(MEMBER) is specified, message IXC291I will be issued stating that the MAXMEMBER value was overridden by the ITEM NAME(MEMBER) value.
If ITEM NAME(MEMBER) is omitted, message IXC291I will be issued stating that MAXMEMBER is incompatible with DATA TYPE(SYSPLEX) and the data set will not be formatted.

MAXSYSTEM(maximum-systems)

Specifies the number of systems to be supported by the new couple data set. If this parameter is omitted, the format utility assigns a default value of eight. In z/OS, the maximum value is 32.

When formatting the couple data set to contain the CFRM policy data, ensure that the value you specify for MAXSYSTEM matches the value for MAXSYSTEM that was used when the sysplex couple data set was formatted.

When coupling facility structures are used for XCF signaling and the MAXSYSTEM value specified for the CFRM couple data set is less than that of the sysplex couple data set, systems might not be able to join the sysplex. For example, if the only signaling connectivity is through coupling facility structures, MAXSYSTEM=16 is specified for the sysplex couple data set, and MAXSYSTEM=8 is specified for the CFRM couple data set, then at most eight systems will be allowed in the sysplex. (The limit might be less than eight as described in Implications of the MAXSYSTEM value for the sysplex couple data set.)

Note:

If MAXSYSTEM is greater than eight, and RMAX (the maximum length of WTOR reply IDs, as specified in the CONSOLxx parmlib member) is less than 99, then the system will increase RMAX to 99 when you start using this data set. This is to handle the potential increase in WTOR traffic in a sysplex of greater than eight systems. Once RMAX is increased, it cannot be decreased. The system issues message IEA403I to indicate that the maximum number of reply IDs becomes 99.
When a sysplex is configured with a MAXSYSTEM value greater than 8, reply IDs are no longer assigned in strict sequential order. Instead, systems obtain groups of reply IDs for assignment to WTORs, and the IDs might not be assigned in sequential order. This change requires no coding changes on the installation's part, but might surprise an operator. You should consider informing operators of this change.

DSN(data-set-name)

Specifies the 1 - 44 character length name to be used for the couple data set. The format utility will allocate a new data set by this name on the volume specified by the VOLSER parameter. The valid characters are alphanumeric characters (A-Z and 0-9), national characters ($,@,#), a period (.), and a hyphen (-). The first character must be either an alphabetic or a national character. DSN is a required parameter.

VOLSER(volser)

Specifies the 1 - 6 character length name of the volume on which the couple data set is to be allocated. The valid characters are alphanumeric characters (A-Z and 0-9) and national characters ($,@,#). VOLSER is a required parameter for non-SMS managed data sets. For SMS-managed data sets and VOLSER restrictions, see the STORCLAS and MGMTCLAS parameters.

UNIT(type)

Specifies the type of the unit to which the couple data set is to be allocated. You can specify an installation-defined group name, generic device type, or specific device number. The UNIT parameter is optional. If you specify UNIT, then you must also specify VOLSER.

NOCATALOG

CATALOG

Specifies whether the data set is to be cataloged. The default is not to catalog the data set if neither CATALOG nor NOCATALOG is specified. If the data set is SMS-managed, NOCATALOG is ignored.

STORCLAS(storage-class)

Specifies the SMS storage class for the SMS-managed volume where the data set is to reside. storage-class can be any valid SMS storage class name. STORCLAS is an optional parameter.

Either STORCLAS or VOLSER must be defined on the DEFINEDS statement. If STORCLAS is specified, you do not need to specify VOLSER. It is recommended that you specify the GUARANTEED SPACE=YES attribute for the storage class. You can use ISMF panels to specify names of storage classes with the guaranteed space attribute.

If your installation has assigned storage classes and management classes through automatic class selection (ACS) routines, the routines might affect where SMS places the couple data set. The format utility issues a message to indicate the volume that SMS has selected for the data set.

MGMTCLAS(management-class)

Specifies the SMS management class for the SMS-managed volume where the data set is to reside. management-class can be any valid SMS management class name. MGMTCLAS is an optional parameter.

DATA TYPE

Indicates the type of data to be supported by the couple data set. Use one DATA TYPE control statement to identify each function to be supported by the couple data set.

DATA TYPE(SYSPLEX)

DATA TYPE(ARM)

DATA TYPE(CFRM)

DATA TYPE(LOGR)

DATA TYPE(SFM)

DATA TYPE (WLM)

DATA TYPE(BPXMCDS)

Identifies the type of data to be supported by the couple data set. Note that SYSPLEX data cannot be combined with other data types in the same couple data set.

ITEM NAME(data-name) NUMBER(data-number): Specifies the number of occurrences of the data specified on the DATA TYPE statement that are to be supported on the couple data set.