SETXCF START command

Use the SETXCF START command to:

Start new inbound signalling paths or restart inoperative inbound signalling paths
Start outbound signalling paths or restart inoperative outbound signalling paths
Define transport classes
Start using a new administrative policy as an active policy
Start rebuilding one or more coupling facility structures either in the same coupling facility or in another coupling facility
Start populating a coupling facility that has been newly brought into service or returned to service in a sysplex with structures selected from the set of those defined in the active CFRM policy. The structures selected are those that list the coupling facility to be populated as higher in the structure's preference list than the coupling facility in which the structure already is allocated
Start duplexing of one or more structures in a coupling facility.
Start altering the size of a coupling facility structure
Start the REALLOCATE process. The REALLOCATE process uses the XCF structure allocation algorithm and the structure definition in the active or pending CFRM policy to evaluate each allocated structure. When this evaluation indicates that adjustments can be made for an allocated structure, then REALLOCATE processing makes the appropriate adjustments.
Transition from a policy-based event and confirmation management protocol to a message-based event and confirmation management protocol.
Place a specific coupling facility or a list of coupling facilities into maintenance mode. When a coupling facility is in maintenance mode, the XCF structure allocation algorithm prevents the allocation of a coupling facility structure in the coupling facility.

An inoperative signalling path remains defined to XCF but is not in use. DISPLAY XCF lists inoperative as well as active signalling paths. When you restart an inoperative signalling path with SETXCF START, you can alter MAXMSG, RETRY, and CLASS. These values take effect when XCF restarts the signalling path.

The complete syntax for the SETXCF START command is:

 
SETXCF START,{CLASSDEF,CLASS=classname                          }
                         [,CLASSLEN=classlength]                
                              [,MAXMSG=maxmsgbuffers]           
                         [,GROUP=(groupname[,groupname]...)]    
             {MSGBASED}
             {PATHIN,{DEVICE=([/]indevnum[,[/]indevnum]...)}    }
                     {STRNAME=(strname[,strname]...)       }    
                         [,MAXMSG=maxmsgbuffers]                
                              [,RETRY=retrylimit]               
                                                               
             {PATHOUT,{DEVICE=([/]outdevnum[,[/]outdevnum]...)} }
                      {STRNAME=(strname[,strname]...)         } 
                         [,MAXMSG=maxmsgbuffers]                
                              [,RETRY=retrylimit]               
                         [,CLASS=classname]                     
                                                               
             {POLICY,TYPE=name,POLNAME=polname                  }
                                                              
             {REBUILD,{POPULATECF=cfname}                       }
                      {DUPLEX,}                                 
                      {STRNAME=(strname[,strname]...)}          
                      {CFNAME=(cfname[,cfname]...)   }          
                         [,LOCATION={NORMAL|OTHER}]             
                         [,LESSCONN={TERMINATE|CONTINUE}]       
                                                               
             {ALTER,STRNAME=strname,SIZE=size[u]                }
             {REALLOCATE                                        }
             {MAINTMODE,CFNAME=(cfname[,cfname]...)             }

CLASSDEF or CD,CLASS=classname

