The User State Field

Every member of an XCF group, regardless of member state, has a user state field associated with it. Each member decides whether it wants to place values in that field. The field is 32 bytes long; a member can use all or part of this field. If a member chooses not to use this field, XCF sets the field to zeros.

While XCF recognizes five member states (not-defined, created, active, quiesced, and failed), the user state field allows you to specify additional, application-defined, internal states that XCF does not use or recognize.

User state information is available to members and other authorized routines in the following ways:

XCF includes the user state field as part of the parameter list it passes to the group user routines of active members.
XCF includes the user state field as part of the data it returns to the caller of the IXCJOIN, IXCCREAT, and IXCQUERY macros.

The following are examples of ways you can use the user state field:

Use the user state field as shared virtual storage. For example, you can use the user state field to keep track of an increasing sequence number across multiple systems. Each member that wants the next sequence number can increment a counter in the user state field.
Use the user state field to determine which member of the group might perform a particular function. For example, each member places a value in its user state field, and one member examines all the values and chooses the member with the highest value to perform the function.
Use the user state field to record steps in a process. As each step is completed, update the user state field with a corresponding value. In the event of abnormal termination, other members can determine exactly which steps in the process completed and thereby determine at which point to continue processing.
Use the user state field to indicate for a failed member that a restart is in progress. For example, when member 1 fails because the system it is running on fails, member 1A can become active in its place. Member 1A can change its user state field to indicate that a restart is in progress. Other members can do recovery for member 1. When recovery is complete, member 1A can change its user state field to indicate it is fully operational.

Members with permanent status recording can reap the most benefit from the user state field. Even if the member ends abnormally, XCF still has a record of the member's existence, and other members can determine what action to take based on the contents of the user state field. Without permanent status recording, if the member ends abnormally, it is no longer defined to XCF, and the contents of the user state field are no longer available to other members.

Details on initializing and changing a user state field are in the topics entitled Defining Members to XCF and Changing the Value in a User State Field. Refer to Skipping of Events for user state design considerations related to skipped events.