MSGBLOK remains on the SEND queue and the length of the remaining data
is stored in the parameter list. The target virtual machine can obtain the
remainder of the message with a subsequent RECEIVE. The RECEIVE func­
tion completes a one-way communication. When invoking the RECEIVE
function, you can identify the message you wish to receive. Identify the mes­
sage completely by specifying the message id, path id, and target message class.
If you do not specify the message id, you can identify the message by path id,
target message class, or both. If you do not specify any identifiers when invok­
ing the RECEIVE function, you receive the first message that has not been
partially received. Note that if a message has been partially received, you must
identify the message completely to receive the remainder. REPLY - Use the REPLY function to respond to a message sent by a source
communicator. When a target virtual machine invokes the REPLY function,
IUCV moves the MSGBLOK for the specified message from the target com­
municator's RECEIVE queue to the source communicator's REPLY queue.
Data in the target's reply area is moved to the source communicator's answer
area. The target communicator can specify that a reply is a priority reply.
IUCV queues a priority reply ahead of any nonpriority replies and after any
earlier priority replies. When invoking the REPLY function, you must identify
completely the message to which you wish to reply. Identify the message com­
pletely by specifying the message id, path id, and target message class. TEST COMPLETION - Use the TEST COMPLETION function to determine
if any messages have been completed. When a source virtual machine invokes
the TEST COMPLETION function, IUCV removes the MSGBLOK represent­
ing the specified message from the REPLY queue and destroys that MSGBLOK. When invoking the TEST COMPLETION function, you may
identify which message you wish to complete. You can identify the message
completely by message id, path id, and source message class. If you do not
specify the message id, you can identify the message by path id, source mes­
sage class, or both. If you do not specify any identifiers when invoking the TEST COMPLETION function, IUCV completes the first message on the REPLY queue. CP system code (outside of IUCV support) cannot use the TEST COMPLETION function. TEST MESSAGE - Use the TEST MESSAGE function to determine whether
any messages or replies are pending on a communicator's SEND queue or REPLY queue. When a virtual machine invokes the TEST MESSAGE func­
tion, the virtual machine enters a wait state if neither messages nor replies are
pending. If an IUCV message or reply becomes pending while the virtual
machine is in the wait state, the virtual machine begins execution by
re-executing the TEST MESSAGE function (which returns a condition code).
By using the TEST MESSAGE function, a virtual machine avoids the necessity
of external interrupt handling.
REJECT -Use the REJECT function to refuse a specified message sent by a
source communicator. After invoking the DESCRIBE or RECEIVE function,
a target communicator can choose not to process a message. The REJECT
function moves the MSGBLOK representing the specified message from the
target's SEND queue or RECEIVE queue to the source communicator's REPLY queue. IUCV updates the message's audit trail to indicate that the
message has been rejected. No message data is moved when the REJECT
function is invoked. When invoking the REJECT function, you must identify
which message you wish to reject. You can identify the message completely by
Inter-User Communications Vehicle 121

specifying the message id, path id, and target message class. If you do not
specify the message id, you must identify the message by path id, target mes­
sage class, or both. • PURGE - Use the PURGE function to terminate a specified message sent to a
target virtual machine. If the source virtual machine purges a message before
the target has described or received it, the target is never aware that the mes­
sage was sent. If the message is already on the source's REPLY queue, IUCV terminates the message immediately. If the message has been described to the
target, IUCV notifies the target that the message has been purged. IUCV indi­
cates that the message has been purged when the target issues the RECEIVE
or REPLY function for the message. IUCV then destroys the message. When
invoking the PURGE function, you must identify which message you wish to
purge. You can specify only a path identifier, or a path id, message identifier,
and message class. If you do not specify a message identifier, the message
class is optional.
122 VM/SP System Programmer's Guide SET CONTROL MASK - Use the SET CONTROL MASK function to enable
or disable external interrupts for the IUCV control functions: connection
pending, connection complete, path severed, path quiesced, and path resumed.
A virtual machine must first be enabled for external interruptions by setting
both bit 7 in the virtual PSW and submask bit 30 in control register zero to
one. The SET MASK IUCV control bit must also be set on or the SET CON­
TRoL MASK settings are ignored. The SET CONTROL MASK function
cannot be used from CP system code. SET MASK - Use the SET MASK function to enable or disable IUCV external
interruptions for priority messages, nonpriority messages, priority replies, non­
priority replies, and IUCV control functions. A virtual machine must also be
enabled for external interruptions by setting both bit 7 in the virtual PSW and
submask bit 30 in control register zero to one. The SET MASK function can­
not be used from CP system code. QUIESCE - Use the QUIESCE function to temporarily suspend incoming mes­
sages on an IUCV path. A communicator may reactivate a path by invoking
the RESUME function or may leave the path quiesced, making it a one-way
path. RESUME - Use the RESUME function to restore communications over a pre­
viously quiesced path. SEVER - Use the SEVER function to reject a pending connection or to termi­
nate a completed IUCV path. If the path is complete, both communicators
must issue the SEVER function for the path to be terminated. After one com­
municator invokes the SEVER function, all messages outstanding on the path
are terminated and IUCV notifies the communicating partner (via a SEVER external interruption). The communicating partner then can dequeue and
process the terminated messages if it chooses. The communicating partner
invokes the SEVER function when it finishes processing messages on the path.
If the path is a pending connection, either communicator may invoke the SEV­ ER function. If the originator of the connection invokes SEVER and the tar­
get has received the pending-connection external interruption, the target must
also invoke the SEVER function. If the target invokes SEVER first, the origi­
nator must do so as well.