1 0 Ref. A3 - THE APPLICATION/NCP PROTOCOL USING VMCF (Ref. A3) + ___ ___________ ___ ________ _____ ____ ___ __ 0 Version 5 + _______ _ 0 8 March 1982 + _ _____ ____ 0 P M Girard + _ _ ______ 1. Introduction + ____________ 0 This supersedes the paper called "The Application/NCP Interface via VMCF", whose name was a source of confusion. 0 Ref. A2 describes a general protocol for communicating between two virtual machines using VMCF. Communication between an Application virtual machine and NCP is a particular case of this, and uses a subset of the general protocol. The purpose of this paper is to specify the subset. 0 It is important in practice that implementors of Applications virtual machines should not write new software to drive this protocol. They should use the software described in the Transport Service paper (Ref. D1). The only parts of the present paper directly relevant to implementors are Sections 6 and 9, which give information about Sub-Function names and the formats of the control records used by the Transport Service. - 2. Use of Subchannels + ___ __ ___________ 0 Except for certain special applications such as VNET and BOOTSTRP, four subchannels are needed for each connection. Subchannels 0 and 1 are for application-level data, and subchannels 2 and 3 are for 'Transport Service' control records. The conventions for using these subchannels are described in Section 4 of Ref. A2. - 3. The VMCF 'PUSH' Signal + ___ ____ ____ ______ 0 In a VMCF SEND operation on the data subchannels, the last bit of the "user-defined data" field is defined to have the following meaning: 0 0 = there is a PUSH signal on the end of the data. 1 = there is no PUSH signal on the end of the data. 0 If the receiving end does not take the whole of the data, the sender should assume that the receiver has not yet reached the PUSH signal (if present), and should therefore repeat it if appropriate in the next transmission. The receiving end must pass back the "user-defined data" field - THE APPLICATION/NCP PROTOCOL USING VMCF PAGE 1 1 0 Ref. A3 0 as it stands, when issuing the RECEIVE. 0 If the whole of the data is not taken, a VMCF code 16 is signalled to the receiver in the DIAGNOSE return code, and to the sender in the response interrupt header. The sender also has access to a residual count in this case. 0 If the application pushes every SEND operation (but not otherwise), it can be sure that NCP will be willing to take up to a packet-full of data per RECEIVE operation. 0 The VMCF PUSH facility provides the underlying mechanism for conveying Transport Service PUSH signals across the Application/NCP interface. - 4. The VMCF 'SPECIAL' Signal + ___ ____ _______ ______ 0 In a VMCF SEND operation on the data subchannels, the last-but-one bit of the "user-defined data" field is defined to have the following meaning: 0 0 = this is "ordinary" data. 1 = this is "special" data. 0 The VMCF 'SPECIAL' facility provides the underlying mechanism for conveying Transport Service ADDRESS messages across the Application/NCP interface. In the case of 'SPECIAL' data, the VMCF PUSH bit is always set to zero, implying that it is always pushed, as far as the Application/NCP interface is concerned; however, this does not imply a Transport Service PUSH, as the latter is in this case indicated or not by the presence or absence of a zero byte on the end of the ADDRESS message itself. - 5. Call Addressing + ____ __________ 0 The addressing fields in a VMCF CONNECT sent by the application must be set up as follows: 0 Listener addressing : bytes 0- 7 : blanks bytes 8-15 : 'C ' Caller addressing : bytes 0- 7 : Any fixed name (always the same) bytes 8-15 : A 'Sub-Function name', which will be incorporated in the network "calling address" by NCP. This should conform to the pattern desribed in Section 6. Application addressing : 16 blanks 0 In the RAL IBM, the userid of the NCP virtual machine is - THE APPLICATION/NCP PROTOCOL USING VMCF PAGE 2 1 0 Ref. A3 0 'VMNCP ' for the CMS version, and 'FEM ' for the MVT version. - For an incoming call, NCP will set up the addressing fields as follows in the VMCF CONNECT:- 0 Listener addressing : bytes 0- 7 : blanks bytes 8-15 : A 'Sub-Function name', conforming to the pattern described in the next Section. This will have been part of the "called address" received in the network Call Request packet. Caller addressing : bytes 0- 7 : arbitrary bytes 8-15 : 'L ' Application addressing : 16 blanks - When sending a VMCF ACCEPT, the addressing fields should be as follows: 0 Listener addressing : bytes 0- 7 : A fixed name, (the same name as used in CONNECTs) bytes 8-15 : 'Sub-Function name' Application addressing : 32 blanks - 6. 'Sub-Function Names' + ___ ________ _____ 0 The 'Sub-Function name' quoted in the VMCF CONNECT addressing fields forms part of the network address and must be constructed as follows (asterisks denote optional extra characters): 0 USR***** : Private protocols, test versions, etc FTP** : FTP processes HASP*** : RJE servers (VNET) RSCS*** : RJE servers (VNET) VDEV*** : Test RJE servers (VNET2) ITP* : Terminal servers (via ITP) XXX* : Terminal servers (via XXX) TS29* : Terminal servers (via TS29) BT**** : RJE Bootstrap servers 0 To ensure that there are no connections still hanging in NCP from a previous loading of his software, the user's initialisation procedures should include the transmission to NCP of a 'GLOBAL DISCONNECT' message for each Sub- Function he proposes to use. 'GLOBAL DISCONNECTS' are defined in Ref. A2. The user should specify a reason code in the range 0 to 9, and the addressing fields correspond to those specified as "caller addressing" when sending a - THE APPLICATION/NCP PROTOCOL USING VMCF PAGE 3 1 0 Ref. A3 0 VMCF CONNECT, or "listener addressing" when sending a VMCF ACCEPT. - 7. Virtual Machine Userids in the RAL IBM + _______ _______ _______ __ ___ ___ ___ 0 For an incoming call, NCP must know which virtual machine to contact. Its decision is made as follows. 0 If the call is addressed to USR*****, this name must be followed by a dot and the userid to be contacted. In other words, the caller must supply the userid explicitly. 0 If the call is addressed to FTP**, the userid is assumed to be 'NIFTP '. 0 If the call is addressed to FTP, the userid is assumed to be 'FEM ' (i.e: the MVT system). - 8. Special Applications in the RAL IBM (VNET and BOOTSTRP) + _______ ____________ __ ___ ___ ___ ____ ___ ________ 0 These differ from normal applications, as they have no Transport Service interface and therefore require only 2 subchannels per connection rather than 4. The Transport Service functions are carried out on their behalf by NCP itself. 0 For VNET, NCP sends a VMCF CONNECT to virtual machine userid VNET with addressing fields as follows:- 0 Listener addressing : bytes 0- 7 : 'RSML ' bytes 8-15 : '*** ' (from the Sub-Function name, with leading zeros removed) Caller addressing : bytes 0- 7 : arbitrary bytes 8-15 : 'RSCS ' Application addressing : 16 blanks 0 For VDEV, NCP sends a VMCF CONNECT as described above to virtual machine userid VNET2. 0 For BOOTSTRP calls, the destination virtual machine is BOOTSTRP, and the addressing fields are as follows:- 0 Listener addressing : bytes 0- 7 : blanks bytes 8-15 : 'BT**** ' Caller addressing : bytes 0- 7 : arbitrary bytes 8-15 : 'BOOT ' Application addressing : 16 blanks - - THE APPLICATION/NCP PROTOCOL USING VMCF PAGE 4 1 0 Ref. A3 0 9. Usage of the Control Subchannels + _____ __ ___ _______ ___________ 0 The control subchannels are used for carrying Transport Service control records. Control records always begin with a 9-byte header, following which comes further information depending on the record type. 0 Although the current maximum lengths are as stated, the user should provide a record area of at least 265 bytes for receiving any control records. This allows for a header and full-sized packet, and will avoid incompatibility problems if NCP's Transport Service support is developed further. 0 For the same reason, the application should tolerate but ignore any control record of an unknown type that it may receive. 0 (a) CONNECT Record (maximum length 98 bytes) + _______ ______ 0 Byte 0 : Reserved. Always set to 9 at present Byte 1 : Record type (=1) Byte 2 : Window in/out (4 bits each) Byte 3 : Pktsize in/out (4 bits each) Byte 4 : High Level Protocol (0=private; 1=FTP) Byte 5 : Network protocol (=2 for X25/TS) Bytes 6-8 : Reserved. Always zero at present Bytes 9ff : "Called address" and "calling address" 0 The "called address" and "calling address" are Transport Service addresses, except that the top bit of each length byte is ignored for outgoing calls, and set to zero for incoming calls, each address being assumed to consist of not more than one fragment. 0 For outgoing calls, the "called address" must have a length in the range 1 to 79 bytes, and the "calling address" in the range 0 to 8 bytes. The "called address" may begin with a numeric DTE number or with an alphanumeric 'title', which NCP can look up to obtain the DTE number. The DTE number is then removed, and the rest of the address (maximum 63 bytes) is forwarded transparently as the new "called address". The "calling address", if present, may identify a process within the + ______ calling application. It should be noted that the 'Sub- Function name' is not quoted in the CONNECT record; it is inserted automatically by NCP. 0 For incoming calls, NCP sets up the various bytes in the header. The "called address" will be from 0 to 8 characters long, and if present may identify a process within the application. The "calling address" may be up + ______ to 79 characters long, and may begin with a DTE number or - THE APPLICATION/NCP PROTOCOL USING VMCF PAGE 5 1 0 Ref. A3 0 a 'title'. 0 It should be remembered that the "called address" and "calling address" fields undergo transformations as they pass through the network. - (b) ACCEPT Record (maximum length 12 bytes) + ______ ______ 0 Byte 0 : Reserved. Always 9 at present Byte 1 : Record type (=2) Byte 2 : Window in/out (4 bits each) Byte 3 : Pktsize in/out (4 bits each) Bytes 4-8 : Reserved. Always zero at present Bytes 9ff : "Recall address". Currently must consist of a zero byte only - (c) DISCONNECT Record (maximum length 12 bytes) + __________ ______ 0 Byte 0 : Reserved. Always 9 at present Byte 1 : Record type (=3) Bytes 2-8 : Reserved. Always zero at present Byte 9 : Must be set to 3 at present Byte 10 : Clearing cause Byte 11 : Diagnostic code 0 Outgoing DISCONNECT: The application should set the + ____________________ clearing cause to zero. The diagnostic code should be set to zero for normal clearance, or to an agreed value between X'80' and X'BF' for abnormal clearance. The diagnostic code will go into the X25 Clear Request packet. 0 Incoming DISCONNECT: Bytes 10 and 11 may have come from + ___________________ an incoming X25 Clear Indication packet, or they may have been generated by NCP if it decides to clear down for its own reasons (e.g: bad protocol). In the latter case, byte 10 will be X'40' and byte 11 will be an NCP error code. NCP error codes correspond to diagnostic codes that might have come in from a Clear Indication packet, except that there are some additional ones: 0 X'33' : The line to the network is out of service. 0 X'34' : An outgoing call to an invalid network address was attempted. 0 X'35' : NCP has insufficient resources for more calls. 0 X'36' : Bad address in an ADDRESS message. 0 X'37' : Breach of protocol by the Application. 0 X'39' : An outgoing call to an insuffienctly defined (i.e: - THE APPLICATION/NCP PROTOCOL USING VMCF PAGE 6 1 0 Ref. A3 0 ambiguous) network address was attempted. - (d) INFORMATION Record (length 12 bytes) + ___________ ______ 0 Byte 0 : Reserved. May be 0 or 9 at present. Byte 1 : Type (=4) Bytes 2-8: Reserved. Zero at present. Byte 9 : Reserved. Set to 3 at present. Byte 10 : X'40', implying origin is NCP. Byte 11 : Diagnostic code. 0 This record is defined for use by NCP only, not by the application. The state of the connection is not altered. The diagnostic code may in principle be any of the listed codes, but at present only a breach of protocol by the application should result in an INFORMATION record being sent. - (e) EXPEDITED Record (length 10 bytes) + _________ ______ 0 Byte 0 : Reserved. May be 0 or 9 at present. Byte 1 : Record type (=5) Bytes 2-8 : Reserved. Always zero at present. Byte 9 : Data byte 0 The application may send an EXPEDITED record on its outgoing control subchannel at any time at which it would be valid to send ordinary data. 0 Expedited data will always be transmitted to the network before any subsequently issued ordinary data. 0 An attempt to send more than one data byte in an EXPEDITED record will be treated as a breach of protocol. Having sent an EXPEDITED record, it is also a breach of protocol for the application to send another until it has received, on its incoming control subchannel, an EXPEDITED ACKNOWLEDGEMENT record. 0 If an EXPEDITED message arrives from the network, it will be passed to the application in the form of an EXPEDITED record on the application's incoming control subchannel. Having received this EXPEDITED record, the application can assume that it will not receive another until it has sent back an EXPEDITED ACKNOWLEDGEMENT record on its outgoing control subchannel. It is a breach of protocol for the application to send an EXPEDITED ACKNOWLEDGEMENT record unless it has previously received an EXPEDITED record. 0 The above-mentioned breaches of protocol will cause NCP to return an INFORMATION record to the application, with a diagnostic code of X'37'. If the application commits - THE APPLICATION/NCP PROTOCOL USING VMCF PAGE 7 1 0 Ref. A3 0 multiple breaches of protocol in quick succession, it will not necessarily receive an INFORMATION record for every individual breach. - (e) EXPEDITED ACKNOWLEDGEMENT Record (9 bytes) + _________ _______________ ______ 0 Byte 0 : Reserved. May be 0 or 9 at present. Byte 1 : Type (=6) Bytes 2-8 : Reserved. Always zero at present. 0 The use of this type of record is described in the preceding section. - (g) RESET Records, etc + _____ _______ ___ 0 Further Transport Service functions have yet to be defined in terms of appropriate control records. Record types 7 and 8 are reserved for RESET records. - 10. References + __________ 0 A2: A Protocol for Using VMCF (P M Girard) 0 C1: Inter-process Communications Package (IPC) (P M Girard) 0 C2: The VMCF Package (P M Girard) 0 M3: IBM VM/370 System Programmers Guide (IBM) - - - - - - - - THE APPLICATION/NCP PROTOCOL USING VMCF PAGE 8