Parameter Descriptions
- ,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.
- ,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.
- ,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 transitions the member to a "non-active" state when the associated task terminates. This means that if the member joins with LASTING=NO, the member becomes "not defined." If the member joins with LASTING=YES, XCF puts the member in a "failed" state.
If you code MEMASSOC=JOBSTEP, the active member is associated with the job step task under which IXCJOIN was issued. XCF transitions the member to a "non-active" state 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 transitions the member to a "non-active" state 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 Mnnnnnnnnnnnnnnn, where nnnnnnnnnnnnnnn is a number.
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=(M,mfctrl)
- ,MF=(M,mfctrl,COMPLETE)
- ,MF=(M,mfctrl,NOCHECK)
- ,MF=(E,mfctrl)
- ,MF=(E,mfctrl,COMPLETE)
- ,MF=(E,mfctrl,NOCHECK)
- 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=M to specify the modify form of the macro. Use the modify form to generate code to put the parameters into the parameter list.
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 (by using a register 2 - 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 assembly language Data Studio 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
- ,NOCHECK
- Use this input parameter to specify the degree of macro parameter syntax checking the system is
to do.
- 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.
- NOCHECK
- Use this parameter to specify that the system is not to check for required parameters nor to supply defaults for omitted optional parameters.
- ,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.
- ,MSGISO=NONE
- ,MSGISO=MSGORSN
- Use this input parameter to indicate the degree to which the member is to be made aware of
message isolation. A member is
message isolated
when XCF determines that the member is consuming so much signalling resource that it impedes the ability of XCF to deliver signals to other members. Messages sent with the XCF Message-Out Service (macros IXCMSGO or IXCMSGOX) to a member that ismessage isolated
will either be delayed or rejected.- NONE
- indicates that the member is not prepared to deal with unique reason codes related to message isolation. The delay or reject of an XCF Message-Out request targeted to a member that is message isolated will be attributed to a "no buffer" condition (ixcMsgoRsnNoBuffer).
- MSGORSN
- indicates that the member is capable of dealing with unique reason codes related to message
isolation. The delay or rejection of an XCF Message-out request targeted to a member that is message
isolated will be attributed to
message isolation
.The reason code (ixcMsgoRsnTargetIsolated) could be reported by any XCF interface that reports the result of a Message-out request. For example, it can be returned by either IXCMSGO or IXCMSGOX. It can be reported to the notify exit by the MNPL (macro IXCYMNPL) or to the invoker of IXCMSGC when querying the state of a message (by macro IXCYMQAA).
MSGISO=NONE is the default. If both NONE and MSGORSN are specified, MSGORSN takes precedence and NONE is ignored.
- ,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.