A VMGROUP maps "user names" onto "suites". A "user name" is an 8 byte string that, for intended uses, should be eight upper case EBCDIC characters, padded to the right with blanks ala CP's user names. A "suite" is a VMCOMM object and a few other keys (....).

Virtual machines may join a "Group". Their virtual machine name is in relation to the group and the group defines which other machines they may communicate with using spool files, messages, VMCF, IUCV etc.

Being in a group is analogous to being in the CP user directory. It does not indicate whether or not the user is "logged on".

VM Group Factory

VMGROUPF(0;PSB,M,SB==>c;VMGROUP) Create VM Group

VMGROUPF(kt==>X'12345679')

VM Group Internal Key

VMGROUP Record Collection

VM Comm Factory

VMCOMMF(0,(8,vmname); prompt_sb,meter,sb,VMGROUPRC,VMGROUPI ==> c;VMCOMM,COMMQ) Create VMCOMM object
See (vmcomm) and (commq) for the respective orders on VMCOMM and COMMQ.

CP simulator Group Communication Key

COMMQ - Communication Queue key

N.B. COMMQ conforms to the protocol described at (cpgcomm). The source of these keys is described at (vmcommf).

COMMQ(0,(8,tod),(8,sender),message==>c) Message for your VM

tod - Time message was sent

sender - The username of the sender

message - Text of message in EBCDIC

Return codes:

0 - done

57 - Message cannot be accepted

COMMQ(1==>) There are one or more spool files waiting to be picked up

COMMQ(2==>) There are one or more pending IUCV connections.

COMMQ(other{3 to 10}, ...) is accepted in the same forms as the CPGCOMM Key, and is queued and passed on unchanged.

Return codes:
0 - message queued

57 - message cannot be accepted

COMMQ(kt+4==>) Destroy VMCOMM object

VMGIUCVPF(0,(8,source_vmid),(8,target_vmid),(2,source_pathid), (2,msglim),(1,flags),(16,userdata);
prompt_sb,meter,sb,VMGROUPI,VMGROUPRC,S,source_commq ==> c,(2,msglim),(1,flags);VMGIUCVP) Connect
This operation checks authorization for the requested path and returns an IUCV Path key.

Passed string (passed on second jump of extended jump protocol):

source_vmid(c8) - the userid of the virtual machine that did the CONNECT function.

target_vmid(c8) - the userid of the virtual machine to which the path is to be established.

source_pathid(x2) - will be used in messages to the source_commq key to identify this path

msglim(i2) - the maximum number of outstanding messages which the source wishes to allow on the path

flags(x1) - contains the following bits:

X'80' - indicates that the source can handle message data in the parameter list.

X'40' - (quiesced) indicates that you do not want to receive messages until you do a resume operation.

X'20' - indicates that the source wants to send priority messages on this path.

X'04' - indicates the path is to be a control path

userdata(x16) - data that is passed to the target in the CPGCOMM(message_pending) operation.

S - The segment that will contain the source's IUCV message buffers (i.e. the virtual machine's real memory segment).

Returned string:

msglim(i2) - the message limit for this path

flags(x1) - contains the following bit:

X'20' - indicates that you may send priority messages on this path

Return code:
0 - Normal return. The connection request is now pending, and the target VM will be notified.

1 - prompt_sb not a bank

2 - prompt_sb has insufficient space

3 - sb has insufficient space

4 - insufficient keys passed (extended jump protocol must be used)

5 - error writing to VMGROUPRC (out of space or implementation limit)

11 - target VM is not in the group (not "logged on")

12 - target VM has not invoked the DECLARE BUFFER function

13 - the path would exceed the maximum number of connections allowed for the source

14 - the path would exceed the maximum number of connections allowed for the target

18 - value in msglim exceeds 255

VMGIUCVPF(kt==>X'1234567C')

VMGVMCFF - VMCF path Factory for VM Group

VMGVMCFF(0,(8,senderid),(8,receiverid),(1,flags),
(4,rcvrextintbuflen);
PSB,M,SB,sender_seg,receiver_set,sender_commq,receiver_commq ==> c;sender's key, receiver's key) Create VMCF path
Creates a VMCF path. A VMCF path is one-way. Messages from A to B go over one path, messages from B to A go over a different path.

VMGVMCFF(kt ==> X'12345680')

The idea
This is a scheme to allow virtual machines running within CP to join, roughly, a VMGROUP within a KEYKOS running within the same CP. We propose to support IUCV first but may support other VM interconnections later.

The idea is to join a user to a VMGROUP that is not a CP simulator, but an adaptor that wields the kernel IUCV key and serves as a surrogate for a virtual machine in the real CP on the real machine. We propose to support paths that originate in a Keykos CMS and connect to a VM supported by the underlying real CP. It will appear that the path originates form the VM under Keykos, but that is ok.

{ni}VMADAPT
VMADAPTF(0;sb,m,sb==>0,VMADAPT)

VMADAPT(0,(8,vmname);VMCOMM==>c;)

VMCOMM is a VMCOMM key from some VMGROUP. vmname is the name in CP's directory for the real machine. This might be the same or different from the name associated with the VMCOMM key.

If VMCOMM is associated with name v1 then an ivocation an IUCV "Connect" naming v1 as destination, from a CMS machine of the VMGROUP will cause an IUCV connection pending interrupt in the machine vmname on the real CP.

The order code is the DIAGNOSE X'68' subcode. See VM System Facilities for Programming.

Sender's orders: SEND, SEND/RECV, CANCEL, IDENTIFY

Receiver's orders: RECEIVE, REPLY, QUIESCE, RESUME, REJECT

VMGVMCF(kt ==> X'12345681')