Performance ConsideratiollS
Using IUCV Functions IUCV assigns path ids and records the path id in each communicator's communi­
cation control table (CCT). IUCV sets up one CCT for each virtual machine and
one for the CP system. A given communicator can reference only the paths
recorded in its own CCT. Other references are not possible. IUCV assigns the message id for each message. Although this message identifier
may be reused, at any given time, it identifies only one message. IUCV does not
use this identifier as a direct reference, but only as an operand in a comparison. It
is conceivable that a virtual machine could generate a valid message identifier and
use this to request a message. However, when a message id is used to request a
message, a user must also specify a message class and a path id. If the specified
message is not associated with the specified path id, and message class, the user
cannot access the messages. If the message id, path id, and message class do
match, the user could legitimately access it by specifying simply path id and/or
message class without the generated message id.
The installation can limit the number of connections for a particular virtual
machine in the virtual machine directory.
The overhead involved in reflecting IUCV external interrupts to the virtual
machine can be reduced if the buffer declared on the DECLARE BUFFER func­
tion is entirely within one page. Overhead can be reduced further if the buffer is
entirely within page 0 of the virtual machine.
Modules DMKIUA and DMKIUE can be made resident to improve the perform­
ance of IUCV.
Communicators invoke all IUCV functions through the IUCV macro instruction.
When using the IUCV macro instruction, communicators specify which function
they wish to perform. Most functions also require the address of a parameter list to
contain inputs to and outputs from the requested function. Communicators can
store inputs directly in the parameter list or they can specify inputs with keyword
parameters. IUCV moves the values specified on the keyword parameters into the
specified parameter list. For details on how to use the IUCV macro, see the sec­
tion "Invoking IUCV Functions".
The following list describes the IUCV functions in the order that they might be
used in a typical communication.
QUERY -Use the QUERY function to determine how large a buffer IUCV requires to store external interrupt information. IUCV returns the number of
bytes required in general register zero. In addition, use the QUERY function
to determine the maximum number of communication paths that can be estab­
lished for your virtual machine. IUCV returns the maximum number of paths
in general register one. The QUERY function does not use a parameter list. CP system code cannot use the QUERY function.
DECLARE BUFFER -Use the DECLARE BUFFER function to specify the
address of a buffer into which IUCV can store external interrupt information.
If a virtual machine receives an IUCV external interruption, IUCV stores in
Inter-User Communications Vehicle 119

this buffer information about the message, reply, or control function that
caused the the interruption. Each virtual machine must declare a buffer prior
to establishing any connections.
Note: When a communicator invokes the DECLARE BUFFER function, IUCV automatically enables the virtual machine for all five types of IUCV external interrupts. Use the SET MASK function to change these initial set­
tings. CP system code does not declare a buffer. • CONNECT - Use the CONNECT function to request the establishment of a
communications path with another communicator. When a source communica­
tor invokes the CONNECT function, IUCV establishes a pending connection.
The path is not complete until the target communicator invokes the ACCEPT function. 120 VM/SP System Programmer's Guide ACCEPT - Use the ACCEPT function to respond to a pending connection.
When a target communicator invokes the CONNECT function, IUCV com­
pletes the connection and enables the path for use. A target communicator can
refuse a pending connection by invoking the SEVER function.
SEND - Use the SEND function to initiate a communication with another vir­
tual machine or CP system service. When a source communicator invokes the
SEND function, IUCV creates a MSGBLOK for the message and enqueues it
on the target communicator's SEND queue. The message text is not transmit­
ted to the target virtual machine until the target communicator invokes the
RECEIVE function. If the installation has authorized the path for priority
messages, you may indicate that the message is a priority message. IUCV queues priority messages ahead of nonpriority messages on the target commu­
nicator's SEND queue (and after any priority messages that have not yet been
received). In addition, you may specify that a message is a one-way communi­
cation. When the target communicator receives a one-way communication, he
cannot send a reply.
DESCRIBE - Use the DESCRIBE function to determine the presence of any
messages on the SEND queue that have not been previously described or
reflected in a message-pending IUCV external interruption. If a previously
undescribed and unreflected MSGBLOK is on the SEND queue, IUCV returns
pertinent information about the MSGBLOK in the parameter list. The MSGBLOK description stored by IUCV consists of the path id, the target mes­
sage class, the message id, the message flags, the length of the message, and
the length of the source's answer area. This information allows the target
communicator to receive the message using the RECEIVE function. IUCV describes a particular message once. It is the responsibility of the target com­
municator to remove described messages from the SEND queue. Messages can
be removed by invoking the RECEIVE or REJECT function. The DESCRIBE
function clears the pending-message external interruption for the described
message. CP system code (outside of IUCV support) cannot use the
DESCRIBE function.
RECEIVE - Use the RECEIVE function to accept messages sent via the
SEND function. When a target virtual machine issues the RECEIVE function, IUCV moves the actual message data from the source virtual machine's send
area to the target virtual machine's receive area. If the complete message has
been moved from the send area to the specified receive area, IUCV moves the MSGBLOK for the specified message from the SEND queue to the RECEIVE
queue. If the receive area cannot completely contain the message, the