Specifies a definition for a new transport class. You must specify the classname as one to eight alphanumeric and national ($,#,@) characters, and may begin with any of these characters. The DEFAULT transport class always exists. If you specify only one class, you do not need to enter the parentheses.

CLASSLEN=classlength: Specifies the message length for this transport class, where classlength must be a number between 0 and 62464. If you omit this keyword, the system uses the current CLASSLEN value (specified either on the SETXCF COUPLE command or in the COUPLExx parmlib member).
MAXMSG=maxmsgbuffers: Specifies the default amount of message buffer space allotted for messages sent in this transport class, where MAXMSG value must be a number between 2 and 999999. See z/OS MVS Setting Up a Sysplex for further information about determining message buffer space.
If you omit this keyword, the system uses the MAXMSG value specified on either the SETXCF COUPLE command or in the COUPLE statement in the COUPLExx parmlib member).
GROUP or GRP =(groupname[,groupname]..): Assigns one or more groups to the transport class. The order in which groups are specified is unimportant; all groups have equal access to the signalling services. If you omit this keyword, XCF assigns all groups not currently assigned (the UNDESIG groups), to the classname specified on the CLASSDEF parameter.
You must specify the group name groupname as one to eight alphanumeric and national ($,#,@) characters, and may begin with any of these characters.

MSGBASED

Switch to a message-based event and confirmation management protocol from a policy-based event and confirmation protocol. The sysplex must be running with a version of the CFRM couple data set that supports message-based event and confirmation processing in order for this command to execute successfully. The system chooses the system where the SETXCF START,MSGBASED command was issued as the new event managing system.

PATHIN or PI,DEVICE or DEV=([/]indevnum[,[/]indevnum]...)

Specifies the device number of one or more inbound signalling paths that XCF can use. A device number, indevnum, is 3 or 4 hexadecimal digits, optionally preceded by a slash (/). If you specify only one device, you do not need to enter the parentheses.

The specified device must be unallocated. The system at the other end of a signalling path must be inactive or part of the sysplex, and the other end of the path must be defined to XCF as an outbound path.

Once the command completes, the other systems in the sysplex can begin to send signalling traffic on the path to this system. For a signalling path device that is not online, MVS™ can vary the device online when you use this command to start the signalling path. The device remains defined to XCF until the definition is deleted through the SETXCF STOP command.

PATHIN or PI,STRNAME or STRNM=(strname[,strname]...)

Specifies the name of one or more coupling facility structures that XCF can use as inbound signalling paths. The designated structure is defined as a signalling path only to this system and not to every system in the sysplex. Other systems that are connected to the structure must also define the structure for use as a signalling path.

The structure name strname can be up to 16 alphanumeric characters long and must begin with ‘IXC’. The remaining characters can be numeric, uppercase alphabetic, national characters ($, @, #), or an underscore (_). If you specify only one structure name, you do not need to enter the parentheses.

MAXMSG=maxmsgbuffers: Specifies the maximum amount of message buffer space, in kilobytes, that XCF can use to receive messages through the inbound signalling path. If you omit this keyword, the system uses the current MAXMSG value (specified on either the SETXCF COUPLE command or the COUPLE statement of the COUPLExx parmlib member). The MAXMSG value must be a number from 1 to 999999.
RETRY=retrylimit: Specifies the retrylimit for the inbound signalling paths. If you omit this keyword, the system uses the RETRY value, a number between 3 and 255 specified on either the SETXCF COUPLE command or the COUPLE statement of the COUPLExx parmlib member.

PATHOUT or PO,DEVICE or DEV=([/]outdevnum[,[/]outdevnum]..

Specifies the device number of one or more outbound signalling paths that XCF can use. A device number, outdevnum, is 3 or 4 hexadecimal digits, optionally preceded by a slash (/). If you specify only one device, you do not need to enter the parentheses.

The specified device must be unallocated. The system at the other end of the path must be inactive or part of the sysplex, and the other end of the path must be defined to XCF as an inbound path. Once the command completes successfully, the other system in the sysplex can begin to receive signalling traffic on the path from this system. For a signalling path device that is not online, MVS can vary the device online when you use this command to start the signalling path. The device remains defined to XCF until the definition is deleted through the SETXCF STOP command.

PATHOUT or PO,STRNAME or STRNM=(strname[,strname]...)

Specifies the name of one or more coupling facility structures XCF can use as outbound signalling paths. The designated structure is defined only to this system, not to every system in the sysplex. Other systems connected to the structure must also define the structure for use as a signalling path.

MAXMSG=maxmsgbuffers: Specifies the amount of message buffer space contributed by this signalling path. If you omit this keyword, the system uses the current MAXMSG value for the transport class that this path is assigned. The MAXMSG value must be a number between 1 and 999999.
RETRY=retrylimit: Specifies the retrylimit for the outbound signalling path. If you omit this keyword, the system uses the current RETRY value, a number between 3 and 255 specified on either the SETXCF COUPLE command or the COUPLE statement of the COUPLExx parmlib member.
CLASS=classname: Specifies the name of the transport class to which the outbound signalling paths are assigned. If you omit this keyword, the system uses the DEFAULT transport class. The classname must be previously defined. You must specify the classname as one to eight alphanumeric and national ($,#,@) characters, and may begin with any of these characters.

POLICY or POL,TYPE=name,POLNAME or POLNM=polname

Specifies that the administrative policy named is to be made active in the sysplex or that the active policy is to be changed. The system from which the SETXCF command is issued must have access to the couple data set supporting the service.

See z/OS MVS Setting Up a Sysplex for information about transitioning to a new administrative policy.

TYPE=name

Specifies the name of the service that is using the couple data set for policy data. The supported services are:

ARM for automatic restart management
CFRM for coupling facility resource management
SFM for sysplex failure management

POLNAME or POLNM=polname

Specifies the name of the administrative policy to be made active.

Note: When TYPE=ARM is specified, POLNAME is optional. If no policy name is specified, the policy defaults will be used.

REBUILD or RB,POPULATECF or POPCF=cfname

Specifies the name of the coupling facility that is to be populated with structures selected from the set of allocated structures in the active CFRM policy.

A structure rebuild will be attempted for each allocated structure in the policy that contains the specified coupling facility in its preference list, if the specified coupling facility is at a higher position in the preference list than the coupling facility in which the structure currently is allocated. If the structure is allocated in a more preferable coupling facility already, the rebuild will not continue.

POPULATECF rebuild processing assumes LOCATION=OTHER. LOCATION and LESSCONN options cannot be specified.

Each structure that contains the specified coupling facility at a higher position in its preference list will be processed serially to completion (either stopped or completed) before the next structure is selected. The serial nature of this processing allows even XCF signalling structures to be selected for coupling facility population.

The coupling facility name can be up to 8 alphanumeric characters long and must begin with an uppercase alphabetic character. The name can contain numeric characters, uppercase alphabetic characters, national characters ($, @, #), or an underscore (_).

REBUILD or RB,DUPLEX,STRNAME or STRNM=(strname[,strname]…)

Specifies the name of one or more coupling facility structures that are to be duplexed in another coupling facility.

If structure duplexing is not supported for the target structure, the duplexing operation will not be started and the system issues a message to the operator.

Duplexing rebuild processing assumes LOCATION=OTHER and LESSCONN=TERMINATE. Other LOCATION and LESSCONN options cannot be specified.

The structure name can be up to 16 characters long and can contain numeric characters, uppercase alphabetic characters, national characters ($, @, #), or an underscore (_). The name must begin with an uppercase alphabetic characters. IBM® names begin with SYS, or letters A-I.

If you specify only one structure name, you do not need to enter the parentheses.

REBUILD or RB,DUPLEX,CFNAME=(cfname[,cfname]…)

Specifies the name of one or more coupling facilities for which all structures are to be duplexed in a different coupling facility.

The system attempts to start a duplexing operation for each structure that is currently allocated in the specified coupling facility.

If structure duplexing is not supported for a particular structure, the system issues a message to the operator.

The coupling facility name can be up to 8 alphanumeric characters long and can contain numeric characters, uppercase alphabetic characters, national characters ($, @, #), or an underscore (_). It must begin with an uppercase alphabetic character.

If you specify only one coupling facility name, you do not need to enter the parentheses.

REBUILD or RB,STRNAME or STRNM=(strname[,strname]...)

Specifies the name of one or more coupling facility structures that are to be rebuilt in the same coupling facility or another coupling facility. The structure name can be up to 16 alphanumeric characters long and must begin with an uppercase alphabetic character. IBM names begin with SYS, or letters A-I. If you specify only one structure name, you do not need to enter the parentheses.

REBUILD or RB,CFNAME or CFNM=(cfname[,cfname]...)

Specifies the name of one or more coupling facilities for which all structures other than XCF signalling structures are to be rebuilt. The coupling facility name can be up to 8 alphanumeric characters long and must begin with an uppercase alphabetic character. If you specify only one coupling facility name, you do not need to enter the parentheses.

For any given structure, the system might not start rebuild. z/OS MVS Programming: Sysplex Services Guide lists the requirements for rebuild initiation. For example, if the named coupling facility contains one or more XCF signalling structures, the system does not start rebuild for them. To rebuild an XCF-signalling structure, issue the SETXCF START,REBUILD,STRNAME=... command for one structure at a time.

LOCATION=NORMAL or OTHER

Specifies the location where the new structure or structures can be rebuilt. If you specify LOCATION=NORMAL, the new structure can be allocated in any coupling facility in the preference list, following the normal allocation rules. If you specify LOCATION=OTHER, the new structure cannot be allocated for rebuild in the same coupling facility as the original structure. The new structure can be allocated in any other coupling facility in the preference list, following the normal allocation rules.

Duplexing rebuild and POPULATECF processing assume LOCATION=OTHER.

Note that before the rebuild process begins, you might need to change the administrative policy to specify where the structure can reside and then activate the policy. The CFRM administrative policy contains the preference list that specifies coupling facilities where a structure can reside.

LESSCONN or LC=TERMINATE or CONTINUE

Specifies the action the system is to take when rebuilding the structure results in a new structure that has poorer connectivity relative to the set of active structure connectors than the old structure does.

With LESSCONN=TERMINATE, the system stops the rebuild processing for the new structure if connectivity relative to the set of active connectors to the structure is not equal or better than it was to the current structure.
LESSCONN=TERMINATE is the default system action. This protects active connectors against inadvertently losing connectivity to the structure as a result of rebuilding the structure.

Duplexing rebuild processing assumes LESSCONN=TERMINATE.
With LESSCONN=CONTINUE, the system allows the rebuild processing for the new structure even if connectivity relative to the set of active connectors to the structure is poorer than it was to the current structure.
Attention: Because this might cause active connectors to lose connectivity to the structure, do not use this keyword unless you understand the impact to the application or subsystem.
Some connectors stop the rebuild if a loss of connectivity is observed, but most connectors disconnect from the structure to allow the rebuild to complete. For many exploiters, disconnecting from the structure is likely to result in losing the sysplex-related functionality (for example, loss of data sharing capability) on that system. For critical system exploiters, this may result in a system wait state. See the application or subsystem documentation for recommendations.

ALTER,STRNAME or STRNM=strname,SIZE=size [u]

Specifies that structure alter processing is to be initiated.

STRNAME or STRNM=strname: Specifies the name of the coupling facility structure to be altered. You can specify only one structure name. The name can be up to 16 alphanumeric characters long and must begin with an uppercase alphabetic character. The name can contain numeric characters, uppercase alphabetic characters, national characters ($,@,#) or an underscore(_). IBM names begin with SYS, or letters A-I.
SIZE=size [u]: Specifies the target size of the structure to be altered in an integer unit of u, where u is specified as K (kilobytes), M (megabytes), G (gigabytes), or T (terabytes). If a size unit value is not specified, the default is K (kilobytes). Size is bounded by the minimum and maximum sizes determined when the structure was allocated. The minimum size of a structure is determined by the coupling facility; the maximum size of a structure is established by the installation in the CFRM policy. (Use the DISPLAY XCF,STRUCTURE,STRNAME=strname command to determine the maximum structure size allowed.)
Note: For report and for the purpose of messages, the size unit specified may be converted to the largest size unit that can be used to represent the size and avoids any rounding. For example, specifying SIZE=1048576K may cause SIZE to be converted to SIZE=1G for the purpose of messages. Specifying SIZE=120000K will not cause SIZE to be converted because it is not an even multiple of megabytes, gigabytes, or terabytes.

REALLOCATE or REALLOC

Specifies that the REALLOCATE process is to be initiated.

The REALLOCATE process evaluates each allocated structure to recognize the need to make the following adjustments:

Relocate the structure instance or instances
Complete a pending policy change
Trigger MVS-initiated duplexing

The evaluation of each allocated structure uses the XCF structure allocation algorithm and either the active or pending CFRM policy definition for the structure. Message IXC574I is written to the hardcopy log to show the current location of instances allocated in coupling facilities, the policy information used, and the evaluation result. Then it compares the current location with the location identified by evaluation to determine what if any adjustments are needed.

By evaluating the 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. In addition, REALLOCATE processing is a triggering event for MVS-initiated duplexing rebuild when it finds the structure is not duplexed and DUPLEX(ENABLED) is specified for the structure in the CFRM policy.

The REALLOCATE process recognizes the need to relocate structure instances when one of the following conditions is detected:

There is a change to the policy definition for the structure affecting the structure size or location.
The structure is not optimally located.

To control the relocation of a specific structure by the REALLOCATE process, you can specify the ALLOWREALLOCATE(YES|NO) keyword for the structure in the CFRM policy.

If you specify or default to ALLOWREALLOCATE(YES) for the structure in the CFRM policy:
When the REALLOCATE process recognizes the need to relocate structure instances (see the preceding description of such conditions), the structure is selected as the target of the REALLOCATE process and the structure rebuild process is used to make the adjustments. Structure rebuild process supports the following:
- User-managed rebuild
- User-managed duplexing rebuild
- System-managed rebuild
- System-managed duplexing rebuild
Multiple steps may need to be taken to complete the relocation of a selected structure. The steps are accomplished using structure rebuild processing (for example, user-managed rebuild) to adjust the location or activate a pending policy change for the structure that is the target of the REALLOCATE process. Messages to the operator document the steps being taken for each structure that is examined.
- For a simplex structure, one step (rebuild) is used to adjust the location or to activate a pending policy change.
- For a duplexed structure, two or three steps are used. The first step stops duplexing and one or more subsequent steps are used as needed to adjust the location, activate a pending policy change, and to reduplex the structure. If a subsequent step cannot be started, the system issues message IXC546I with an explanation.
- A duplexed structure can also be converted to simplex structure when one of the duplexed structure instances is allocated in a coupling facility that does not permit structure allocation (for example, maintenance mode) and it is not possible to reduplex the structure. In this case, one or two steps are used. The first step stops duplexing and a second step might be needed to relocate the simplex structure or activate a pending policy change.
If you specify ALLOWREALLOCATE(NO) for the structure in the CFRM policy:
The REALLOCATE process evaluates the allocated structure but does not select the structure as the target of the REALLOCATE process. However, when NO is specified it is still possible for the REALLOCATE process to do the following adjustments if 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.

When the REALLOCATE process does not select an allocated structure, message IXC544I is issued with an explanation.

When the start request is accepted, the DISPLAY XCF,STR or the DISPLAY XCF,CF command shows THE REALLOCATE PROCESS IS IN PROGRESS. For a summary of allocated structure status, use the DISPLAY XCF,STR,STATUS=ALLOCATED command:

The structure that is the current target indicates TARGET OF REALLOCATE PROCESS.
Allocated structures which have not been evaluated indicate REALLOCATE EVALUATION PENDING.
Structures which have been processed do not have additional status indicators displayed but the log can be examined to determine the action taken.

When the entire process completes for all structures, the processing provides a report (message IXC545I) summarizing the actions that were taken as a whole. The REALLOCATE process evaluates all allocated structures, in a serial (one structure at a time) fashion. Each selected structure is processed to completion before the next structure is evaluated. The serial nature of this processing allows even XCF signalling structures to be selected for relocation.

REALLOCATE processing evaluates a structure based on the CFRM policy and on the current conditions (for example, available coupling facilities, coupling facility attributes, and connection attributes), and for each structure selected for processing, takes the necessary steps to adjust the location of the structure's allocated instances. From the time a structure is evaluated to the time when the steps using structure rebuild processing cause a new instance to be allocated, it is possible for the conditions to have changed. The result is that the current conditions are used when the structure allocation algorithm is applied. The REALLOCATE process does not validate the resulting location of the allocated instances but relies on the result of applying the XCF allocation criteria. Because of this, it is possible that the coupling facilities shown as preferred when message IXC574I was written to the hardcopy log with the evaluation information are not the coupling facilities containing the allocated instances when the necessary steps finish. Where REALLOCATE processing intersects with other environmental changes (for example, starting or stopping a structure rebuild process due to a policy change, a coupling facility failure, or loss of connectivity to a coupling facility), the other ongoing process will take precedence with REALLOCATE processing issuing messages IXC544I or IXC546I as appropriate. For some environmental changes (for example, a coupling facility failure), the installation may choose to stop the REALLOCATE process.

Consider the following when you use the SETXCF START,REALLOCATE command:

Move structures out of a coupling facility following a CFRM policy change that deletes/changes that coupling facility (for example, in preparation for a coupling facility upgrade).
Move structures back into a coupling facility following a CFRM policy change that adds/restores the coupling facility (for example, following a coupling facility upgrade/add).
Clean up pending CFRM policy changes that may have accumulated for whatever reason, even in the absence of any need for structure "relocation" per se.
Clean up simplex or duplexed structures that were allocated in or moved into the "wrong" coupling facilities, for whatever reason (for example, the "right" coupling facility was inaccessible at the time of allocation).
Clean up duplexed structures that have primary and secondary "reversed" because of a prior condition which resulted in having duplexing stopped with KEEP=NEW and the structure reduplexed.

Note:

The REALLOCATE process is mutually exclusive with the POPULATECF function, which can be started either by the SETXCF operator command or the IXLREBLD programming interface.
The REALLOCATE process can only be started or stopped using the SETXCF command.
Support for the REALLOCATE process is provided by APAR OA03481.
- The REALLOCATE process cannot be started if there exists an active system in the sysplex that does NOT have the APAR installed. The SETXCF START,REALLOCATE command is rejected.
- An in-progress REALLOCATE process is stopped immediately when an active system without the APAR installed is discovered in the sysplex. The SETXCF START,REALLOCATE command was accepted but subsequently an active system without the APAR installed was discovered by an up-level system which immediately stopped the process.
In both cases, message IXC543I is issued with explanatory text.
Enhancements for the REALLOCATE process are provided by APAR OA08688.
- A structure-level control is provided to prevent REALLOCATE processing from selecting particular structures while allowing it to initiate structure rebuilds for others. This control is achieved by providing an option on the CFRM STRUCTURE parameter to the XCF Administrative Policy Utility (IXCMIAPU). The option is ALLOWREALLOCATE. See z/OS MVS Setting Up a Sysplex, under topic Coding the Administrative Data Utility for topic CFRM Parameters for Administrative Data Utility.
- For a simplex structure with DUPLEX(ENABLED) specified, the REALLOCATE process is a triggering event. Message IXC536I is issued when MVS is able to initiate a duplexing rebuild for the structure identified by REALLOCATE processing.
- When a pending policy change does not affect size, REALLOCATE processing avoids structure rebuild processing when evaluation with the pending policy shows that the structure does NOT need relocating. It completes the pending change. Message IXC544I is issued indicating ALLOCATED IN PREFERRED CF AND POLICY CHANGE MADE.
- With this enhancement, REALLOCATE processing will ignore a specified exclusion list in some cases, so as to avoid anomalies when honoring the exclusion list would have precluded structures from relocating to the optimal location.

MAINTMODE,CFNAME=(cfname,[cfname...])

Sets the specified coupling facility or facilities into maintenance mode. When in maintenance mode, a CF is not eligible for CF structure allocation purposes. The XCF structure allocation algorithm modifies the CF selection processing accordingly. You can use the SETXCF STOP command to turn off MAINTMODE. This setting is kept in control blocks in the storage of the ACTIVE sysplex. It is not saved across sysplex wide IPLs, so a sysplex wide IPL will clear the setting.