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, theDECLARE 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 theCONNECT 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 theSEND 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 theQUIESCE
To quiesce is to pause or alter a device or application to achieve a consistent state, usually in preparation for a backup or other maintenance.
Description
In software applications that modify information stored on disk, this generally involves f ...
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 theTEST 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 theSEVER 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 theRETRIEVE 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 theDECLARE 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 theIUCV 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.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
See also
*References
{{ReflistExternal links