Parameter Descriptions

The parameter descriptions are listed in alphabetical order. Default values are underlined:

,ANSAREA=ansarea

Use this output parameter to specify a storage area to contain member information returned from the request. Member information includes the group name, member name, member token, and any data you place in the user state field specified on USTATE. You will use the member token as input to other XCF macros.

The IXCYQUAA mapping macro, in the QUAMEM section, provides the format of the member information area. The member information area can be in the primary address space or be addressable through a public entry on the caller's dispatchable unit access list (DU-AL).

Use the ANSLEN parameter to specify the length of the area.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an area (with a length of ANSLEN) where the system will put the member information.

,ANSLEN=anslen

Use this input parameter to specify the size of the answer area specified by ANSAREA. The size of the area must be greater than or equal to the length of the data area for a single member record returned by IXCQUERY plus the length of the user state field. The field QUAMLEN in the IXCYQUAA mapping macro contains this value (the length of the member record plus the length of the user state field).

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4-byte field that contains the length of the member information area (ANSAREA).

,CANREPLY=NO

,CANREPLY=YES

Use this input parameter to specify whether the member can participate in the protocol for XCF-managed response collection for response-required signals.

NO: The member does not participate in XCF-managed response collection. A response-required message will be sent to the member even if it does not participate in the XCF-managed response collection protocol. XCF does not expect the member to recognize or respond to a message that requires an XCF-managed response. XCF response management does not wait for responses from this member.
YES: The member participates in XCF-managed response collection. The member can recognize and respond to a message that requires an XCF-managed response. The member detects when an XCF-managed response is required and sends the response with the IXCMSGO SENDTO=ORIGINATOR service.
The message exit parameter list, mapped by IXCYMEPL, the message notification exit parameter list, mapped by IXCYMNPL, or data, mapped by IXCYMQAA, returned by the Message Control Query Message service (IXCMSGC REQUEST=QUERYMSG) provide the information needed to allow the member to participate in this protocol.

,CRITICAL=NO

,CRITICAL=YES

Use this input parameter to indicate whether the member is a critical member. A critical member is one whose function is so critical to the normal operation of the group (and probably the system) that the member should be terminated if it appears to be impaired.

NO

The member does not designate itself as a critical member.

YES

The member designates itself as a critical member. XCF will monitor the health of the member. If the member becomes impaired for too long, XCF will terminate the member according to the TERMLEVEL specification.

To determine whether the member is impaired, XCF can use two techniques to monitor the health of a critical member:

XCF can use the status supplied by the member.
XCF can monitor the member's ability to process its XCF related work.

If the member requests status monitoring by coding the STATFLD, STATEXIT, and INTERVAL keywords, XCF will use both monitoring methods. If the member does not request status monitoring at join time, XCF will use the second method only.

,FUNCTION=NO_FUNCTION

,FUNCTION=function

