1 • Page of GC20-1807-7 As Updated April 1, 19a1 by TNL GN25-0829
The buffer used for SOURCE data in a SEND, request should not be freed or reused until
external interrupt is received by the SOURCE. SENDX or SEND/RECV the final response
2. The buffer used for SINK data in a REPLY function can be reused by
the SINK atLer the DIAGNOSE instruction (REPLY; has successfully
completed.
3. The user parameter list (VMCPARM) may be reused upon completion of
the Diagnose instruction. At that point the VMCPARM data has been
copied to a VMCF control block (VMCBLOK) by the control program. A
user should, however, maintain queues of VKCPARM data in order to
associate an external interrupt message header (VMCMHDR) with a
particular request.
4. A user should always interrogate the DIAGNOSE return code or data
transfer error code for possible error conditions. It is the
user's responsibility to determine the types and extent of error recovery_ The DIAGNOSE return code 19 for a SOURCE SEND, SEND/RECV or SENDX request indicates that an error was associated with the SINK user and for a SINK RECEIVE or REPLY request indicates that an
error was associated with the SOURCE user. The user who receives
this return code does not have to invoke error recovery for himself
but only be aware that the transaction did not complete
successfully because of an error associated with the other user. PERFORMANCE CONSIDERATIONS There are several factors that can effect the performance of VMCF: • The VMCF support module, DMKVMC, is a pageable CP module. If a user
has significant paging activity, it may be advantageous to either
lock the module in real storage (CP LOCK command) or alter the CP LOADLIST to make DMKVMC resident. • It is to a user's benefit to have the user parameter list, VMCPARM, in the same 4K page as the DIAGNOSE X'0068' instruction. This may
eliminate a paging operation. e User support modules using the VMCF interface should be written as
reentrant modules and be contained within a CP shared segment
whenever possible. This helps reduce CP paging overhead. • The VMCF external interrupt masking is controlled by PSi bit 7 and CRO bit 31. It is to a user's advantage to always have CRO bit 31
set to 1 (while VMCF is in use) and control the interrupts with PSi bit 7 only. This reduces the number of LCTL instructions. • For applications that involve serial message processing, the SENDX function is the most efficient. The SENDX function eliminates the
need for the SINK to do a RECEIVE operation.
Note: Overall system VM/370 performance is not affected when VMCF is not used by an installation. Part 2. Control Program (CP) 147

April 1, 1981
GENERAL CONSIDERATIONS The SENDX function is a fast way to transfer messages or data and can be
used in place of the CP MSG command where the message length exceeds the
capacity of the terminal input line. Its use is somewhat restricted in
that the maximum data length must be agreed upon by all VMCF users and
then remains fixed unless reneqotiated.
The SEND and SEND/RECV functions are better suited to transfer high
volume data base type information. This type of data transfer requires
the flexibility of a wide range of data lengths along with rigorous
management and control techniques.
The QUIESCE function allows a virtual machine to discontinue
receiving messages. The virtual machine can process those messages
already stacked and then use the RESUME function to continue reception.
The QUIESCE function also allows a virtual machine to process all queued
messages prior to terminating VMCF operation.
The user parameter list, VMCPARM, is designed such that it can be
used foc any subfunction by simply varying the contents of its fields. Users should keep copies of VMCPARMs for all requests made via the SEND, SEND/RECV, or SENDX functions. When a final response interrupt is
received and the interrupt message header indicates no data transfer
errors, the corresponding VMCPARM copy can be released. If a data tcansfec error is indicated, the copy can be used to reinitiate the
tr ansact ion.
VMCF Protocol VMCF pcovides four types of protocol: SEND, SEND/RECV, SENDX, and IDENTIFY. The protocol used to communicate between two virtual machines
depends on the application of VMCF and conventions established by
virtual machine users authorized to use VMCF. A virtual machine must
in voke the AUTHORIZE subfunct ion before it is allowed to use any of the
other subfunctions.
The types of transactions that virtual machines can be involved in
are described by a series of VMCF protocols. In these protocols the
originating virtual machine is called the "source" virtual machine. The
dest inat ion virtu al machine is called the "sink" virt ual machine.
The pcotocol for a transaction remains in effect for the duration of
the transaction.
THE SEND PROTOCOL The SEND pcotocol defines a one-way transfer of data from source virtual
machine stocage to sink virtual machine storage. The SEND protocol uses
the SEND and RECEIVE subfunctions, as described in Figure 15. The source victual machine first transfers data to the sink virtual machine.
This is done by executing the SEND subfunction which specifies the
userid of the sink virtual machine, a message ID, and the address and
length of the data being sent. The sink virtual machine receives an
external interrupt from CP notifying it of the data transfer request.
The sink virtual machine can then respond via the RECEIVE subfunction.
The RECEIVE request specifies the address and the length of the SINK buffer that is to receive the data and causes the data to be transferred
148 IBM VM/370 System Programmer's Guide