IUCV

Inter User Communication Vehicle (IUCV) is a data transfer mechanism in IBM VM line of operating systems. It was introduced with VM/SP Release 1 in 1980.

It allows establishment of point to point communication channels, either between two virtual machines or between a virtual machine and hypervisor services. In effect, IUCV provides a form of message-based interaction between virtual machines that anticipated the client/server interaction between network connected physical machines that emerged later on distributed systems.

IUCV is implemented by CP (the VM hypervisor) and controls all aspects of session establishments, message passing and flow control.

IUCV basics

Initializing IUCV

Before a virtual machine can use the IUCV service, it must first indicate the address of an area within its address space where CP will be able to store information regarding pending information or status. Therefore, the DECLARE BUFFER method must be invoked first.

The IUCV Path

In IUCV terminology, the session between two end points is called a PATH. It is identified at each end by a Path ID which is only relevant to the virtual machine that owns the session end. A path is always a connected channel - meaning there are no connectionless paths.

Establishing a path

To establish a path, the initiating virtual machine must invoke the CONNECT method, and specify the path target identity, which is either another virtual machine name or the name of a CP system service - which all start with the '*' character - which is not a valid character within a virtual machine name.

Provided the target has initialized IUCV itself, the target will be notified of the pending incoming path connection and may then either use the ACCEPT method - to complete path establishment - or the SEVER method - which effectively closes the pending path.

Once the path is established, messages may be passed between the two path endpoints.

IUCV Messages

IUCV Messages are bounded, that is, they have a beginning and an end. If more than one message is pending on a path for an endpoint, IUCV will not merge the messages.

Messages are sent on the path using the SEND method. The other end point can then receive the message using the RECEIVE method. If the original message also requested a reply, the receiving end point then use the REPLY method to send that reply.

Flow control

Multiple messages may be made pending on a path. The number of messages allowed pending for a path is specified during path establishment but cannot exceed 65535. Attempting to send a message on a path which has reached its pending message limit will result in an error.

Suspend and resume

Data transfer may be temporarily suspended by using the QUIESCE method. While the path is suspended, no further message transfers are allowed on the path until the RESUME method is invoked by the virtual machine that initially suspended the path.

Polling

A virtual machine may poll for IUCV notifications using the TEST MESSAGE and TEST COMPLETION methods. If nothing is pending, then the virtual machine waits until further information is available.

Explicit path termination

When either end point issues the SEVER method, the path enters a severed (closing) state and the other end point is notified. At this point, no new messages are allowed on the path - but the other end point may still retrieve pending messages. When the other end point also issues the SEVER method, the path is effectively dismantled.

Implicit path termination

A path may be implicitly closed when

• A virtual machine logs off
• A virtual machine is reset
• A virtual machine terminates IUCV operations using the RETRIEVE BUFFER method

In either of those cases, for the other end of the path, the behavior is identical to an explicit path termination.

Using IUCV

The B2F0 instruction

IUCV methods are invoked by using the 'B2F0'x instruction. This instruction must be invoked while in virtual supervisor state (for example a guest supervisor) or an Operation Exception program interrupt is generated. The instruction is then interpreted by CP as an IUCV request.

IPARML

IPARML is the Iucv PARaMeter List. It is a control block that describes the method being invoked as well as the method parameters. Upon completion of the B2F0 instruction, some fields are altered by CP to indicate the status of the B2F0 instruction completion.

Notifications

CP notifies a virtual machine of a pending message or status information by making an external interrupt code X'4000' pending to the virtual machine. When the interrupt occurs, the information regarding the pending status is made available at the address location specified by the DECLARE BUFFER method.

Macros

CP Macros

CP has a specific macro (IUCV) which generates the appropriate code - including the instruction and filling in the IPARML - so that the details regarding the parameters about such and such method can be defaulted or checked for conflict.

CMS Macros

CMS can be made to handle IUCV application requests. CMS has its own set of IUCV macros (CMSIUCV) which allow multiple applications to share the IUCV facility within a virtual machine.

Authorization

Access to some IUCV functions is controlled by statements in the CP Directory (the list of virtual machines and their specifications).

A virtual machine can be permitted to accept communications from all other virtual machines via the IUCV ALLOW directory statement, or establish a communication path with any other virtual machine via the IUCV ANY statement. It is also possible to allow a virtual machine to issue path connection requests to other specific virtual machines by specifying the virtual machine name in an IUCV statement, for example: IUCV TARGETVM. By default, a user is always allowed to connect to itself.

The IUCV statement controls CP-imposed access control for IUCV connections. In addition, a virtual machine can impose its own access control by rejecting an attempt to connect.

Examples of IUCV use

CP System services

The CP system services are IUCV end points which are not virtual machines by themselves, but allow a virtual machine to perform hypervisor functions asynchronously or to access specific hypervisor facilities.

Some examples are

• *MSG : The Message System Service. Allows a virtual machine to receive through IUCV specific virtual machine console outputs such as the results of the 'CP MESSAGE' or Console I/O. This is used by VM subsystems such as PROP (The PRogrammable OPerator) or Fullscreen CMS.
• *SPL : Allows accessing spool files asynchronously. RSCS (The Remote Spool Communication Subsystem) is an example of an application that uses this system service.

GCS

GCS (The Group Control System) of VM uses IUCV to perform maintenance of shared memory areas between virtual machines. By using implicit path termination, the GCS recovery virtual machine can ensure that any locks held on the shared area by a virtual machine that entered the group but left unexpectedly is properly released.

VM TCP/IP

VM TCP/IP - the TCP/IP stack for VM - uses IUCV to either allow a virtual machine to perform socket operations or to allow a virtual machine to act as a network interface to pass whole frames or datagrams between itself and the TCP/IP stack. The S/390 and z/Architecture implementation of Linux uses this facility to implement a network interface to the VM TCP/IP stack.

See also

• VMCF – The Virtual Machine Communication Facility
• Channel-to-channel adapter

External links

• IUCV in z/VM 5.3 CP Programming Services manual chapter 2.1.3