The source of VMCOMM keys is described at (vmgroup). The normal use is described at (jvmg).

VMCOMM(register{=0};CPGCOMM==>c,(8,vmname)) Register CP simulator with Group

CPGCOMM is the group communication key from the CP simulator.

Return Codes:

0 - CP simulator is registered and ready for communications. vmname is the name assigned to the virtual machine with the VMGROUP key.

1 - There is already a VM registered under this name. The vmname is not returned and the CP simulator is not registered for communications.

vmname is the name of the virtual machine to receive the message, message is the message in EBCDIC.

Return Codes:

0 - Message sent.

45 - vmname not logged on (not joined).

57 - Not receiveing, edata specifies why.

VMCOMM(retrieve_buffer{=3}==>) Retrieve IUCV buffer.

N.B. This call does NOT sever outstanding connections. The caller must sever any outstanding connections.

target_vmid - the name of the VM to connect to (the target)

flags - As follows:

X'04' - indicates that this is to be a control path

X'20' - indicates you want to send priority messages on this path

X'40' - Path is quisced

X'80' - Data may be sent in the parameter list

source_pathid - Will be used to identify the path for this request in CP Group Communication key messages.

msglim - Maximum number of outstanding messages on path

userdata - User data sent by connector

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

Return Codes:

0 - Connection request made
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

VMGIUCVP - The VMGIUCVP key for the path

1 - there are insufficient resources to create the path

11 - target_vmid not logged on (joined to group)

12 - target_vmid has not completed DECLARE BUFFER

13 - Maximum number of paths exceeded for source VM

14 - Maximum number of paths exceeded for target VM

15 - Connection not authorized

16 - Invalid IUCV system service name

18 - msglim > 255

After this operation you should do an ACCEPT (or SEVER) operation on the IUCVPATH key.

Returned string:

source_vmname - The name of the VM issuing the connect request

flags - As follows:

X'20' - This virtual machine may receive priority messages on this path.

X'40' - Path is initially quiesced

X'80' - Data may be sent in the parameter list

msglim - Maximum number of outstanding messages that the connecting virtual machine may send on the path

userdata - User data sent by connector

Return codes:
0 - pending connection returned

1 - there are no pending IUCV connections

Return Codes:
c is the maximum number of permitted paths

Return Codes:
c is the allocated message ID.

vmcv-parameter-list - The parameter list used with the function

S - Required only on the VMCF AUTHORIZE operation. The segment that will contain the VMCF message data (i.e. the virtual machine's real memory segment).

Return Codes:

0 to 20 - As defined by IBM for VMCF

Implementation Notes:
Message reject - X'FFFE'
This operation is unique to KeyKOS. It indicates that the receiving virtual machine has performed an unauthorize function before an interrupt could be reflected. The sender should get error code X'05' for this message.

Identify response - X'FFFF'
This operation is unique to KeyKOS. It indicates that the external interrupt for an identify operation has been reflected to the virtual machine. It is implemented in the group by sending an Identify Response message to the CPGCOMM key of the originator of the identify so his outstanding operation count can be decremented.

AUTHORIZE - X'0000'
N.B. Authorize overrides a previous authorize.

CP simulator saves address of buffer & length. Gives rc=1,2,6.

VMGROUP saves the 3 flags, the specific username authorized (if applicable), and the length of buffer.

UNAUTHORIZE - X'0001'
CP simulator forgets authorization

VMGROUP forgets authorization, destroys any VMCF path objects connected to this virtual machine. (Pending sends to that VM must get rc=5).

SEND - X'0002'
CP simulator passes it on. Gives rc=2,4,10.

VMGROUP implements it.

SEND/RECV - X'0003'
CP simulator passes it on. Gives rc=2,4,10.

VMGROUP implements it.

SENDX - X'0004'
CP simulator passes it on. Gives rc=2,4,10. N.B. The receiveing CP simulator will do a receive operation for the data so the group may treat SENDX as if it were a SEND.

VMGROUP implements it.

RECEIVE - X'0005'
CP simulator passes it on. Gives rc=2,4,13.

VMGROUP implements it. N.B. group recognizes overlap (rc=17).

CANCEL - X'0006'
CP simulator passes it on. Gives rc=2,4.

VMGROUP implements it.

REPLY - X'0007'
CP simulator passes it on. Gives rc=2,4,13.

VMGROUP implements it. N.B. group recognizes overlap (rc=17).

QUIESCE - X'0008'
CP simulator passes it on. Gives rc=2,4.

VMGROUP implements it.

RESUME - X'0009'
CP simulator passes it on. Gives rc=2,4.

VMGROUP implements it.

IDENTIFY - X'000A'
CP simulator passes it on. Gives rc=2,4,10.

VMGROUP implements it.

REJECT - X'000B'
CP simulator passes it on. Gives rc=2,4,13.

VMGROUP implements it.

vmname is the name of the virtual machine to receive the message, message is the message in EBCDIC.

Return Codes:

0 - Message sent.

45 - vmname not logged on (not joined).

57 - Not receiveing, edata specifies why.

Return Codes:
0 - Name is in group

1 - Name is not in group

spooldata - The CP simulator spool file header data
(8,distributioncode) - CP distribution code

(8,ownerid) - userid to queue file for

(8,creatorid) - userid of the file's creator

(8,formname) - Printer form name

(8,tod) - Time of file creation

- The name given to the spool file

(4,recordcount) - The number of records in the file

(2,spoolid) - Sender's spoolid 1-9900.

(2,maxrecord) - The length of the longest record

(1,class) - The CP spool class for this file

(1,copycount) - Number of copies to print (1-255)

(1,type) - The type of the file

0 - Console file

1 - Punch file

2 - Printer file

(1,flags) - Bit switches for file:
X'80' - File is in HOLD status

- The tag data associated with the spool file

S - The segment that contains the spool file

Return Codes:

0 - Name is in group

1 - Name is not in group, file has not been sent

The file S is a "file transfer segment" and has a hex 41 preceeding each record (at least if produced by the virtual punch).

Return Codes:

0 - Spool file returned
spooldata - The CP simulator spool file header data {(spooldata)}, 212 bytes - Note that the "ownerid" is the userid of the "transfer from" virtual machine.

S - The segment that contains the spool file

1 - No spool files queued
spooldata - Is the null string, S is DK0

Internal Logic

Each VMCOMM object consists of three domains. The VMCOMM domain impliments the VMCOMM key and is prompt. The queue domain is called by VMCOMM domains to queue information for the CP simulator and is prompt. The notify domain works off the queue and is responsible for calling the CP Simulator Group Communication Key. (It is not prompt.)

Order code 0: If there is a CP simulator Group Communication key in the group record collection which is not DK0, return code 1 is returned. Otherwise the key passed is stored in the record collection and return code 0 + the user name are returned.

Order code 1: The tod stamp and the "MESSAGE FROM <uid >: " header are placed on the message and the result is passed to the queue domain of the reciepent's VMCOMM object where it is queued for the notifier domain. The return code and data from the queue domain are returned to the caller.