Parameter Descriptions

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

,AMDALEVEL=0

,AMDALEVEL=amdalevel

Use this input parameter to specify the level of the IXCYAMDA record mappings that the system returns in the answer area. Valid values are 0, 1 and 2.

A value of 0 indicates that base level IXCYAMDA records will be returned.
A value of 1 indicates that level-1 IXCYAMDA records will be returned.
A value of 2 indicates that level-2 IXCYAMDA records will be returned.

DATAAREA=dataarea

Use this output area to identify the area in which IXCMG is to return the data you request.

The data area must be in fixed or disabled reference (DREF) storage. It must be in the primary address space or in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).

To Code: Specify the name of a fullword field (or register 2-12 containing the address of the field) that identifies the data area.

,DATALEN=datalen

Use this input parameter to specify the length of the area you provided on the DATAAREA parameter. The length should be long enough to accommodate the IXCYAMDA mapping of the data area.

To Code: Specify the name of a fullword field (or register 2-12 containing the address of the field) that contains the length of the data area.

,ECBPTR=NONE

,ECBPTR=ecbptr

Use this input parameter to specify the address of an ECB to be posted either when the results become available or when the request is discarded. If ECBPTR is not specified or ECBPTR=NONE is specified, no ECB is posted.

This is an optional parameter and ECBPTR=NONE is the default.

To Code: Specify the RS-type name or address (using a register from 2-12) of the 4 byte field containing the ECB address.

,GATHERFROM=LOCAL

,GATHERFROM=OTHER

,GATHERFROM=TOKEN

Use this input parameter to specify from which system you want to gather the information.

GATHERFROM=LOCAL, the default, is used to request the gathering of data from the local system. Note that the contents of the DATAAREA is different depending on whether GATHERFROM=LOCAL is explicitly coded or is processed by default. If not explicitly coded, the DATAAREA will contain the header AMDAREA followed by the requested data records. If GATHERFROM=LOCAL is explicitly coded, the header information is mapped by AMDAGFD and there will be two new records (AMDGLI) provided.
GATHERFROM=OTHER is used to request the gathering of data from some other system in the sysplex. The requester provides the XCF system ID of the system from which the data is to be gathered and a timeout value indicating how long they are willing to wait for the results. An optional ECB can be provided if the requester wants XCF to post the user when the results arrive (or when the request times out). If not posted, the requester is expected to poll for the results. If accepted, the output DATAAREA contains a request token (AMDAGFO_REQTOKEN) that is used to obtain the results of the asynchronous data gathering. Use this token as input to a subsequent IXCMG GATHERFROM=TOKEN request to retrieve the results. If the user does not gather the results before the timeout, or if the target system is removed from the sysplex, XCF discards the request and its results.
GATHERFROM=TOKEN is used to obtain the result of a previous IXCMG GATHERFROM=OTHER request. The DATAAREA must be large enough for the AMDAGFD header. The requester provides the appropriate REQTOKEN to identify which results are to be obtained. The expected answer is one of the following:
- The results were copied into the indicated DATAAREA.
- The indicated DATAAREA is too small to hold all of the results. Try again with a bigger DATAAREA.
- Expected results have not yet arrived. Try again later.
- No such request exists anymore
The TYPE, MEMTOKEN, GROUP, and AMDALEVEL parameters should not be coded when issuing a GATHERFROM=TOKEN request to retrieve the results.

This is an optional parameter and GATHERFROM=LOCAL is the default.

,GROUP=NO

,GROUP=YES

Use this input parameter to specify whether information is to be returned only for the indicated member (GROUP=NO) or for all active members of the member's group (GROUP=YES) on the system where the data is gathered. GROUP is only used when the MEMTOKEN value is nonzero.

This is an optional parameter and GROUP=NO is the default.

,MEMTOKEN=0

,MEMTOKEN=memtoken

Use this input parameter to specify the MEMTOKEN of the member whose MEMBER data is to be gather. MEMTOKEN is only used when gathering MEMBER data. It is ignored for all other data options. If the indicated member does not reside on the local system, no MEMBER data will be returned.

To Code: Specify the name of a 64-bit field (or register 2-12 containing the address of the field) that contains the MEMTOKEN of the member.

,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.

,REQTOKEN=reqtoken

Use this input parameter to specify the request token that identifies the request whose results are to be collected.

To Code: Specify the RS-type name or address (using a register from 2-12) of the 16 character field that contains the request token.

,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 name of a fullword field (or register 2-12 containing the address of the field) to contain the return code.

,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 name of a fullword field (or register 2-12 containing the address of the field) to contain the reason code.

,SYSID=sysid

Use this input parameter to specify the XCF system ID of the system from which the data is to be gathered.

To Code: Specify the RS-type name or address (using a register from 2-12) of the fullword field containing the target system ID.

,TIMEOUT=timeout

Use this input parameter to specify the maximum number of seconds that the system allows the request to persist. The specified value must be between 1 and 120, inclusive.

To Code: Specify the RS-type name or address (using a register from 2-12) of the halfword field containing the timeout value.

,TYPE=ALL

,TYPE=PATH

,TYPE=MSGPEND

,TYPE=SYSTEM

,TYPE=SRCDST

,TYPE=MEMBER

Use this input parameter to specify which types of data records XCF is to return. TYPE=ALL returns all types of data records. If you do not specify the TYPE parameter, you receive all types of data records. You may specify more than one type of data record with this parameter. For example, you could code: TYPE=(PATH,MSGPEND).

The data that IXCMG generates consists of a header, followed by zero or more data records. The types of data records are as follows:

TYPE=PATH returns one record for each signalling path that XCF is using. The AMDPATH structure in IXCYAMDA maps this record. It includes such information as, for each outbound signalling path, the number of times XCF tried to send a signal across the path.
TYPE=MSGPEND returns one record for each pending message. The AMDMPEND structure maps this record. It includes such information as, for each outbound signal queued for data transfer, the member token, ASID, and length of the message.
TYPE=SYSTEM returns records that describe the message traffic associated with the system on which you issue IXCMG. The AMDSYS structure maps this record. It includes such information as the total number of times the system refused message requests in each transport class because buffer space was not available.
TYPE=SRCDST returns one record for each active member in the sysplex. The AMDSD structure maps this record. It includes such information as the number of messages the member has sent.
TYPE=MEMBER returns one record for each member that resides on the local system. The AMDMEM structure maps this information. The MEMTOKEN keyword can be specified to limit the data to a specific member.