The parameters are explained as follows:

,#DATADESC=#datadesc

,#DATADESC=1

Use this optional input parameter to indicate the number of data descriptors in the data descriptor table. This parameter is valid when RECEIVE=RESPONSES and DATADESC=datadesc are specified. The default is 1.

To code: Specify the RS-type name or address in register (2)-(12), of a fullword field, or specify a literal decimal value that contains the number of data descriptors in the table.

,ANSAREA=ansarea

When RECEIVE=RESPONSES is specified, use this required input variable to specify an answer area where XCF is to store the metadata that describes the message and its responses. ANSAREA contains a header (ixcysrvr_tAnsArea), a send descriptor (ixcysrvr_tSendDescriptor), a target descriptor (ixcysrvr_tTargetDescriptor) for each target, and a response descriptor (ixcysrvr_tResponseDescriptor) for each response if EXPECTREPLY=YES was specified in the originating IXCSEND invocation. The mappings are defined in the IXCYSRVR macro.

In general, ANSAREA must be large enough to hold the header and all the descriptors. If not, none of the descriptors will be stored. The service routine returns with a return and reason code indicating that the ANSAREA needs to be bigger (ixcrecvRsnMoreAnsArea). The header indicates how much storage is needed (aa_AnsAreaSize). The caller needs to obtain a sufficiently large answer area and reissue the request before the IXCSEND hold time (HOLDTIME) timeout value (See IXCSEND — Send Client/Server Requests and Responses.)

The answer area must reside in the primary address space of the caller, or in a space addressable through a public entry on the dispatchable unit access list (DU-AL), or in a common area data space.

To code: Specify the RS-type name or address in register (2)-(12), of a character field that contains the answer area.

,ANSLEN=anslen

When RECEIVE=RESPONSES is specified, use this required input variable to specify the length in bytes of the answer area provided by the invoker.

To code: Specify the RS-type name or address in register (2)-(12), of a fullword field, or specify a literal decimal value to specify the length of the answer area.

,BIND=TARGET

,BIND=NEXT

Use this optional parameter to indicate how XCF is to associate entries in the data descriptor table to responses. This paramter is valid whenDATADESC=datadesc and RECEIVE=RESPONSES are specified. The default is BIND=TARGET.

,BIND=TARGET

Entries in the data descriptor table are in one to one correspondence with the targets of the message. The number of entries in the data descriptor table must be greater than or equal to the number of message targets. Entry "i" in the table describes where the response from target "i" is to be stored. For example, if a request was sent to four targets, and only targets 1 and 3 replied with response data. With BIND=TARGET, the response data from target 1 will be stored in the storage area described by data descriptor table entry 1, and the response data from target 3 will be stored in the storage area described by entry 3. The storage areas described by entries 2 and 4 will not be used.

,BIND=NEXT

Entries in the data descriptor table are to be used successively for the next response to be delivered. For example, if a request was sent to four targets, and only targets 1 and 3 replied with response data. With BIND=NEXT, the response data from target 1 will be stored in the storage area described by data descriptor table entry 1, and the response data from target 3 will be stored in the storage area described by entry 2. The storage areas described by entries 3 and 4 will not be used.

,DATALEN=datalen

When DATAAREA=dataarea and RECEIVE=RESPONSES are specified, use this required input parameter to contain the length in bytes of the data area provided by the invoker.

To code: Specify the RS-type name or address in register (2)-(12), of a fullword field, or specify a literal decimal value to specify the length of the data area.

,LENDDENTRY=lenddentry

,LENDDENTRY=16

Use this optional input parameter to indicate the length in bytes of each entry in the data descriptor table. This paramter is valid whenDATADESC=datadesc and RECEIVE=RESPONSES are specified. As XCF iterates through the table, it locates the next descriptor by adding LENDDENTRY to the location of the current descriptor. LENDDENTRY must be greater than or equal to the length of one data descriptor, which is 16. If not specified, LENDDENTRY defaults to the length of one data descriptor. The default is 16.

To code: Specify the RS-type name or address in register (2)-(12), of a fullword field, or specify a literal decimal value to specify the length pf each entry in the descriptor table.

,MF=S

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,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. MF=S is the default.

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 might 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 of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

