1 0 Ref. C2 0 THE VMCF PACKAGE (Ref. C2) + ___ ____ _______ ___ __ 0 Version 8 + _______ _ 0 8 March 1982 + _ _____ ____ 0 P M Girard + _ _ ______ 0 1. Introduction + ____________ 0 This paper supersedes the paper called "The MVT/VMCF Package and User Interface", and should be read in conjunction with the same Version number of "A Protocol for Using VMCF" (Ref. A2). 0 If the package is used via IPC (Ref. C1), no detailed knowledge of the contents of this paper is required. 0 The package aims to support those features of the IBM VMCF (Ref. M3) used or allowed by the protocol, with the further restriction that SEND/RECV and REPLY are not supported. Thus the package accepts SENDX, IDENTIFY, SEND, RECEIVE and REJECT, in the forms allowed by the protocol. 0 Both ends of a connection may be in the same virtual machine, so references to the "other end" should be understood to include this possibility. 0 Although written originally for the RAL MVT system as a resident nucleus module, the package has been run unaltered in a CMS environment. It should likewise be usable under other virtual machine operating systems, if some simple interfacing routines are provided. - 2. VMCF AUTHORISE + ____ _________ 0 At RAL, the MVT virtual machine AUTHORISES itself for VMCF during HASP initialisation, by calling the package with a special password and stating the maximum number of Sub- Functions required. Under CMS, an initialisation routine is provided, which makes this initial call to the package. - 3. "Functions" and "Sub-Functions" + _________ ___ ___ _________ 0 In the MVT or CMS context, the Caller or Listener "Addressing" referred to in the protocol definition is composed of a Function name and a Sub-Function name. Under MVT, the Function name is the OS Job Name as held in - THE VMCF PACKAGE PAGE 1 1 0 Ref. C2 0 the TIOT. Under CMS, a dummy TCB and TIOT are used, simulating the MVT equivalents, and an arbitrary Function name is held in the TIOT. The interfacing routine, SVC242, communicates this information to the package. The Sub-Function name is any 8-byte name chosen to represent something in the user's software (a 'process' or subtask perhaps). Each Sub-Function has its own control block, and there are facilities for clearing down globally all the connections belonging to a known Sub-Function. - 4. Communication with the Package + _____________ ____ ___ _______ 0 The package is used by calling SVC 242 in the MVT case, or via the SVC242 interfacing routine in the CMS case, with VMCF-like parameter areas (VMCPARM) pointed to by R1. A reply is returned in R15. A password is required in R0, so that the package can protect itself against stray calls. Apart from standard VMCF messages, some new procedures (DECLARE, SCRAP, OPEN, CLOSE) have been introduced. These are for consumption by the package, not by VMCF itself. - 5. DECLARE + _______ 0 A Sub-Function must first DECLARE itself, giving its Sub- Function name, the number of connection slots it requires, and optionally an LCCB size. The minimum LCCB size is 92 bytes including 48 bytes for addressing and an SCCB of 16 bytes (2 sub-channels). If a larger SCCB is needed, the package will normally getmain extra space as necessary, but this can be avoided if preferred by specifying a large enough LCCB at DECLARE time. 0 VMCPARM for DECLARE: + _______ ___ _______ VMCPFUNC : X'001D' VMCPVADA/LENA : Sub-Function Name VMCPVADB : Bits 0-15 : Zeros (or LCCB size) Bits 16-31 : No. of slots 0 Registers: R0 = 'VMCF'; R1 = VMCPARM address. On exit, + _________ R15=0 if successful or negative if unsuccessful. - 6. SCRAP + _____ 0 A complete Sub-Function can be scrapped, causing the package to close all its connections and release its control blocks. If VMCPVADA/LENA is set to blanks, all - THE VMCF PACKAGE PAGE 2 1 0 Ref. C2 0 Sub-Functions declared under the current TCB or dummy TCB will be scrapped. Where the closure of connections involves telling the other end to disconnect, this is done using GLOBAL DISCONNECT messages containing the supplied Reason code and user-defined data. 0 VMCPARM for SCRAP: + _______ ___ _____ VMCPFUNC : X'001C' VMCPMID : Bits 0-21 : Zeros Bits 22-25 : Reason code Bits 26-31 : Zeros VMCPVADA/LENA : Sub-Function Name (or blanks) VMCPUSE : Bits 0-31 : Zeros Bits 32-63 : User-defined data 0 Registers: R0 = 'VMCF'; R1 = VMCPARM address. On exit, + _________ R15=0 always. - 7. OPEN + ____ 0 When the Sub-Function has been DECLAREd, a pool of connection slots is available for use. To secure a slot for a particular connection, the user must issue an OPEN. This sets up a Logical Channel Control Block (LCCB) in the user's region but (under MVT) in protected storage (subpool 252). Associated with this is a Sub-channel Control Block (SCCB) with an entry for every sub-channel, but the SCCB may not be actually created until ACCEPT time. 0 The user may or may not decide to listen on a given slot. Even if listening is specified, the user may subsequently send out a CONNECT message, in which case the listening status is immediately cancelled; however, if this is done, there is some risk of a missed connection if the other end simultaneously sends a CONNECT. When a connection has been established, the end which sent the effective CONNECT is defined to be the "caller" on that connection, and the end which responded to it with ACCEPT is defined to be the "listener", regardless of the initial listen/nolisten specification at OPEN time. This is an important point in relation to sub-channel usage (see Section 9 below). 0 VMCPARM for OPEN: + _______ ___ ____ VMCPFUNC : X'001E' VMCPMID : Bits 0-4 : Reserved.Must be zero. Bit 5 : 0 = Record mode SEND : 1 = Stream mode SEND Bit 6 : 0 = Single ECB mode : 1 = Multiple ECB mode Bit 7 : 0 = No listen : 1 = Listen Bits 8-31 : Address of primary ECB - THE VMCF PACKAGE PAGE 3 1 0 Ref. C2 0 VMCPUSER : Other end's USERID (or blanks) VMCPVADA/LENA : Sub-Function Name VMCPVADB/LENB : Addressing (for listening) VMCPUSE : Addressing (for listening) VMCPXTRA : Addressing (for listening) VMCPXTR2 : Addressing (for listening) 0 Registers: R0='VMCF'; R1 = VMCPARM address. On exit, R15 + _________ = LCCB address if successful, negative if not successful. If successful, a Local LCN is also passed to the user in the top 22 bits of R1, the last 10 bits being zero. 0 If 'record mode SEND' is specified, a SEND issued by this end will complete even if a RECEIVE by the other end takes less than the number of bytes offered. If 'stream mode SEND' is specified, a SEND issued by this end will not complete until the residual count has reached zero, unless a REJECT or a VMCF error is returned at some stage. 0 If 'single ECB mode' is specified, only one ECB is used, referred to as the 'primary ECB'. If 'multiple ECB mode' is specified, the user must supply at CONNECT or ACCEPT time a pointer to a list of additional ECB addresses, one for each sub-channel. Once the connection has been fully established (i.e: has reached State 4), these ECBs are posted rather than the primary ECB supplied at OPEN time. 0 The other end's USERID is needed only when listening. If listening for a CONNECT from an unknown virtual machine, the field must be set to blanks. 0 When listening, the package will match individually the four 8-byte Addressing fields in the OPEN with the Caller and Application Addressing fields in an incoming CONNECT. Fields set wholly to blanks in the OPEN will be accepted without matching. If matching is successful, the fields from the CONNECT will be deposited in an area pointed to by the LCCB for the user's further inspection, and the primary ECB will be posted. - 8. CLOSE + _____ 0 This releases a connection slot back to the pool, after sending a DISCONNECT message if necessary. There is no point in the user sending an explicit DISCONNECT message, because a disconnected slot cannot be re-used until it has been closed. If closure involves sending a DISCONNECT message, this will contain the supplied Reason code and user-defined data. 0 VMCPARM for CLOSE: + _______ ___ _____ VMCPFUNC : X'001F' - THE VMCF PACKAGE PAGE 4 1 0 Ref. C2 0 VMCPMID : Bits 0-21 : Zeros Bits 22-25 : Reason code Bits 26-31 : Zeros VMCPUSE : Bits 0-31 : Zeros Bits 32-63 : User-defined data 0 Registers: R0 = 'VMCF'; R15 = Local LCN assigned at OPEN + _________ time in top 22 bits, last 10 bits being zero. - 9. Issuing Standard VMCF Messages (including CONNECT, etc) + _______ ________ ____ ________ _________ _______ ___ 0 To issue VMCF messages, the user must set up a VMCPARM and call the package with R1 pointing to it. The Local LCN assigned at OPEN time, and some sub-channel information where appropriate, must be provided in R15. The user is not expected to supply information already known to the package, such as userids (except with CONNECT), Labels and LCNs. Such fields are not checked, and the package will overwrite them with its own information (in its own copy of the user's VMCPARM area). The Caller Addressing fields in a CONNECT and the Listener Addressing fields in an ACCEPT are also inserted automatically by the package, but the buffer address must be valid. See below for details of the VMCPARM area and register contents. 0 Where the user specifies a buffer that is taken asynchronously by VMCF (as for instance in SEND messages), the user must not overwrite the buffer while the operation is still pending in VMCF. However, in the case of CONNECT and ACCEPT messages, the package will copy the addressing information into its own storage, so the original buffer can be re-used immediately if required. 0 Sub-channels must be used in pairs, each sub-channel carrying data in one direction only. The "caller" must use even-numbered sub-channels (0, 2, etc) for transmitting data, and odd-numbered sub-channels for receiving it. The "listener" must of course do the opposite. Data must be transmitted using SEND and either taken using RECEIVE or refused using REJECT. 0 The number of sub-channels is determined by the smaller of the two numbers proposed at CONNECT and ACCEPT time respectively. A zero value must not be proposed by either end. 0 The LCCB State is 1 immediately following an OPEN. The State becomes 2 if a CONNECT is sent or received, 4 if an ACCEPT is sent or received, and 5 if a DISCONNECT is sent or received. The package will ensure that the use of these messages conforms to the protocol. - THE VMCF PACKAGE PAGE 5 1 0 Ref. C2 0 An unsuccessful message (R15 non-zero) has no effect on the LCCB State or other control block contents. 0 VMCPARM for CONNECT or ACCEPT: + _______ ___ _______ __ ______ VMCPFUNC : X'0004' VMCPMID : Pointer to secondary ECB list (multiple ECB mode only) VMCPUSER : Other end's userid (needed only for CONNECT) VMCPVADA/LENA : Address / length of Addressing VMCPVADB : Type code (1 or 2) VMCPUSE : Bits 32-63 : User-defined data 0 VMCPARM for other VMCF Messages + _______ ___ _____ ____ ________ VMCPFUNC : As defined for VMCF VMCPVADA/LENA : As defined for VMCF VMCPUSE : Bits 32-63 : User-defined data 0 The VMCPARM for DISCONNECT is not given, as the user can more usefully issue a CLOSE. GLOBAL DISCONNECT is discussed separately in a later section. 0 Registers: R0 = 'VMCF'; R1 = VMCPARM address; R15 = Local + _________ LCN assigned at OPEN time in top 22 bits, with sub-channel number in the last 10 bits if appropriate. In the case of CONNECT and ACCEPT, the last 10 bits of R15 must contain the number of sub-channels (counting from 1). On exit, R15 = 0 if successful; non-zero if unsuccessful (positive error codes come from VMCF itself). - 10. Interrupts from VMCF + __________ ____ ____ 0 The user's ECB or ECBs are posted and information is deposited in the LCCB or SCCB. The user must look at the relevant parts of the LCCB and SCCB to see what there is to do, but should not attempt to alter anything there. The package will clear the top byte of the appropriate SCCB entry whenever the user issues a VMCF message (SEND, RECEIVE, etc) to that sub-channel, and will guarantee not to deliver more than one interrupt to it following such a VMCF message. Information from CONNECT, ACCEPT and DISCONNECT interrupts goes into the LCCB itself. Information relating to specific sub-channels goes into the appropriate SCCB entry. 0 The SCCB is separately getmained if there is not room for it in the LCCB. 0 Action on particular interrupts is as follows: - - THE VMCF PACKAGE PAGE 6 1 0 Ref. C2 0 An incoming CONNECT, when matched, sets LCCB State=2, deposits 32 bytes of Addressing in an area pointed to by the LCCB and posts the primary ECB. The last 32 bits of VMCMUSE are also deposited in the LCCB User Data field. The package remembers the first 16 bytes of the Addressing. 0 An incoming ACCEPT sets LCCB State=4, causes the SCCB to be initialised, and posts the primary ECB. The first 16 bytes of Addressing is remembered by the package, and the last 32 bits of VMCMUSE are deposited in the LCCB. The package does not support the transfer of more than 16 bytes of Application-level Addressing. 0 An incoming DISCONNECT sets LCCB State=5. It normally posts the primary ECB, but if the LCCB State is 4 and multiple ECB mode is in use, it posts all the secondary ECBs instead. The user must CLOSE the connection before it can be re-used. The Reason code and the last 32 bits of VMCMUSE are deposited in the LCCB. A DISCONNECT may arrive at any time, but once the LCCB has gone into State 5, no further interrupts will be delivered. It should be noted that an LCCB in State 5 may or may not have an associated SCCB, depending on the State it had reached before it was disconnected. 0 An incoming SEND interrupt deposits V*1, V*2 and the message length in the correct SCCB entry and posts either the primary ECB (in single ECB mode), or the appropriate secondary ECB (in multiple ECB mode). The last bit of the first byte is always set on, to ensure that the SCCB entry cannot remain zero when posted. Only the first byte of the SCCB should be tested to see whether an interrupt has occurred. The LCCB State will be 4 (or 5 if a DISCONNECT is also delivered). The last 32 bits of VMCMUSE are also deposited as User Data. 0 An incoming SEND Response interrupt is similar, except that the length deposited is the residual data length from VMCMLENA. If 'stream mode SEND' was specified, the package will automatically issue another SEND for the residue if there is any, and the user will not be notified until the count becomes zero unless a VMCF error or a REJECT is returned. 0 An incoming SENDX Response interrupt is discarded by the package, unless it contains a VMCF error code. If an error code is present, the code is deposited in the first byte of LCCBUSE (with top bit set on to distinguish it from an error of the same type at the other end); the appropriate Reason code is put into the LCCB, the LCCB State is set to 5, and the user's ECB or ECBs are posted; if the SENDX was an ACCEPT, a DISCONNECT is also sent to the other end. - THE VMCF PACKAGE PAGE 7 1 0 Ref. C2 - 0 11. Use of GLOBAL DISCONNECT Messages + ___ __ ______ __________ ________ 0 The user may send a GLOBAL DISCONNECT at any time, specifying the other end's userid, a Reason code, a local Sub-Function name in VMCPVADB/LENB, and optionally some user-defined data in the second half of VMCPUSE. The package will insert a Label and put the user's jobname in VMCPVADA/LENA. Programs running in key zero may specify blanks in VMCPVADB/LENB, in which case the package will insert blanks in VMCPVADA/LENA also. 0 It is not necessary for any Sub-Functions to be actually in use at the time of issue, and indeed the main purpose of GLOBAL DISCONNECT is to provide a means of ensuring that the other end is starting from scratch, with no un- cleared slots left over from a previous loading of the virtual machine at this end. However, if there are any + ___ un-disconnected local slots covered by the GLOBAL DISCONNECT, each LCCB affected will be put into State 5, the Reason code and User Data from the GLOBAL DISCONNECT will be deposited in the LCCB, and the post bit in the user's ECB or ECBs will be set. The user must still issue CLOSE or SCRAP to free the slots for re-use. 0 On receipt of a GLOBAL DISCONNECT from another virtual machine, the package will locate all the relevant control blocks, and treat them as if an individual DISCONNECT had arrived for each one. It should be noted that this does not CLOSE any slots or SCRAP any Sub-Functions; as usual, only the user can perform those operations. - 12. Task Termination under MVT + ____ ___________ _____ ___ 0 A trap in an early load of ABEND will detect abnormal termination of a task or subtask, and SCRAP all its Sub- Functions. If a task or subtask tries to terminate normally, while still holding some Sub-Functions, an ABEND D03 will occur. - - - - 0 THE VMCF PACKAGE PAGE 8 1 0 Ref. C2 0 13. LCCB Format + ____ ______ 0 Word 0 : Bit 0 : Always zero in a valid LCCB Bits 1-3 : LCCB State (1,2,4 or 5) Bit 4 : Reserved Bit 5 : 0 = record mode SEND 1 = stream mode SEND Bit 6 : 0 = single ECB mode 1 = multiple ECB mode Bit 7 : 0 = this end is caller 1 = this end is listener Bits 8-31 : Address of primary ECB Words 1,2 : Other end's userid Word 3 : Bits 0-21 : Other end's LCN Bits 22-31 : Reason code (State 5 only) Word 4 : Bits 0-21 : Caller's Label Bits 22-31 : No. of sub-channels (counting from 1) Word 5 : Bit 0 : 0 = SCCB not getmained 1 = SCCB getmained Bit 1 : 0 = SCCB does not exist 1 = SCCB exists Bits 2-7 : Reserved Bits 8-31 : Address of Addressing (States 1,2) Address of SCCB (When SCCB exists) Word 6 : User data from VMCMUSE + 4 Words 7ff : Workspace. Addressing areas and SCCB entries may be located here, but should be accessed normally via the pointer in Word 5, in case the LCCB is extended later. - 14. SCCB Format + ____ ______ 0 Two words per sub-channel. Byte 0 of Word 0 becomes non-zero when an interrupt for this sub-channel is delivered. Contents when posted are: 0 Word 0 : Byte 0 : V*1 (with X'01' bit added) Byte 1 : V*2 Bytes 3,4 : Length from VMCMLENA Word 1 : User data from VMCMUSE + 4 (single ECB mode) 0 In multiple ECB mode, the first byte of User Data goes into the first byte of Word 1, the rest into the last 3 bytes of the ECB itself. - - 0 THE VMCF PACKAGE PAGE 9 1 0 Ref. C2 0 15. Acknowledgements + ________________ 0 Many of the ideas incorporated in this paper were contributed by Chris Cooper, Margaret Curtis, Alan Mayhook and Steve Tunstall in the course of a number of discussions. - 16. References + __________ 0 A2: A Protocol for Using VMCF (P M Girard) 0 C1: Inter-Process Communications Package (IPC) (P M Girard) 0 M3: IBM VM/370 System Programmers Guide (IBM) - - - - - - - - - - - - - 0 THE VMCF PACKAGE PAGE 10 1 0 Ref. C2 0 APPENDIX 1 + ________ _ 0 Error Codes: + _____ _____ 0 >0 : See VMCF documentation 0 : Success -1 : Bad password or machine not authorised -2 : Unsupported VMCF operation -3 : Too many Sub-Functions DECLARED Sub-Function not known (OPEN) -4 : Sub-Function already exists (DECLARE) No free connection slots (OPEN) -5 : Bad ECB address (OPEN, CONNECT, ACCEPT)) Unknown LCN (VMCF operations, CLOSE) -6 : Violation of protocol -7 : Wrong sub-channel no. (SEND, RECEIVE, REJECT) -8 : Bad VMCPARM address -9 : Bad VMCPARM contents -10 : Connection not in State 4 (SEND, RECEIVE, REJECT) - Disconnection Reason codes: + _____________ ______ _____ 0-9 : User-defined 10-11 : Reserved for package 12 : SENDX data transfer error (first byte of User Data field contains VMCF code) 13 : OS task or subtask has terminated 14 : Unacceptable Label 15 : Incoming CONNECT not matched - REJECT issued by package: + ______ ______ __ _______ 0 This happens if a SEND/RECV comes in, or a SEND arrives which cannot be delivered. A code is placed in bits 32-39 of the User Doubleword: 0 X'FB': Connection closed with a SEND pending. X'FC' : SEND received on wrong sub-channel X'FD' : SEND received in wrong LCCB State X'FE' : SEND invalid or unrecognised X'FF' : SEND/RECV received - - - - 0 THE VMCF PACKAGE PAGE 11 1 0 Ref. C2 0 APPENDIX 2 + ________ _ 0 Some information is collected here about the internal organisation of the package, but none of this is needed by the user. 0 When the package issues the VMCF AUTHORISE, it creates a VMCF control block (VMCB) in System Queue Space (under MVT), with enough room to hold entries for a fixed number of Sub-Functions. The format of the VMCB is as follows: 0 HEADER SECTION + ______ _______ Word 0 : Byte 0 : X'80' Bytes 1-3 : Pointer to 1st free entry Word 1 : Bytes 0-1 : No. of VMCB entries Bytes 2-3 : Length of each entry 0 EACH ENTRY: + ____ _____ Word 0 : Bit 0 : 0 = Entry not on free queue : 1 = Entry is on free queue Bits 1-7 : Zeros Bits 8-31 : Address of next free entry (if bit 0 = 1) Address of SFCB (if bit 0 = 0) Word 1 : Address of user's TCB Words 2,3 : Sub-Function name (8 bytes) 0 When a Sub-Function is DECLARED, the package acquires a free VMCB entry for it. It also getmains some space for a Sub-Function Control Block (SFCB), in the user's region but (under MVT) in protected storage (subpool 252). If a Sub-Function is later SCRAPPED, the SFCB is freemained and the VMCB entry is released. 0 Each entry in an SFCB is called a Logical Channel Control Block (LCCB), and the format of this, with its associated SCCB, is given in the main part of the paper. 0 The format of an SFCB is as follows: 0 HEADER SECTION: + ______ _______ Word 0 : Byte 0 : X'80' Bytes 1-3 : Pointer to 1st free entry Word 1 : Bytes 0-1 : Number of SFCB entries Bytes 2-3 : Length of each entry 0 EACH ENTRY: + ____ _____ Word 0 : Bit 0 : 0 = Entry not on free queue 1 = Entry is on free queue Bits 1-31 : Address of next free entry (if bit 0 = 1) As defined for LCCB (if bit 0 = 0) - THE VMCF PACKAGE PAGE 12 1 0 Ref. C2 0 Words 1 ff: See LCCB format given in body of paper. - Labels are assigned by deriving the first Label from the clock, and thereafter incrementing this by one for every connection attempt. 0 LCNs, 22 bits long, are constructed as follows: 0 Bits 0-7 : VMCB entry no. (counting from 1) Bits 8-21 : SFCB entry no. (counting from 0) 0 Under MVT, the package itself comprises a new module called IEAVMCF, about 5K in length, and a slightly modified IEADDP00, both linked into the nucleus. On SYS1.SVCLIB, the module IGC0101C (UCLA EXCHANGE version) has been modified to deal with the VMCF aspects of abends. A change is also required in HASPINIT to make the initial call to SVC 242 to initialise the package. The IEAVMCF module contains SVC 242 itself (a Type 1 SVC), and also the bulk of the external interrupt handler extensions and abend processing. 0 Under CMS, the IEAVMCF module is identical to the MVT version. An initialisation routine is provided with it. There is also a general interfacing routine, SVC242, which provides a dummy CVT, TCB and TIOT, and simulates the normal interface to an SVC. Finally, there is an external interrupt handler which detects VMCF interrupts and passes control to IEAVMCF as necessary. - - - - - - - - - THE VMCF PACKAGE PAGE 13