Using the JES XCF exits

As noted previously, there are a number of restrictions placed on the use of the JES XCF macros and their use in specific exits or JES3 DSPs. Remember, only two of the JES XCF macros (IXZXIXAT and IXZXIXDT) can be used in a JES XCF exit (IXZXIT03). All other JES XCF macros are for your use in standard JES exits and JES2 DSPs only.

To illustrate an attach, send, receive, detach scenario, refer to Figure 1, which presents the overall flow between two JES members of the same JES XCF group. The example presented here shows the steps both JES members MCR and POK take to communicate. The figure shows the macros invoked, the exits used, and the basic flow for an entire asynchronous acknowledgement message cycle. Following Figure 1 is sample code for each step.

Figure 1. Example of using JES XCF macros and exits for an ASYNCACK message cycle

The following numbered steps describe the events in Figure 1.

1 MCR builds mailbox mcr mailbox (using the IXZXIXMB macro in a standard JES exit or JES3 DSP)
2 POK builds mailbox pok mailbox (using the IXZXIXMB macro in a standard JES exit or JES3 DSP)
3 MCR sends a message to member POK (using the IXZXIXSM macro in a standard JES exit or JES3 DSP)
4 Exit IXZXIT01 is invoked to modify the ASYNCACK message before delivery to the POK mailbox
5 POK receives the message from MCR (using the IXZXIXRM macro in a standard JES exit or JES3 DSP)
6 Exit IXZXIT02 is invoked to modify the ASYNCACK message before POK receives the message
7 POK acknowledges the message from MCR (using the IXZXIXAC macro in a standard JES exit or JES3 DSP)
8 Exit IXZXIT01 is invoked to modify the acknowledgement to member MCR before delivery to the MCR mailbox
9 MCR receives the acknowledgement from POK (using the IXZXIXRM macro in a standard JES exit or JES3 DSP)
10 Exit IXZXIT02 is invoked to modify the ASYNCACK message acknowledgement from POK before MCR receives the acknowledgement.
11 MCR acknowledges the acknowledgement from POK (using the IXZXIXAC macro in a standard JES exit or JES3 DSP)

Steps A and B (member attach) and steps C and D (member detach) are provided in the following series of macro coding examples for completeness. It is not the intention to suggest that you would ever attach members, send a single message, and then immediately detach members.

(A) Exit IXZXIT03 (Attach/Detach) for MCR

⋮
attach   IXZXIXAT GROUP=GROUP,MEMBER=MCR,WHICHJES=JES2,    X
         RELEASE=FMID,GROUPTOKEN=MCRGTOKE,                 X
         RTNCODE=RTNCODE,RSNCODE=RSNCODE
⋮
GROUP     DC  CL8'IBMVSLAB'
MCR       DC  CL16'MCR'
FMID      DC  CL8'HJE5510'
MCRGTOKE  DS  F
RTNCODE   DC  F'0'
RSNCODE   DC  F'0'
⋮

Member MCR attaches to JES XCF group IBMVSLAB. The group token is returned in field MCRGTOKE.

(B) Exit IXZXIT03 (Attach/Detach) for POK

⋮
attach   IXZXIXAT GROUP=GROUP,MEMBER=POK,WHICHJES=JES2,    X
         RELEASE=FMID,GROUPTOKEN=POKGTOKE,                 X
         RTNCODE=RTNCODE,RSNCODE=RSNCODE
⋮
GROUP     DC  CL8'IBMVSLAB'
POK       DC  CL16'POK'
FMID      DC  CL8'HJE5510'
POKGTOKE  DS  F
RTNCODE   DC  F'0'
RSNCODE   DC  F'0'
⋮

Member POK attaches to JES XCF group IBMVSLAB. The group token is returned in field POKGTOKE.

(1) Mailbox Build (IXZXIXMB) for MCR
`⋮ mbbuild IXZXIXMB MBOXNAME=MBOXNAME,POSTXIT=POSTXIT, X POSTDATA=POSTDATA,GROUPTOKEN=MCRGTOKE,SYSEVENT=NO,... ⋮ MBOXNAME DC CL16'MCR␢MAILBOX' POSTXIT DS A POSTDATA DS A ⋮`

Member MCR builds mailbox MCR␢MAILBOX. Field POSTXIT contains the address of the POST exit routine. Field POSTDATA contains the address of a data area passed to the POST exit routine.

(2) Mailbox Build (IXZXIXMB) for POK
`⋮ mbbuild IXZXIXMB MBOXNAME=MBOXNAME,POSTXIT=POSTXIT, X POSTDATA=POSTDATA,GROUPTOKEN=POKGTOKE,SYSEVENT=NO,... ⋮ MBOXNAME DC CL16'POK␢MAILBOX' POSTXIT DS A POSTDATA DS A ⋮`

Member POK builds mailbox POK␢MAILBOX. Field POSTXIT contains the address of the POST exit routine. Field POSTDATA names the field that contains the address of a data area passed to the POST exit routine.

