1 0 Ref. B3 0 NCP : INTERFACE TO CP/CMS FOR TERMINALS (Ref. B3) + ___ _________ __ __ ___ ___ _________ ___ __ 0 Version 3 + _______ _ 0 8 March 1982 + _ _____ ____ 0 P M Girard + _ _ ______ 1. Introduction + ____________ 0 This paper relates to the VM version of NCP only, as the MVT version no longer supports access to CP/CMS. 0 The interface uses the IBM-supplied Logical Device Support Facility, LDSF, (see Ref. M3), and network terminals are made to look like ASCII devices to the VM control program CP. It was necessary to modify CP's ASCII terminal support to some extent. The code for issuing the necessary LDSF DIAGNOSES and processing the LDSF interrupts is contained in the VMCF Package (Ref. C2), but is documented here rather than in the main paper, as it is logically quite separate. The package was originally designed as a nucleus-resident module for MVT, which accounts for the nature of its interfaces. The entry point SVC242 in NCP corresponds to the use of SVC 242 under MVT. 0 Terminal traffic may be carried over the network using ITP, X29 or TS29 protocols. There need be no visible differences between these as far as a terminal user is concerned, and indeed the selection of the protocol can take place in the user's local software without his knowledge. 0 NCP also contains code to support full screen terminals (using 3270 protocol) via X29 or TS29, but this is currently not available as a service. There are facilities for only one or two ports and the method of carrying the protocol is still under review and likely to change. For these reasons, full screen terminal support is not discussed further in this paper. - 2. Initialisation + ______________ 0 The VMCF Package is entered with password 'AUTH' in R0, and the maximum number of VMCF Sub-Functions in R15. As well as doing the necessary initialisation for VMCF, the Package carries out the following functions for LDSF also. 0 Bit 22 of control register 0 is turned on, and this subsequently stays on permanently. A 'Terminate All' DIAGNOSE is issued to ensure that no logical devices are - NCP : INTERFACE TO CP/CMS FOR TERMINALS PAGE 1 1 0 Ref. B3 0 still tied up from a previous load of the program. A 512-byte area is getmained and filled with zeroes. This area has space for 256 one-byte queue pointers (one for each possible logical device), and 256 associated interrupt code values. The queue control word is zeroed, and so is the word LDSFECB, indicating that NCP has not yet made contact by supplying its ECB address. - 3. External Interrupt Handler + ________ _________ _______ 0 When an LDSF external interrupt (code X'2401' or X'2402') is detected, control is passed to entry point LDSFEXT in the Package. 0 An interrupt is ignored if the system is not running under VM/370, if AUTHFLAG is zero for any other reason, or if LDSFECB is zero, which means that NCP is not in contact. Otherwise an interrupt is queued for NCP and the latter is posted if necessary. 0 Only one interrupt per logical device can be on the queue at any one time, so if CP sends another interrupt while an earlier one is still pending, it merely supersedes the latter on the queue. For instance, CP may validly issue a 'Read', then change its mind and issue a 'Write' or 'Terminate'; in this case the original 'Read' is likely to be ignored completely unless NCP has already begun to process it. If an interrupt supersedes a previous one that is still queued, only the interrupt code value is changed, and NCP is not re-posted. The queue is so constructed and used that no scanning of it is involved at interrupt time, and subsequently only when NCP wishes to take interrupts out of order. The queue will in any case normally be short, as NCP takes the interrupts without delay and stores them internally. - 4. NCP Initialisation + ___ ______________ 0 Until NCP makes initial contact with the Package to start the LDSF interface, the LDSFECB field in the Package remains zero. 0 NCP establishes contact by calling SVC242 with R1 pointing to an ECB. The Package stores this address in LDSFECB, notes NCP's jobname and TCB address, ensures the queue is cleared, and passes back in R1 the address of IEAVMCF2, which contains a table of useful addresses, including that of the Queue Control word. The Package also increments the TCB resource count of NCP, so that (under MVT) NCP - NCP : INTERFACE TO CP/CMS FOR TERMINALS PAGE 2 1 0 Ref. B3 0 could not terminate without going through the special LDSF code in the Abend interface. - 5. NCP Termination + ___ ___________ 0 The ENQ count is decremented and a 'Terminate All' DIAGNOSE is issued. LDSFECB is then cleared. This has the effect of discarding any pending interrupts, whatever stage they may have reached. - 6. Logical Device Initiation + _______ ______ __________ 0 The logical device addresses used by CP are in the range X'4B00' to X'4FFF'. The first byte identifies one of five possible virtual machines, while the second byte allows up to 256 devices per machine. 0 NCP recognises that an incoming call is for CP/CMS by examining the address in the Call Request Packet. It asks the Package to perform an LDSF 'Initiate' function for a new logical device. The device address returned by CP is stored in the field JSLOT in the call record. - 7. Reception of Interrupts by NCP + _________ __ __________ __ ___ 0 Whenever the external interrupt handler queues an interrupt for NCP, it posts the ECB whose address was supplied by NCP during initialisation. 0 When NCP's dispatcher finds this ECB posted, it activates the NCPCMS process. This process clears the ECB and examines the Queue Control word to see if any interrupts are queued. If so, it calls SVC242, which de-queues the top interrupt and passes back its slot number (i.e: the bottom byte of its device address), and the value of the interrupt code. NCPCMS deposits this in the call record of the appropriate NCP call handler process, and puts the latter on the dispatch queue. It then re-examines the Queue Control word to see if any more interrupts are waiting. It will be noted that interrupts are removed from the queue without delay and passed to the relevant process, though the latter may be unable to act upon them for some time. - - 0 NCP : INTERFACE TO CP/CMS FOR TERMINALS PAGE 3 1 0 Ref. B3 0 8. Processing of Interrupts by NCP + __________ __ __________ __ ___ 0 Whenever a call handler process gets control, it tests whether a 'Terminate' interrupt from CP has been deposited in the call record. If so, it ensures that it does not try to use the logical device any more (it may have been already re-assigned by CP), and also clears down the network call. 0 If a 'Write' interrupt is present, NCP asks the Package to ACCEPT the data from CP. To guard against synchronisation loop-holes, the Package at the same time ensures that there is no interrupt for this device on the queue: if there is, it de-queues it. If CP has changed its mind since the call handler was told about the 'Write', this fact will be evident from the return of an error code from the ACCEPT. 0 If the ACCEPT was successful, CP is liable to put out a new 'Write' interrupt immediately, and this will be re- queued by the interrupt handler as soon as the Package returns control. There is therefore a piece of code in NCP immediately after the SVC242 call for ACCEPT, which tests for the arrival of a new interrupt and picks it up immediately if present. In this way, it is possible to pick up successive transmissions from CP and pack them as far as possible in the same network packet. If an ACCEPT fails, this is almost certainly due to the arrival of a new interrupt after the 'Write' was delivered. In this case the Package passes back the new interrupt code at the same time, and NCP re-evaluates the situation. 0 If a 'Read' interrupt is present, NCP sets up the next input message (if any) and asks the Package to PRESENT it to CP. Similar considerations apply to those discussed in the last paragraph: the operation may fail if a later interrupt supervenes, whereas if it succeeds a new interrupt may be already waiting as soon as NCP regains control from the Package. Here again, an attempt is made to process any new interrupt immediately. 0 If two or more Control E characters appear at the front of an incoming message, an 'attention' interrupt to CP is simulated. 0 If an @Y signal comes in from the network, this will + / cause an 'attention' to CP whatever CP may be doing at the time. However, it cannot by-pass normal flow control across the network, and has the disadvantage of throwing away any data that happens to be still in transit at the time, in either direction. - - NCP : INTERFACE TO CP/CMS FOR TERMINALS PAGE 4 1 0 Ref. B3 0 9. Call Termination + ____ ___________ 0 NCP will issue a TERMINATE to CP if a call times out or is cleared by the network. If, however, CP has itself issued a 'Terminate' interrupt, the call handler that was using it must not issue a TERMINATE or communicate in any other way with CP about it: CP may re-assign the device to a new call as soon as its own 'Terminate' interrupt has been delivered to NCP's virtual machine. - 10. References + __________ 0 C2: The VMCF Package (P M Girard) 0 M3: IBM VM/370 System Programmers Guide (IBM) - - - - - - - - - - - - - 0 NCP : INTERFACE TO CP/CMS FOR TERMINALS PAGE 5 1 0 Ref. B3 0 APPENDIX + ________ 0 LDSF Subfunctions in SVC242: + ____ ____________ __ ______ - LDSFSTRT Start NCP to CP Interface + ________ On entry: R15 = 0/anything + ________ R1 = ECB address R0 = 'L'/anything 0 On exit: R15 = 0 :interface started + _______ R15 =-1 : not VM or not Authorised R15 =-2 : Bad subfunction code R1 = address of IEAVMCF2 (if R15=0) - LDSFINIT Initiate a Device + ________ On entry: R15 = 1/anything + ________ R1 = device type details R0 = 'L'/anything 0 On exit: R0 = device address + _______ R15 >= 0 : LDSF reply (cc*256+rc) R15 < 0 : As for LDSFSTRT - LDSFTERM Terminate a Device + ________ On entry: R15 = 4/anything + ________ R1 = anything R0 = 'L'/device address 0 On exit: R15 = LDSF reply (cc*256+rc) + _______ R15 < 0 : As for LDSFSTRT - LDSFTALL Terminate all devices + ________ On entry: R15 = 5/anything + ________ R1 = anything R0 = 'L'/anything 0 On exit: R15 = LDSF reply (cc*256+rc) + _______ R15 < 0 : As for LDSFSTRT - LDSFPRES Present data to CP + ________ On entry: R15 = 3/data length + ________ R1 = mode/data address R0 = 'L'/device address 0 (mode = 0 for data; X'40' for 'attention') (sets top bit of Ry+1 if data) 0 On exit: R15 = LDSF reply (cc*256+rc) + _______ R15 < 0 : As for LDSFSTRT - NCP : INTERFACE TO CP/CMS FOR TERMINALS PAGE 6 1 0 Ref. B3 0 R1 = i/r code if queued. Otherwise 0. - LDSFTAKE Accept data or take top i/r on queue + ________ On entry: R15 = 2/max data length + ________ (or 2/anything if R0 = 'L'/0) R1 = anything/buffer address (undefined if R0 = 'L'/0) R0 = 'L'/device address (accept data) 'L'/0 (take top i/r) 0 On exit: R15 = 0 (if top i/r requested) + _______ R15 = LDSF reply (cc*256+rc) (if data requested) R15 < 0 : As for LDSFSTRT R1 = i/r code if queued. Otherwise 0. R0 = data length actually received (if data requested) or slot no. of top i/r on queue (if R0 = 'L'/0 on entry) - LDSFEND End LDSF interface + _______ On entry: R15 = 6/anything + ________ R0 = 'L'/anything 0 On exit: R15 = LDSF reply (cc*256+rc) + _______ - - - - - - - - - - NCP : INTERFACE TO CP/CMS FOR TERMINALS PAGE 7