XPCC (Cross-Partition Communication) Macro

The macro invokes the cross-partition communication service, which allows communication between two application programs (two different z/VSE tasks).

For the values and meanings of the return and reason code information that is related to the various XPCC requests, see the MAPXPCCB (Map Cross-Partition Control Block) Macro.

Format

Requirements for the caller

AMODE:: 24 or 31
RMODE:: 24 or ANY
ASC Mode:: Primary

Parameters

XPCCB=addr | (1) | (S,addr)

Defines the address of the XPCCB, which is the control block that contains all request-related information. The control block is set up with the XPCCB macro. Depending on the request, only certain fields of the control block are used. For details, refer to the description of the various functions in the Using z/VSE Macro Support.

The address of the XPCCB is treated as a 3-byte address if the issuer of the macro is operating in 24-bit mode, and as a 4-byte address, if operating in 31-bit mode.

FUNC=keyword | (reg)

Defines the specific function to be requested from the XPCC service. Depending on the type of request, an application can use the following keywords:

Initialization request:
IDENT Identify an application to the XPCC service.
Connection-related requests:
CONNECT Connect an application to another application. DISCONN Terminate a connected link to another application (if no data transmission is going on at the moment).

DISCPRG Terminate a connection unconditionally. This might interrupt the transfer of data.

DISCALL Disconnect unconditionally all connections for a certain application.
Data transmission requests:
SEND Send data to another application.

SENDR Send data and request a reply from the receiver.

SENDI Send data into a predefined area and give SENDI state to partner.

RECEIVE Receive data.

REPLY Send a reply to the sender.

CLEAR Revoke a previously initiated SEND request from the connection (used by the sender).

PURGE The receiver purges the data, because he is not able to receive it.
Termination requests:
TERMIN Terminate XPCC usage (if all links are already disconnected).

TERMPRG Terminate unconditionally. This might interrupt the transfer of data.

TERMQSCE No termination yet, but new connections to this application are not granted anymore.

Depending on the selected function, IJBXFCT of the cross-partition control block (XPCCB) is set accordingly.

If the format FUNC=(reg) is used, the specified register must have been loaded with the corresponding function byte value. These values can be found in the program listing under label IJBXFCT in the mapping macro MAPXPCCB (see Table 3).

BUFFER=addr | (reg) | (S,addr)

This optional operand can be used with SEND, SENDR, SENDI, RECEIVE, and REPLY requests to dynamically provide a data area from where (SEND, SENDR, SENDI, REPLY) or to which (RECEIVE) data is to be moved. If you use this operand, the corresponding BUFFER field in the XPCCB control block is overwritten.

If the address is loaded into a register, it must be a 4-byte address.

For a RECEIVE or REPLY request, the BUFFER address must point to an 8-byte area with the following format:

Bytes: Description
0, bit 0: ON
0 - 3: Data area address (31bit address)
4 - 7: Length of data area.

For a SEND or SENDR request, the BUFFER address must point to an address list as shown below, where each entry has the following format:

Bytes

Description

0, bit 0

Indicator bit:

OFF: Not last entry in list
ON: Last entry in list

0 - 3

Data area of buffer segment (31bit address))

4 - 7

Length of buffer segment

You can specify up to 256 entries of this format in one buffer address list. The buffer segments are concatenated and passed as one buffer.

Note: For performance reasons, it is recommended that buffers should start at a page boundary or, if smaller than a page, do not cross the page boundary.

FDSCR=POSTRCV | UNIQUE | ABNORM | NO | (reg)

This operand specifies an option for the requested function. If omitted, the current value of the function descriptor field IJBXFDSC of the XPCCB is used (see also Table 4).

POSTRCV Can be specified with the SENDR function. The sender is notified when the data is received by the other side. IJBXCECB is posted and the reason code field IJBXREAS is set to IJBXRECX. If register notation is used, the register must be loaded with IJBXPOST.

UNIQUE Can be specified with the IDENT function. It ensures that the application name specified in the XPCCB macro is unique in this z/VSE system. If the application name is already known in the system, the request is rejected with return code X'08' in register 15 and return code field IJBXRETC set to IJBXDUP. If the IDENT request is granted, each subsequent request with the same application name is rejected with the same return information. If register notation is used, the register must be loaded with IJBXUNIQ.

ABNORM Can be specified with the DISCONN and DISCPRG functions. The other side is posted an abnormal-end condition of the current task, with reason code field IJBXREAS set to IJBXABDC. If register notation is used, the register must be loaded with IJBXFDAB.

NO Can be specified with any function. It forces the function descriptor code to X'00'.

If register notation is used, the register must be loaded with binary zeros.

MECB=addr | (reg) | (S,addr)

This operand can optionally be used with the CONNECT function. It specifies the address of an ECB within the user 's partition. This 'main ECB' is always posted, if any of the XPCC ECBs is posted. All tasks waiting on the MECB are set to 'ready-to-run'. The application owning the main ECB is responsible for resetting the traffic bit in the main ECB.

If the address is loaded into a register, it must be a 4-byte address.

MXPCCB=addr | (reg) | (S,addr)

This operand can optionally be used with the CONNECT function. It defines the XPCCB, which contains the identify token to be used as input in the CONNECT request.

If the address is loaded into a register, it must be a 4-byte address.

TIMEOUT=n | (reg)

Specifies the number of seconds the issuer of a CONNECT request is prepared to wait. The value for n must be in the range of 0 to 255. After the specified time interval is exhausted, IJBXCECB, IJBXSECB, and IJBXRECB are posted and reason code IJBXTOUT is set in IJBXREAS. The XPCC user must respond with either an XPCC FUNC=DISCONN or DISCPRG request.

In register notation, byte 3 of the register contains the value n. 0 means an immediate request. In this case the CONNECT request is rejected with IJBXTIMO, if the partner has not already issued CONNECT.

If the TIMEOUT operand is specified, the XPCCB must be defined with VERSION=2.