April 1, 1981
Descriptions of VMCF Subfunctions
There are two types of VMCF subfunctions: data transfer and control.
THE CONTROL SUBFUNCTIONS The VMCF control subfunctions allow efficient management
transfer operations from your virtual machine console. The
subfunctions are: AUTHORIZE, UNAUTHORIZE, CANCEL, QUIESCE, IDENTIFY, and REJECT.
of data
control RESUME, AUTHORIZE enables VMCF for a virtual machine; once AUTHORIZE has been
executed, the virtual machine can execute other VMCF subfunctions and
receive messaqes and data from other authorized VMCF virtual machines.
It is possible to specify three options with the AUTHORIZE subfunction: SPECIFIC, PRIORITY, and VMCPSMSG. The SPECIFIC option authorizes communication with a specific virtual Any messaqes sent to the virtual machine from other than the
specified virtual machine will be rejected. The SPECIFIC option can be
used in an application where virtual machines desire to communicate with
a master controller but not among themselves. Under the message
facility, CP is authorized with every virtual machine that is to receive
messages sent via the SMSG command. Virtual machines that are to
receive messages must authorize themselves.
The PRIORITY option allows a virtual machine to authorize the receipt
of priority messaqes. A virtual machine is allowed to send priority
messages to another virtual machine only if the other virtual machine is
authorized to receive priority messages. A priority message is one that
will be queued ahead of nonpriority messages and therefore accepted
first. When you execute the AUTHORIZE subfunction, you must specify the
address and length of the external interrupt buffer for your virtual
machine. The buffer must be large enough to contain a £ixed message
header (40 bytes). The message header identifies messages sent by other
virtual machines or responses to messages you might send to your own
virtual machine.
If you are going to accept SENDX-type communications, you must
specify the size of the external interrupt buffer as 40 plus the maximum
size of SENDX data that you plan to accept. This has the effect of
authorizing SENDX protocol. That is, a virtual machine may receive data
along with the external interrupt in its external interrupt buffer. When a virtual machine sends data to another virtual machine via the SENDX the data must fit in that virtual machine's externaJ
interrupt buffer or the subfunction will be rejected. Messages sent via
the special message facility require a buffer length of 169 bytes.
Any AUTHORIZE options in effect can
reexecuting the AUTHORIZE subfunction. If
execution of the AUTHORIZE subfunction,
authorization status is not changed.
be reset or changed by
there are errors during
a virtual machine's Part 2. Control Program (CP) 153

Paqe of GC20-1807-7 As Updated April 1, 1981 by TNL GN25-0829 UNAUTHORIZE terminates VHCF activity for a virtual machine. The UNAUTHORIZE subfunction causes any stacked or queued messages associated
with the virtual machine to be purged. A virtual machine should execute
the QUIESCE subfunction before executing UNAUTHORIZE if messages that
are already queued are to be handled. When a virtual machine executing UNAUTHORIZE has pending final response external interrupts, 'the
interrupts are purged. If a virtual machine has pending SEND external
interrupts from another source virtual machine, a RESPONSE interrupt is
reflected to the source indicating that the virtual machine is no longer
available. CANCEL cancels a message or data transfer pending for but not accepted
by another VMCF virtual machine. A virtual machine can CANCEL ·messages
it oriqinates with SEND, SENDX, or SEND/RECV subfunctions. A message
cannot be canceled if any of the following conditions exist: • The request was SENDXor IDENTIFY and the sink had already received
the SEND external interrupt. • The request was SEND and the sink had already executed the RECEIVE or REJECT subfunctions. • The request was SEND/RECV and the sink had already executed the REPLY or REJECT subfunctions.
If the original request was SEND/RECV and the sink virtual machine had
executed the RECEIVE subfunction but not the REPLY, the REPLY can be
canceled. A virtual machine is notified of this condition with a DIAGNOSE return code. (For a description of the return codes, see
Figure 19). QUIESCE temporarily rejects SEND, SENDX, SEND/RECV, or IDENTIFY requests
from other virtual machines. QUIESCE allows a virtual machine to
receive any stacked or queued messages but reject further SEND, SENDX, IDENTIFY, or SEND/RECV requests from other virtual machines. QUIESCE can be used to indicate to other virtual machines that the virtual
machine is in QUIESCE status, authorized for communication but not able
to accept messages at this time (e.g., entering slowdown, my buffers are
full, tryaqain later). The IDENTIFY subfunction could be used to
inform other virtual machines that a particular user is no longer in QUIESCE status. You should execute the QUIESCE subfunction before
executing the UNAUTHORIZE subfunction to avoid losing messages (see "UNAUTHORIZE: DIAGNOSE Code X '68' Subfunct"ion Code X· 0001"')... A virtual
machine can reset the OUIESCE status (exit slowdown) by executing the RESUME subfunction. (See "RESUME: DIAGNOSE Code X'68' Subfunction Code X'0009'''). A virtual machine in QOIESCE status may continue to send
messaqes to other virtual machines. QUIESCE status for a virtual
machine only affects messages sent from other virtual machines.
154 IBM VM/370 System Programmer's Guide