12. Virtual machine X has now completed its communications with virtual machine
Y and issues a SEVER to break the communications path. The SEVER func­
tion queues an external interrupt for Y indicating that the communication link
has been broken. Control returns in X at the next instruction after the
SEVER; a return code indicates the path has been broken.
13. The external interrupt queued by step 12 is reflected to Y indicating that the
path has been broken by virtual machine X. Virtual machine Y can now do
any clean up needed in its storage.
14. After virtual machine Y has completed processing, the virtual machine issues a SEVER to notify LUCY that is also is finished with the communication link. LUCY can then clean up the control blocks.
15. When all communications are complete and all communication paths have been
severed, both virtual machines independently invoke the RETRIEVE BUFFER
function.
IUCV Communications Using Parameter List Data
To better understand how data specified in the parameter list is handled, the LUCY functions are covered in a typical user scenario:
1. The lUCV DECLARE BUFFER, CONNECT, and ACCEPT sequence must
be invoked to establish the user's external interrupt buffer and a path to the
target virtual machine (or CP). If you expect to receive data in the parameter
list, you must authorize such communication on the CONNECT or ACCEPT
by specifying PRMDAT A= YES. The external interrupt information to the
target communicator includes a bit indicating if PRMDAT A= YES was chosen.
2. Issue an LUCY SEND request. When the data is to be passed in the parameter
list, the DAT A=PRMMSG option is used on the LUCY macro, and the
PRMMSG= option is used to move the data into the parameter list. Or you
can avoid using the macro options by initializing the parameter list yourself.
The sender of the message should be prepared to handle a return code indicat­
ing that DATA=PRMMSG is not allowed if the target communicator has not
specified PRMDAT A= YES at connection time. A message block (MSGBLOK) is created to represent the message within CP and contains the
message data until presented to the target. The message is queued on the target
send queue.
3. If the target is enabled for IUCV pending-message external interrupts, the tar­
get virtual machine receives an LUCY pending-message external interrupt as a
result of the SEND request in the previous step. The message data is stored in
the external interrupt buffer. A flag is set in the IPFLAGS1 field of the buffer
to indicate that the data is in the parameter list. Since the message data has
been presented to the target, the target does not have to issue an IUCV RECEIVE for this message. If the message was a one-way message, the MSGBLOK is destroyed and the communication is complete. There is no
asynchronous return of message completion given to the source (sending) vir­
tual machine on a one-way message.
4. If the target is disabled for LUCY pending-message external interrupts and
issues the IUCV DESCRIBE or RECEIVE functions, the message data is
stored in the parameter list. A flag is set in the IPFLAGS 1 field of the parame-
Inter-User Communications Vehicle 125

Invoking IUCV Functions
ter list to indicate that the data is in the parameter list. Since the message data
is presented to the target on a DESCRIBE, the target does not have to issue an IUCV RECEIVE for this message. If the message was a one-way message, the MSGBLOK is destroyed, and the communication is complete. There is no
asynchronous return of message completion given to the source (sending) vir­
tual machine on a one-way message.
5. If the communication in the previous steps was a two-way message, a REPLY
is issued by the target virtual machine. When the REPLY data is to be passed
in the parameter list, the DATA=PRMMSG option is used on the IUCV mac­
ro, and the PRMMSG= option is used to move the data into the parameter list. Or, you can avoid using the macro options by initializing the parameter list
yourself. The REPL Y er of the message should be prepared to handle a return
code indicating that DATA=PRMMSG is not allowed if the source commu­
nicator has not specified PRMDAT A= YES at connection time. The message
block (MSGBLOK) contains the message data until presented to the source
communicator. The message block is queued on the sender's reply queue.
6. If the source communicator is enabled for IUCV message complete external
interrupts, the source virtual machine receives an IUCV message-complete
external interrupt as a result of the REPLY in the previous step. The message
data is stored in the external interrupt buffer. A flag is set in the IPFLAGS 1
field of the buffer to indicate that the data is in the parameter list. The MSGBLOK is destroyed and the communication is complete.
7. If the target is disabled for IUCV message-complete external interrupts, and
issues the IUCV TEST COMPLETE function, the message data is stored in
the parameter list. A flag is set in the IPFLAGS 1 field of the parameter list to
indicate that the data is in the parameter list. The MSGBLOK is destroyed,
and the communication is complete.
8. SEVER and RETRIEVE BUFFER cause any pending messages (MSGBLOK) to be destroyed for that virtual machine. Since no asynchronous
message-complete interrupt is returned to the source communicator, for
one-way messages using the DAT A=PRMMSG option, the source communica­
tor must realize upon receiving an IUCV SEVER external interrupt from the
target communicator, that messages may not have been received by the target.
Invoke all IUCV functions through the IUCV macro instruction. In general, speci­
fy the name of the IUCV function you wish to perform, the address of a parameter
list to contain input to the function, and keyword parameters. IUCV moves the
values specified on the keyword parameters into the specified parameter list. Most
functions require a parameter list as input to the IUCV macro instruction. Use the
PRMLIST = parameter to specify the address of the parameter list. The parameter
list must begin on a doubleword boundary or a specification exception results.
When invoked from a virtual machine, specify the address of the parameter list as a
guest real address (that is, it must be an address that is real to the virtual machine).
When invoked from CP system code, the address of the parameter list must be a
real address.
Supply input to IUCV functions in two ways: • By coding keyword parameters on the IUCV macro instruction. IUCV stores
values in the function parameter list based on values you specify on the macro.
126 VM/SP System Programmer's Guide ,/