(3) Send Message (IXZXIXSM) from MCR to POK

⋮
send     IXZXIXSM MBOXNAME=POK_MBOX,MEMBER=POK,           X
         GROUPTOKEN=MCRGTOKE,DATA=TOMESSAGE,DATALEN=DLENGTH,    X
         REQTYPE=ASYNCACK,REQTOKEN=TOTOKEN,REQMBOX=MCR_MBOX,    X
         RTNCODE=RTNCODE,RSNCODE=RSNCODE
⋮

TOMESSAGE DC  A(MESSAGE)
DLENGTH   DC  A(L'MESSAGE)
MESSAGE   DC  CL80'Message to process'
MCR_MBOX  DC  CL16'MCR␢MAILBOX'
POK_MBOX  DC  CL16'POK␢MAILBOX'
TOTOKEN   DS  XL8
RTNCODE   DS  F
RSNCODE   DS  F
⋮

Member MCR sends an ASYNCACK message to member POK's mailbox (POK␢MAILBOX). Field TOMESSAGE contains the address of the message being sent. REQTOKEN defines a field to contain a token returned by send message processing to associate the message acknowledgment with this message. The acknowledgement is to be returned to MCR␢MAILBOX.

4 Exit IXZXIT01 is invoked on member MCR to modify the message before delivery to POK␢MAILBOX.

(5) Receive Message (IXZXIXRM) from MCR to POK
`⋮ receive IXZXIXRM MBOXNAME=POK_MBOX,GROUPTOKEN=POKGTOKE, X MSGTOKEN=MTOKEN,DATA=DATA,DATALEN=DLEN,... ⋮ POK_MBOX DC CL16'POK␢MAILBOX' DATA DC A(0) DLEN DC F'0' MTOKEN DS XL8 ⋮`

The message is sent to member POK. The POST exit routine posts member POK, which then receives the ASYNCACK message from POK␢MAILBOX. Field DATA contains the address of the message to be received. MSGTOKEN defines a field to contain the token member POK is to use to associate its acknowledgement with this message.

6 Exit IXZXIT02 is invoked on member POK to modify the message before delivery to POK.

(7) Acknowledge Message (IXZXIXAC) from POK to MCR
`⋮ acknow IXZXIXAC GROUPTOKEN=POKGTOKE,MSGTOKEN=MTOKEN, X USERRC=USERRC,... ⋮ USERRC DC F'0' ⋮`

Member POK acknowledges the ASYNCACK message from member MCR. POK uses the message token returned in MTOKEN to identify the message being acknowledged. The user return code (USERRC) provides a return code to the sender of the original message (member MCR).

8 Exit IXZXIT01 is invoked on member POK to modify the acknowledgement.

(9) Receive Acknowledgement (IXZXIXRM) from POK to MCR
`⋮ receive IXZXIXRM MBOXNAME=MCR_MBOX,GROUPTOKEN=MCRGTOKE, X MSGTOKEN=MTOKEN,DATA=ACKMSG,DATALEN=DLEN,... ⋮ MTOKEN DS XL8 ACKMSG DC A(0) DLEN DC F'0' ⋮`

The message is sent to member MCR. The POST exit routine posts member MCR, which then receives the acknowledgement in MCR␢MAILBOX. JES XCF places the address of the acknowledgement in field ACKMSG. The message token, which member POK used to associate the acknowledgement with the message, is returned in field MTOKEN.

10 Exit IXZXIT02 is invoked on member MCR to modify the acknowledgement before delivery to MCR.

(11) Acknowledge Message (IXZXIXAC) from POK to MCR
`⋮ acknow IXZXIXAC GROUPTOKEN=MCRGTOKE,MSGTOKEN=MTOKEN,... ⋮ MTOKEN DS XL8 ⋮`

Member MCR acknowledges the acknowledgement from POK. MCR uses the message token returned in field MTOKEN to identify the acknowledgement that is being acknowledged.

In this example, the two JES members have completed their communication and each could detach from the JES XCF group. Remember, a detach is accomplished only through exit IXZXIT03, and exit IXZXIT03 gets control only during JES initialization and termination. This detach code is not called while the JES address space remains active.

(C) Exit IXZXIT03 (Attach/Detach) for MCR
`⋮ detach IXZXIXDT GROUPTOKEN=MCRGTOKE,RTNCODE=RTNCODE, X RSNCODE=RSNCODE ⋮ RTNCODE DC F'0' RSNCODE DC F'0' ⋮`

Member MCR detaches from JES XCF group IBMVSLAB.

(D) Exit IXZXIT03 (Attach/Detach) for POK
`⋮ detach IXZXIXDT GROUPTOKEN=POKGTOKE,RTNCODE=RTNCODE, X RSNCODE=RSNCODE ⋮ RTNCODE DC F'0' RSNCODE DC F'0' ⋮`

Member POK detaches from JES XCF group IBMVSLAB.