,list addr

The name of a storage area to contain the parameters. For MF=S and MF=E, this can be an RS-type address or an address in register (1)-(12).

,attr

An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.

,COMPLETE

Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.

,MSGSTGKEY=msgstgkey

,MSGSTGKEY=USERKEY

Use this optional input parameter to contain the storage key to be used when storing the response data into the indicated data areas (either DATAAREA or the areas described by DATADESC). This paramter is valid whenRECEIVE=RESPONSES is specified. The high order nibble contains the storage key, the low order nibble is ignored. For example, set 'kkkk' in the binary bit string B'kkkkxxxx' to correspond to the desired storage key.

If MSGSTGKEY is not specified, the response data is stored using the PSW key in effect at the time the XCF receive service was called. The default is USERKEY.

To code: Specify the RS-type name or address in register (2)-(12), of an 8 bit field that contains the storage key.

MSGTOKEN=msgtoken

Use this required input parameter to contain the message token that identifies the message to be processed. The IXCSEND macro returned this token through the RETMSGTOKEN keyword when the message was sent.

If the indicated message no longer exists, the service routine sets a return and reason code to so indicate (ixcrecvRsnMsgNotFound) and returns to the caller.

To code: Specify the RS-type name or address in register (2)-(12), of a 32-character field that contains the message token.

,NODATA

,DATAAREA=dataarea

,DATADESC=datadesc

Use this required input parameter to specify how to handle the response data. This paramter is valid when RECEIVE=RESPONSES is specified.

,NODATA

One of set of mutually exclusive keywords indicating that no response data is to be stored.

To code: Specify the RS-type name or address in register (2)-(12), of a field.

,DATAAREA=dataarea

One of set of mutually exclusive keywords indicating where XCF is to store the response data provided by the responder. The content, interpretation, and mapping of the response data is determined by the responder.

If multiple responses are being received, XCF concatenates the response data for each response successively in the indicated DATAAREA. The response descriptor in the ANSAREA can be used to locate the corresponding response data within DATAAREA.

Depending on the size of the response data and the number of responders, the amount of storage needed for DATAAREA could be significant. In such cases DATADESC might be more appropriate, as it might be easier to get one storage area per response rather than one storage area large enough to hold all the responses.

If DATAAREA is not large enough, none of the response data will be stored and the service routine returns with a return and reason code indicating that the DATAAREA needs to be bigger (ixcrecvRsnMoreDataArea). The header in the ANSAREA indicates how much storage is needed (aa_DataAreaSize). The caller needs to obtain a sufficiently large data area and reissue the request before the HOLDTIME timeout value for the message expires. (See IXCSEND — Send Client/Server Requests and Responses.)

The data area must reside in the primary address space of the caller, or in a space addressable through a public entry on the dispatchable unit access list (DU-AL), or in a common area data space. The storage key of the data area must match the storage protect key indicated by the MSGSTGKEY keyword.

To code: Specify the RS-type name or address in register (2)-(12), of a character field that contains the data area.

,DATADESC=datadesc

One of set of mutually exclusive keywords containing a table of one or more data descriptors. A data descriptor identifies a storage location where the response data for one response is to be stored. Data descriptors are mapped by ixcysrvr_tDataDescriptor that is defined in the IXCYSRVR macro. A data descriptor specifies the length, ALET, and address of a contiguous virtual storage area where the response data for one response is to be stored. The content, interpretation, and mapping of the response data stored in the storage area indicated by a data descriptor is determined by the responder.

The data descriptor table is an array of entries. Each entry has the same fixed size, and can contain data other than the data descriptor. The storage location named by DATADESC contains the first such data descriptor. Subsequent descriptors are iteratively located by adding the value LENDDENTRY to the location of the current descriptor.

The storage area defined by the data descriptor must reside in the primary address space of the caller, or in a space addressable through a public entry on the dispatchable unit access list (DU-AL), or in a common area data space. The storage key of the data area must match the storage protect key indicated by the MSGSTGKEY keyword.

