RETRIEVE BUFFER - Use the RETRIEVE BUFFER function to terminate
all outstanding messages and communications paths, and to end IUCV com­
munications. CP system code (outside IUCV support) cannot use the
RETRIEVE BUFFER function.
Virtual Machine to Virtual Machine Communication
Figure 16 illustrates the sequence of functions invoked when a virtual machine
communicates with another virtual machine. The functions include initialization,
connection to another virtual machine, sending and receiving messages, replying to
and waiting for messages, severing communications with the other virtual machine,
and termination.
Virtual Machine X Communicating to Virtual Machine Y (VIRTUAL MACHINE X)
1 DECLARE BUFFER
2 CONNECT to Y
5 Get External Interrupt
6 SEND to Y
8 TEST COMPLETION 11 Get External Interrupt fori TEST COMPLETION 12 SEVER
15 RETRIEVE BUFFER
Figure 16. Sequence of Functions
(VIRTUAL MACHINE Y) 1 DECLARE BUFFER
3 Get External Interrupt
4 ACCEPT
7 Get External Interrupt fori DESCRIBE
9 RECEIVE 10 REPLY 13 Get External Interrupt
14 SEVER
15 RETRIEVE BUFFER
1. Virtual machine X wishes to communicate with virtual machine Y. Both virtual
machines must independently invoke the DECLARE BUFFER function. The
buffer is used to provide the virtual machine with information about incoming
external interrupts concerning IUCV functions.
2. Virtual machine X invokes the CONNECT function, indicating Y as the target. IUCV checks the directory to determine if this connection is authorized. If it
is, IUCV queues an external interrupt for Y indicating that there is a pending
connection for it. IUCV returns control to X at the next instruction after the CONNECT; a return code indicates that a partial connection has been estab­
lished.
Inter-User Communications Vehicle 123

3. The external interrupt queued by step 2 is reflected to Y indicating a pending
connection. IUCV places the external interrupt information in the buffer that
Y provided in step 1. IUCV passes control to the external interrupt handler of
Y.
4. Virtual machine Y interprets the external interrupt and responds with an ACCEPT to complete the connection. IUCV then completes the connection
and queues a connection-complete external interrupt for X. IUCV returns
control to Y at the next instruction after the ACCEPT; a return code indicates
that the connection is complete.
5. The external interrupt queued by step 4 is reflected to X, indicating that the
connection is complete and the communication path is available for use. IUCV places the external interrupt information in the buffer that X provided in step
1.
6. Virtual machine X issues a SEND. The SEND function queues an external
interrupt for Y indicating that there is a message pending. Control returns in X
at the next instruction after the SEND; areturn code indicates that the ' sage has been sent.
7. If virtual machine Y is enabled for external interrupts and for IUCV messages
(via SET MASK), the external interrupt queued by step 6 is reflected to Y,
indicating that a message is pending. IUCV places external interrupt informa­
tion in the buffer specified in step 1. IUCV passes control to the external
interrupt handler of Y. If virtual machine Y is disabled for external interrupts
or IUCV messages and invokes the DESCRIBE function, IUCV places the
information identifying the message in the DESCRIBE parameter list and the
pending-message external interrupt for this message is cleared. IUCV passes
control to the next instruction after the DESCRIBE.
8. While virtual machine Y is processing the message, virtual machine X can
decide to check if the communication has been completed by issuing the TEST COMPLETION function. The condition code indicates that (in this example)
the communication is not complete.
9. With the message description from step 7, virtual machine Y starts to process
the message and issues a RECEIVE. The parameter list associated with
RECEIVE specifies where the message data is stored in virtual machine Y. 10. When processing the message is complete, virtual machine Y responds to X by
invoking the REPL Y function. The REPLY function queues an external inter­
rupt for X indicating that there is a reply pending. Control returns to Y at the
next instruction after the REPLY; a return code indicates that the reply has
been transferred.
11. If virtual machine X is both enabled for external interrupts and enabled for IUCV replies, the external interrupt queued by step 10 is reflected to X, indi­
cating a reply pending. To identify the reply, the external interrupt information
is placed in the buffer specified in step 1. IUCV passes control to the external
interrupt handler of X. If virtual machine X is disabled for external interrupts
and issues a TEST COMPLETION, IUCV places the information identifying
the reply in the TEST COMPLETION parameter list and clears the queued
external interrupt concerning this reply. IUCV passes control to the next
instruction after the TEST COMPLETION. 124 VM/SP System Programmer's Guide