Use this input parameter to describe the function, service, or application associated with the member. This description will appear in various XCF messages that provide information about the member.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 24-character input field that contains the description of the function, service, or application associated with the member. The string can contain any alphanumeric (A-Z), national (@,#,$), or special character (underscore or blank). Leading blanks and all blank descriptors are not permitted.

Note: The FUNCTION keyword is required if the IXCJOIN macro uses a parameter list of version 2 or higher. That is to say, it is required if any of the following keywords is used: CRITICAL, TERMLEVEL, and RECOVERYMGR.

,GRPEXIT=NO_GRPEXIT

,GRPEXIT=grpexit

Use this input parameter to specify the address of the optional group user-routine. This routine executes in the primary address space of the issuer of the IXCJOIN macro, in 31-bit addressing mode and in SRB mode. The routine receives control when there is a change in the operational state of other members in the group or systems in the sysplex.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4-byte field that contains the address of the group user-routine.

GRPNAME=grpname

Use this input parameter to specify the name you assign to the group that the member joins. The group name must be eight characters long, padded on the right with blanks if necessary; the valid characters are A-Z, 0-9, and national characters ($, # and @). To avoid using the names IBM® uses for its XCF groups, do not begin group names with the letters A through I or the character string SYS. Also, do not use the name UNDESIG, which is reserved for use by the system programmer in your installation.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an 8-byte field that contains the name of the XCF group.

,GT61KMSG=NO

,GT61KMSG=YES

Use this input parameter to specify whether the member supports sending or receiving messages greater than 61K bytes in length (62,464 bytes). If so, the member is allowed to use the XCF Message Services for messages up to 128M bytes in length (134,217,728 bytes).

Data returned by the IXCQUERY service indicates whether a member is permitted to send or receive messages greater than 61K bytes.

NO: Messages for this member are limited to a maximum length of 61K bytes. XCF will not allow the member to use the XCF Message-out Service (IXCMSGO) to send messages longer than 61K bytes. Messages sent to this member will be rejected by the XCF Message-out Service if they exceed 61K bytes.
YES: Messages for this member are limited to a maximum length of 128M bytes. XCF will not allow the member to use the XCF Message-out Service (IXCMSGO) to send messages longer than 128M bytes. Messages sent to this member will be rejected by the XCF Message-out Service if they exceed 128M bytes. The member is capable of using the XCF Message-in Service (IXCMSGI) to receive messages of up to a maximum of 128M bytes, although the application might impose a lower message length.
The message exit parameter list, mapped by IXCYMEPL, the message notification exit parameter list, mapped by IXCYMNPL, or data, mapped by IXCYMQAA, returned by the Message Control Query Message service (IXCMSGC REQUEST=QUERYMSG) provide the information needed to allow the member to participate in this protocol.

,INTERVAL=interval

Use this input parameter to specify the status-checking interval, in hundredths of seconds, that determines the length of time that can elapse with no change to the status field before scheduling the user status routine. Specify the interval in full seconds; that is, the value must be greater than zero and must be a multiple of 100. If you specify INTERVAL, you must also specify STATEXIT and STATFLD.

Note: The user status routine might not be called immediately after the interval expires based on timing of the status check as well as system environmental conditions.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4-byte field that contains the interval value in hundredths of seconds.

,LASTING=NO

,LASTING=YES

Use this input parameter to specify whether the member is to have permanent status recording. If you code LASTING=NO, XCF recognizes the member only while the member is active. If the sysplex is in XCF-local mode, you must use LASTING=NO.

If you code LASTING=YES, XCF recognizes the member even while the member is in the failed or quiesced state. If you are activating a member that already has permanent status recording in effect, use LASTING=YES.

MEMNAME is required with LASTING=YES.

,LOCALCLEANUP=NEEDED

,LOCALCLEANUP=CONTINUE

Use this input parameter to indicate whether the member needs time to perform cleanup processing when the system on which the member resides is being removed from the sysplex. XCF calls the member group user exit routine with the "system being removed from sysplex" event (GEPLTYPE=GESYSPRT) to notify the member that its system is being removed from the sysplex.

NEEDED: The member needs to perform cleanup when the system on which it resides is being removed from the sysplex. XCF will wait no longer than the installation-defined CLEANUP interval for the member to accomplish the cleanup before putting the system in a wait state. The member must inform XCF when the cleanup is completed by invoking either the IXCLEAVE or IXCQUIES macro. System termination will continue when the CLEANUP interval expires, or when all members that need to do cleanup have indicated that their cleanup is finished.
Note: The system defaults to LOCALCLEANUP=CONTINUE if a group exit is not provided. XCF may also proceed as if LOCALCLEANUP=CONTINUE is specified if the group exit routine fails when presented with the "system being removed from sysplex" event (GEPLTYPE=GESYSPRT).
CONTINUE: The member does not need time to perform additional cleanup after its group exit is presented with the "system being removed from the sysplex" event (GEPLTYPE=GESYSPRT). XCF may wait for other members to finish their cleanup, but it need not wait for this member to perform cleanup. With respect to this member, XCF can immediately continue with system termination.

,MEMASSOC=TASK

,MEMASSOC=JOBSTEP

,MEMASSOC=ADDRSPACE

Use this input parameter to specify a member's association with a task, job step task, or address space. XCF uses the MEMASSOC value to determine when to terminate a member (put the member in the failed or not-defined state). For more information on member termination, see z/OS MVS Programming: Sysplex Services Guide.

If you code MEMASSOC=TASK, the active member is associated with the task under which IXCJOIN was issued. XCF terminates the member when the associated task terminates.

If you code MEMASSOC=JOBSTEP, the active member is associated with the job step task under which IXCJOIN was issued. XCF terminates the member when the associated job terminates.

If you code MEMASSOC=ADDRSPACE, the active member is associated with the address space under which IXCJOIN was issued. XCF terminates the member when the associated address space terminates. Note that with this option, the system cannot provide SRB to task percolation.

Remember: An initiator address space does not end when a batch job running in it ends. So, if you are issuing IXCJOIN from a batch job and you want to terminate the member when the batch job ends, you must associate the member with the job, (MEMASSOC=JOBSTEP) not the initiator address space.

,MEMDATA=NO_MEMDATA

,MEMDATA=memdata

Use this input parameter to specify a 64-bit member data field. XCF provides this field to the group, status, message, and message notify user routines for this member. If you do not specify MEMDATA, or you specify MEMDATA=NO_MEMDATA, XCF sets the member data field to zeros.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an 8-byte field that contains member data.

,MEMNAME=NO_MEMNAME

,MEMNAME=memname

Use this input parameter to specify the name you choose for the member. If the member was previously in a created, failed, or quiesced state, you already have defined the member name. The name must be 16 characters long, padded on the right with blanks if necessary; the valid characters are A-Z, 0-9, and national characters (@, # and $).

If you use LASTING=YES, MEMNAME is required (MEMNAME=NO_MEMNAME is not acceptable). If you are defining one member per system, consider using the SYSNAME from CVTSNAME as the member name.

If you do not specify MEMNAME, or if you specify MEMNAME=NO_MEMNAME, XCF generates the member name in the form Mxxxxxxxxxxxxxxx.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 16-byte field that contains the XCF member name.

,MF=S

,MF=(L,mfctrl)

,MF=(L,mfctrl,mfattr)

,MF=(L,mfctrl,0D)

,MF=(E,mfctrl)

,MF=(E,mfctrl,COMPLETE)

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter can be coded with the list form of the macro.

Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

,mfctrl: Use this output parameter to specify a storage area to contain the parameters.
To Code: Specify the RS-type name or address (using a register from 2 to 12) of the parameter list.
,mfattr: Use this input parameter to specify the name of a 1- to 60-character string that can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code mfattr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE: Use this input parameter to require that the system check for required parameters and supply defaults for omitted optional parameters.
Note: In the macro expansion you might see some defaults for optional parameters that are not documented here. The ones that are not documented do not have any effect on the macro. For example, if SMILE=var were an optional parameter and the default is SMILE=NO_SMILE then it would not be documented. However, if the default was SMILE=:-), then it would be documented because a value would be the default.

,MSGEXIT=NO_MSGEXIT

,MSGEXIT=msgexit

Use this input parameter to specify the address of the message user routine. This routine executes in the primary address space of the issuer of the IXCJOIN macro, in 31-bit addressing mode and in SRB mode. The routine receives control when a message becomes available for this member from another member of the group.

See z/OS MVS Programming: Sysplex Services Guide for information about how to code a message user routine.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4-byte field that contains the address of the message exit routine.

,MSGOUTASID=MEMBER

,MSGOUTASID=ANY

Use this input parameter to indicate which address spaces can use the IXCMSGO macro to send messages to the members in the specified XCF group.

MEMBER: Indicates that when IXCMSGO is issued, the primary address space must equal the requesting member's primary address space at the time the group was joined, or the primary address space must be the MASTER address space.
ANY: Indicates that IXCMSGO can be issued from any address space.

,NOTIFYEXIT=NO_NOTIFYEXIT

,NOTIFYEXIT=notifyexit

Use this input parameter to specify the name of a user routine to receive control for message notifications. The routine must reside in the user's address space and run in 31-bit addressing mode. See z/OS MVS Programming: Sysplex Services Guide for the types of events that the system can present to the message notify user routine.

Specifying or defaulting to NO_NOTIFYEXIT indicates that the member does not want to receive unsolicited notification of events that have occurred. Lack of a message notify user routine at join time does not prevent the member from specifying the name of a routine to other services (such as IXCMSGO) that support it.

See z/OS MVS Programming: Sysplex Services Guide for information about how to code a message notify user routine.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a fullword field that contains the address of the message notify user routine.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=plistver

Use this input parameter to specify the version of the macro. See Understanding IXCJOIN Version Support for a description of the options available with PLISTVER.

,RECOVERYMGR=NO

,RECOVERYMGR=YES

Use this input parameter to indicates whether the member is a recovery manager. A recovery manager is a group member that coordinates a sysplex-wide recovery process.

NO: The member does not designate itself as a recovery manager.
YES: The member designates itself as a recovery manager.

,RETCODE=retcode

Use this output parameter to specify the location in which the system is to copy the return code from GPR 15.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4-byte field that will contain the return code when the join request is complete.

,RSNCODE=rsncode

Use this output parameter to specify the location in which the system is to copy the reason code from GPR 0.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4-byte field that will contain the reason code (if any) when the join request completes.

,STATEXIT=statexit

Use this input parameter to specify the address of the status user routine. This routine executes in the primary address space of the issuer of the IXCJOIN macro, in 31-bit addressing mode and in SRB mode. The routine receives control if the status field of the member is unchanged during the time period determined by the INTERVAL parameter. If you specify STATEXIT, you must also specify STATFLD and INTERVAL.

See z/OS MVS Programming: Sysplex Services Guide for information about how to code a status user routine.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4-byte field that contains the address of the status user-routine.

,STATFLD=NO_STATFLD

,STATFLD=statfld

Use this input parameter to specify a 64-bit status field in fixed or disabled reference (DREF) common storage, with any storage key. If the status field remains unchanged over the specified interval, XCF schedules the status user-routine identified in STATEXIT. If you specify STATFLD, you must also specify STATEXIT and INTERVAL.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an 8-byte field that contains the status of the member.

,SYSCLEANUPMEM=NO

,SYSCLEANUPMEM=YES

Use this input parameter to specify whether the member will perform system-wide cleanup after a system leaves the sysplex. If YES is specified, the system will wait for this member to issue the IXCSYSCL macro before any elements may be restarted by automatic restart management.

NO: Indicates the member joining the group will not perform system-wide cleanup of resources when a system leaves the sysplex.
YES: Indicates the member joining the group will perform system-wide cleanup when a system leaves the sysplex. When this member is notified that a system has left the sysplex, it must issue the IXCSYSCL macro to indicate to the system that cleanup is complete.

,TERMLEVEL=MEMASSOC

,TERMLEVEL=ADDRSPACE

,TERMLEVEL=SYSTEM

Use this input parameter to specify the first member-specific termination action the system is to take against this member when it needs to be terminated. For example, XCF may terminate a member that is determined to be causing signalling sympathy sickness, or a critical member that becomes impaired.

MEMASSOC

The system will use the MEMASSOC keyword specification to determine the task or address space with which the member is associated for termination purposes.

For MEMASSOC=TASK, the task from which the member invoked the IXCJOIN macro will be terminated.
For MEMASSOC=JOBSTEP, the job step task from which the member invoked the IXCJOIN macro will be terminated.
For MEMASSOC=ADDRSPACE, the address space from which the member invoked the IXCJOIN macro will be terminated.

ADDRSPACE

The system will terminate the address space from which the member invoked the IXCJOIN macro.

SYSTEM

The system will terminate the system on which the member resides. The system will enter wait state and be removed from the sysplex.

Note:

The termination will cause any other members associated with the relevant task, space, or system to be terminated too.
The setting on TERMLEVEL is honored whenever XCF needs to terminate the member, for example, when IXCTERM is used to terminate a target member.

,USLEN=uslen

Use this input parameter to specify the length in bytes of the user state data that you provide on the USTATE parameter. The length must be from 1 to 32 bytes. If you specify less than 32 bytes, XCF pads the remainder of the user state field, up to 32 bytes, on the right with zeros. IXCQUERY always returns the full 32 bytes, and group user-routines always receive the full 32 bytes. If you code USTATE, USLEN is required.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of a 4-byte field that contains the length of the user state data (USTATE).

,USTATE=NO_USTATE

,USTATE=ustate

Use this input parameter to specify the user state data that XCF is to place in the member's user state field. If you do not specify the USTATE parameter, XCF retains the existing value in the user state field unless the joining member was previously not-defined. In this case, XCF clears the user state field to zeros. Specify the length of the user state data on the USLEN parameter.

To Code: Specify the RS-type name or address (using a register from 2 to 12) of an area (with a length of USLEN) that contains the user state information.