There must be a data descriptor for each response to be received. If not, the service routine returns with a return and reason code indicating that more descriptors are needed (ixcrecvRsnMoreDataDesc). Each such data descriptor must describe storage that is large enough to hold all the response data for the relevant response. If not, the service routine returns with a return and reason code indicating that more storage is required (ixcrecvRsnMoreDataArea). In the ANSAREA, the dd_DataSize field within the data descriptor (md_DataDesc) for the response message descriptor (rd_MsgDesc) that is returned for each requested response indicates how much storage is needed for the associated response data. The caller needs to obtain a sufficient number of descriptors that describe large data areas and reissue the request before the IXCSEND hold time (HOLDTIME) timeout value for the message expires.

In all cases, if the data area for any one response is too small to hold the relevant response data, or if the data descriptor table does not contain enough entries for all responses, none of the responses will be stored.

If response data is stored, the response descriptor in the ANSAREA can be used to locate the corresponding message data.

The storage area containing the data descriptor table must reside in the primary address space of the caller, or in a space addressable through a public entry on the dispatchable unit access list (DU-AL), or in a common area data space.

To code: Specify the RS-type name or address in register (2)-(12), of a character field that contains the data descriptors.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=0

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

,RECEIVE=STATUS

,RECEIVE=RESPONSES

Use this required parameter to indicate the kind of data the service routine is to gather.

,RECEIVE=STATUS

The service routine is to report the status of the request. The return code and reason code indicates whether the request is completed (RETCODE=0), or whether the request is still pending (RETCODE=4). If pending, the RSNCODE indicates whether there are responses available for delivery (ixcrecvRsnAvailable or ixcrecvRsnPending).

RECEIVE=STATUS is specified if the caller wants to obtain the status of the message but does not actually want to receive the responses or information about the responses. RECEIVE=STATUS can be used, for example, to poll for message completion.

,RECEIVE=RESPONSES

RECEIVE=RESPONSES is specified if the caller wants to receive the results associated with the indicated message.

An earlier IXCSEND SENDTO=SERVER request was used to send a message to one or more targets. If EXPECTREPLY=YES is specified, each target is expected to invoke IXCSEND SENDTO=ORIGINATOR to send its response in reply to the message. Each reply can contain "response data" (corresponding to the IXCSEND keywords MSGDATA or MSGDESC), or "response info" (keywords RESPRETCODE, RESPRSNCODE, SUPPLIEDLEVEL, SUPPORTSLEVEL), or both. The caller now wants to receive the results.

The keyword DATAAREA or the keyword DATADESC is used to indicate where the "response data" is to be stored. The metadata describing the status of the results is stored in the storage area identified by the ANSAREA keyword.

,REQTYPE=BLOCKING

Use this required parameter to indicate that the caller wants the service routine to wait for the results to arrive before returning. This paramter is valid whenRECEIVE=RESPONSES is specified.

,REQTYPE=BLOCKING

If the requested results are not yet available, the IXCRECV service routine blocks (suspends) the caller. Control does not return to the caller until the requested results become available. To release a blocked receiver before all results become available, some other work unit can invoke the XCF message control service (IXCMSGC) to discard the message (REQUEST=DISCARDMSG), complete the message (REQUEST=COMPLETION), or release the blocked receiver (REQUEST=RELEASEMSG).

,RETCODE=retcode

An optional output parameter into which the return code is to be copied from GPR 15. If you specify 15, GPR15, REG15, or R15 (within or without parentheses), the value will be left in GPR 15.

To code: Specify the RS-type name of a fullword field, or register (2)-(12) or (15), (GPR15), (REG15), or (R15).

,RSNCODE=rsncode

An optional output parameter into which the reason code is to be copied from GPR 0. If you specify 0, 00, GPR0, GPR00, REG0, REG00, or R0 (within or without parentheses), the value will be left in GPR 0.

To code: Specify the RS-type name of a fullword field, or register (0) or (2)-(12), (00), (GPR0), (GPR00), REG0), (REG00), or (R0).

,SCOPE=ALL

Use this required parameter to indicate that all results are to be gathered. This paramter is valid whenRECEIVE=RESPONSES is specified.

,SCOPE=ALL

All results are to be gathered. This allows the caller to process all the results at one time.

The metadata of the results are to be stored in the answer area. If a data area (DATAAREA or DATADESC) is provided, the response data for each available response is to be stored in the data area.