Defining Members to XCF

Defining members to an XCF group is a process that requires planning. For each member, you have the following choices:

Define the member to XCF and immediately make the member active (issue the IXCJOIN macro).
Define the member to XCF in the created state with the intent to subsequently make the member active (issue the IXCCREAT macro, and later on, issue the IXCJOIN macro).
Define the member to XCF in the created state without intending to make the member active (issue the IXCCREAT macro).
Define the member with permanent status recording.
Define the member with a value in the user state field.
Define the member with one or more of the following optional user routines on IXCJOIN:
- Message user routine
- Status user routine
- Group user routine.
- Message notify user routine
Define the member's association with a task, job step task, or address space.
Define the member, specifying that the system should wait for the member to clean up resources before the system performs an automatic restart.
Define the member, specifying that it is capable of participating in XCF's response collection protocols.

Once you define a member, XCF maintains information about the member, along with a timestamp. XCF updates the timestamp on every change to the member's state or the member's user state value.

Member Attributes provides the information you need to choose attributes for defining each member to XCF. This topic provides the information you need to use the IXCCREAT and IXCJOIN macros to define members with the desired attributes.

Obtaining Permanent Status Recording
When you issue the IXCCREAT macro to define a member to XCF, the member automatically has permanent status recording. If, instead, you use the IXCJOIN macro to define a member to XCF, you can choose permanent status recording by coding the LASTING=YES parameter.

If you plan to define members to XCF with permanent status recording, you should inform the system programmer in your installation, because the systems on which your multisystem application will run cannot be in XCF-local mode. Permanent status recording requires a sysplex couple data set, which is not supported in XCF-local mode. See z/OS MVS Setting Up a Sysplex for further information.

Members requesting permanent status recording should check the return codes from either IXCCREAT or IXCJOIN. Both of these macros provide return codes indicating that the system is in XCF-local mode.

A member cannot discontinue permanent status recording once it is in effect. If a member with permanent status recording is in a created, quiesced, or failed state and then issues IXCJOIN to become active, the member must specify LASTING=YES on the IXCJOIN macro.
Initializing a User State Field
You can initialize the 32-byte user state field on the IXCCREAT macro or the IXCJOIN macro (USTATE and USLEN parameters). The USLEN parameter indicates the number of bytes of user state data you provided on the USTATE parameter. If you specify a USLEN of fewer than 32 bytes, XCF pads on the right with zeros, thus initializing the remainder of the user state field to zeros.

If you specify the user state field on the IXCCREAT macro, you do not have to specify it again when you issue IXCJOIN, unless you want to change the value.

You can also define a member to a group without specifying a value for the user state field on IXCJOIN, and subsequently set the user state field by coding the USTATE and USLEN parameters on IXCLEAVE, IXCQUIES, or IXCSETUS.

See Changing the Value in a User State Field for further information.
Identifying One or More User Routines
Identify user routines on the IXCJOIN macro as follows:
- Message user routine: code the MSGEXIT parameter.
- Status user routine: code the STATEXIT, STATFLD, and INTERVAL parameters (you must code all three).
- Group user routine: code the GRPEXIT parameter.
- Message notify user routine: code the NOTIFYEXIT parameter.
When you code one or more user routines, you might want to use the member data field (MEMDATA parameter on IXCJOIN). This is an 8-byte field that can contain whatever information you want to provide to the user routines. XCF includes this information as part of the parameter list that it passes to the message, status, message notify, and group user routines. You might use the member data field to pass the address and ASID or ALET of a particular control structure that the user routine needs to do its work.
Associating the Member
To specify the unit of work with which the member is to be associated, code the MEMASSOC parameter on the IXCJOIN macro. See Member Association for more information about member association.
Specifying Resource Cleanup for Automatic Restart
To specify that the system should wait for the member to clean up resources before automatic resource management restarts batch jobs and started tasks on another system, code the SYSCLEANUPMEM parameter on the IXCJOIN macro. When the group user routine gets control for a system that was removed from the sysplex, the routine must issue the IXCSYSCL macro to indicate that system cleanup has completed.
Participating in Message Response Collection Protocols
To specify that a member is to participate in XCF-managed response collection, code the CANREPLY parameter on the IXCJOIN macro. See Specifying Message Response Collection for more information about XCF-managed response collection.
Summary: Using the IXCCREAT and IXCJOIN Macros
Both the IXCCREAT and IXCJOIN macros allow you to:
- Define a new group name to XCF and define a new member to that group (XCF supports a maximum of 2045 groups and a maximum of 511 members per group, provided the system programmer in your installation defines sufficient capacity in the sysplex.)
- Define a new member to an existing XCF group (XCF insures that the member name is unique within the group).
- Initialize a user state field (USTATE and USLEN parameters).

Table 1 specifies how the IXCCREAT and IXCJOIN macros differ. Table 2 summarizes the parameters you code on each macro to obtain the desired member attributes.

Table 1. Differences between IXCCREAT and IXCJOIN Macros
Area of Difference	IXCCREAT	IXCJOIN
Member state	Defines a member to XCF and places that member in the created state. The created member cannot use XCF signaling and status monitoring services.	Defines a member to XCF and places that member in the active state. Only members in the active state can use XCF signaling and status monitoring services. Issue IXCJOIN to change an existing member from the created, quiesced, or failed state to the active state.
Permanent status recording	Defines a member with permanent status recording.	Defines a member with permanent status recording only if you code LASTING=YES. You can code LASTING=NO if the member does not already have permanent status recording in effect.
Member name	Requires that you provide a member name (MEMNAME parameter).	Requires that you provide a member name (MEMNAME parameter) when you code LASTING=YES. If you code LASTING=NO, you can code MEMNAME, or let XCF generate a unique name for the member.
Member token	Returns a unique (within the sysplex) member token that you can use to code the TARGET parameter on IXCSETUS or IXCDELET. However, when the member becomes active through IXCJOIN, XCF returns a new unique member token, and the old token is no longer valid.	Returns a unique (within the sysplex) member token that you use on subsequent calls to XCF. (If a created, quiesced, or failed member issues IXCJOIN, XCF returns a new unique member token, and the old token is no longer valid.)
User routines	Does not allow you to identify user routines.	Allows you to identify a message, status, group, and message notify user routine.
Member association	Does not allow you to associate a member with any particular task, job step task, address space, or system.	Allows you to associate the member with a task, job step task, or address space on a particular system.
Member cleanup	Does not allow you to specify that the system should wait for the member to clean up resources before the system performs an automatic restart.	Allows you to specify that the system should wait for the member to clean up resources before the system performs an automatic restart.

Table 2. Summary of Options on IXCCREAT and IXCJOIN Macros
Option	Macro	Parameter
Permanent status recording	IXCJOIN	LASTING=YES
Permanent status recording	IXCCREAT	Automatic
User state value	IXCCREAT or IXCJOIN	USTATE and USLEN
Message user routine	IXCJOIN	MSGEXIT
Status user routine	IXCJOIN	STATEXIT, STATFLD, and INTERVAL
Group user routine	IXCJOIN	GRPEXIT
Message notify user routine	IXCJOIN	NOTIFYEXIT
Member association	IXCJOIN	MEMASSOC
Member cleanup	IXCJOIN	SYSCLEANUPMEM
Message response collection	IXCJOIN	CANREPLY=YES