1 0 Ref. B2 - NCP : INTERNAL ORGANISATION (Ref. B2) + ___ ________ ____________ ___ __ 0 Version 2 + _______ _ 0 8 March 1982 + _ _____ ____ 0 P M Girard + _ _ ______ 0 1. Introduction + ____________ 0 This paper gives technical information about the internal organisation of NCP at a level appropriate for someone installing, developing or maintaining the software. 0 It is not the intention to produce a blow-by-blow account of the flow of control. Nor would this be particularly useful, as the listings are fairly heavily commented throughout and should be easier to follow than a separate verbal account. However, it can be very helpful to know what a particular routine is trying to achieve, why it goes about this in a certain way, and what some of the important variables are supposed to represent. The present paper aims to provide such information in areas of particular importance. 0 This documentation relates specifically to the new version of NCP (VMNCP) rather than to the MVT version (DKNCP), and the reader should find it useful to consult first the Functional Specification paper (Ref B1) for an overview of the new NCP as seen from outside. - 2. General Structure + _______ _________ 0 NCP is written mainly in FORTRAN, making heavy use of the LOGICAL*1 facilities and fairly heavy use of the bit- manipulation facilities of the IBM FORTRAN H Extended Plus compiler. There are also a significant number of modules in IBM Assembler, including three independent packages which are used by NCP, namely the IPC package, the DEFI package and the VMCF Package. 0 The IPC package provides in effect a mini Operating System under which NCP runs, with the consequence that it makes relatively little use of the IBM Operating System under which the whole is executed. This made it fairly easily transplantable from MVT into CMS under VM. 0 The program is composed of a number of autonomous "processes" running under the dispatcher provided by the IPC package. All processes are dispatched once during program initialisation. Subsequently a process is made - NCP : INTERNAL ORGANISATION PAGE 1 1 0 Ref. B2 0 dispatchable only when an event occurs implying that there may be work for it to do. This may be a timer interrupt, the arrival of an inter-process message, the completion of an I/O operation, or a variety of other conditions supported directly or indirectly by IPC. Processes receive control in the order in which they were made dispatchable, and once a process has control, it cannot lose it to another process until it voluntarily returns to the dispatcher. It may of course lose control to an interrupt handler , which may 'post' another process, but no other process within NCP can actually get control until the original process has finished. IPC also provides all the buffer-handling and buffer-monitoring facilities needed by NCP, and in addition an 'access method' for using the VMCF-based interface between NCP and external applications processes. 0 Ref. C1 contains a full specification of the IPC package, and no attempt will be made to describe it in detail here. 0 There are a number of special purpose processes in NCP, devoted to such activities as handling commands, collecting statistics, and so on, but the majority of the processes can be thought of as belonging to two distinct "levels". These levels correspond to levels 2 and 3 in the ISO 7-Layer Model. Level 4 (Transport Level) exists logically, but not as a separate layer in the implementation. - 3. Level 2 Processes + _____ _ _________ 0 The software supports up to 4 "line driver" processes (it could support up to 8 with some minor changes), each capable of driving one physical line to the network. Currently, the only protocol used at this level is Binary Synchronous, and this is handled entirely by the LMFLOW and LMCALL routines. The coding of LMFLOW may seem unduly complex and obscure: the reason for this is that it was derived from the HASP Line Manager code, which was stripped down to a considerable extent, and made to work in a new context. 0 The 'process type' (3rd byte of the work-space) for a line driver process must be in the range 1 to 4, and corresponds to the logical line number. 0 Under MVT, LMFLOW achieved I/O to the line by setting up a channel program and issuing an EXCP (via IPC, which directly supports asynchronous I/O). Under VM/CMS, EXCP is not supported, so a routine called SVC0 has been incorporated in the IEAVM module of NCP to do the necessary EXCP simulation. No attempt was made to - NCP : INTERNAL ORGANISATION PAGE 2 1 0 Ref. B2 0 simulate EXCP generally; the code is specifically for driving Binary Synchronous lines, and is called only by IPC for this purpose. To avoid altering existing code, OS-type control blocks are retained as far as necessary: each line has a DCB, and when the line becomes active this points to a DEB, which in turn points to a UCB containing the virtual device address. In practice, only one or two fields in these control blocks are needed, and the 'IRQ' control blocks in IEAVM simulate both DEBs and UCBs. Line I/O takes place asynchronously of course, and provision has therefore been made to field the ensuing interrupts. This is done by the DEVINT routine in IEAVM, which stores channel status information in the IOB and posts the ECB of the appropriate line driver process. IPC then ensures that the posting of this ECB causes the line driver process itself to be made dispatchable. 0 For a description of Binary Synchronous protocol as used by NCP, the reader should refer to Ref. A1. - 4. Level 2 to Level 3 Communication + _____ _ __ _____ _ _____________ 0 Each physical line is driven by a separate line driver process, and each network call is driven by a separate "call handler" process. 0 Communication between the levels occurs in several ways: 0 (1) While a call is active, its call handler is associated with a particular line driver by means of entries in a table. Each entry has four half-word elements: 0 LAB : The LCN of the call ITAB : IPC identifier (process no.) of call handler ILMID : IPC identifier (process no.) of line driver CALTYP: Unused (not needed for BSC) 0 Entries are added by GETLAB at call set-up time, and removed by RESIGN when a call is cleared. 0 (2) Network traffic is passed from call handler to line driver and vice versa by the IPC inter-process message mechanism. Such data always comprises a network packet preceded by a two-byte prefix defined as follows: 0 Bits 0-6 : '0010010' Bits 7-15 : Packet length excluding the prefix and the next 3 bytes (maximum 256). 0 A call handler may send any number of such messages to the line driver, and vice versa. In practice of course, network flow control ensures that the number cannot be very large. - NCP : INTERNAL ORGANISATION PAGE 3 1 0 Ref. B2 - If an RNR packet arrives, the call handler can retrieve packets sent to the line driver but not yet taken by the latter. 0 (3) If the line is restarted or drained for any reason, a more immediate form of communication is used to inform all the call handlers with which the line is currently associated. In this case, the line driver notifies every call handler by issuing a CALL I$PCB(5,ID,1) for each. The call handler is immediately aware of such signals as soon as it gets control, and reacts by clearing its call. 0 (4) The LDRIVE bytes in the ICRD common area provide a rudimentary means of communication between an operator and a line driver. There is one byte for each line driver. Its contents may be altered by operator command, and it permits such operations as manually starting or draining a line where appropriate. 0 Packets arriving from the network may be packed several to each BSC block, though hitherto only one packet per block has ever been used. If the packet is an Incoming Call Packet, a new call handler must be "claimed" to which the packet can be sent. This is done by LMCALL. If the packet is of any other type (except RESTART, which is acted upon at once), its LCN is looked up in the table mentioned above, and it is sent to the appropriate call handler. If the LCN is not found, it is assumed that the call no longer exists and the packet is discarded. The LCN assignment algorithms are now PSS-compatible, and a call handler will wait for up to 100 seconds for a Clear Confirmation packet, before closing itself down. - 5. Level 3 Call Handling + _____ _ ____ ________ 0 Each call is handled by a separate call handler process, and the protocol used by the existing software is PSS- compatible X25. There is no logical impediment to the use of more than one Level 3 protocol, and indeed the MVT version of NCP drives both X25 and EPSS calls. 0 There is also a single "outgoing call controller" process (CHMAST), which listens for requests from applications to make outgoing calls. When such a request arrives, CHMAST 'transfers the call' to an ordinary call handler process which it has previously "claimed". There is no need for an "incoming call controller", because the line driver processes themselves can "claim" call handlers for incoming calls. - - NCP : INTERNAL ORGANISATION PAGE 4 1 0 Ref. B2 0 The main routine of the call handler code is CHFLOW. When a particular process has control, its work-space contents will have been copied into the CALREC common area, and it is convenient to refer to this collection of call-related variables as the 'call record'. 0 There are two basic types of call handler, which may be referred to respectively as the "ordinary" type and the "ITP" type. 0 The "ordinary" type is used for everything except incoming terminal calls. The "ITP" type is used for all incoming terminal calls, whether they use ITP, XXX or TS29 protocols. The reason for the difference is that terminal calls do not use a standard Transport Service interface. NCP has to involve itself in higher level processing of these calls and consequently a considerably larger work- space area is needed. An ordinary call handler uses the CALREC variables down to JRNRQ only, plus up to 8 further bytes (IEXTRA array) in some circumstances. An ITP call handler uses the whole CALREC area. Possible values of the 'process type' (IPRTYP) in CALREC are 101 (ordinary call handler), 104 (ITP call handler), and 110 (garbage call handler). The garbage call handler receives calls which cannot be accepted due to lack of available resources; it rejects such calls with appropriate diagnostic codes. - 5. X25 Level 3 Call Handler + ___ _____ _ ____ _______ 0 The state of a call handler is defined principally by the value of the ISTAT variable in CALREC. ISTAT=-1 implies a totally inactive call handler which is free to be assigned to a new incoming or outgoing call. ISTAT=0 means that the call handler has been assigned, but as yet no Call Request or Incoming Call packet has been sent or received. For an incoming call, ISTAT is set to 1 when the call request information (i.e: the CONNECT record) has been queued for transmission to the application. It becomes 4 when the Call Accepted packet has been queued. For an outgoing call, ISTAT becomes 2 when the Call Request packet has been queued for transmission, 3 when the ACCEPT record has been queued for transmission to the application, and 4 when the application has taken this. ISTAT=4 is the normal fully operational state. ISTAT=5 implies that the process wishes to clear itself down and will do so as soon as all oustanding control records destined for the application have been delivered. When process closure can take place, ISTAT=6 is set and the RESIGN routine is eventually called. This ultimately sets ISTAT back to -1. Apart from the states -1 to 6, there are several special states (7 to 12) which can occur only - NCP : INTERNAL ORGANISATION PAGE 5 1 0 Ref. B2 0 in specific contexts (such as waiting for resources to clear a call, or waiting for a Clear Confirmation packet). The application interface is always closed down before waiting for a Clear Confirmation packet, so that no delay will be evident at application level. Precautions are also taken to ensure that a Clear Request or Clear Confirmation is not sent until the process is willing to release its LCN. 0 Preliminary activities: On entry to CHFLOW, some special + ___________ __________ circumstances are tested for. If a call has just been transferred to this call handler by the outgoing call controller (CHMAST), it is necessary to pick up the 'TAG' (or 'Sub-Function name') and call type from the CALREC area, before the latter is re-initialised. Then, if the state was -1 (unless it is the very first entry during NCP initialisation), a new call must be starting, so the 'call record' in CALREC (including ISTAT itself) is cleared to zeros. 0 Start of main loop in CHFLOW: Special precautions (now + _____ __ ____ ____ __ ______ moved into a separate subroutine called CPCHOP) are taken if a CP/CMS call has been terminated by CP or otherwise unexpectedly 'aborted'. This is because CP is liable to re-assign the same device address immediately if another call comes in, and we must ensure that the current call handler cannot go on talking to CP as if it still owned the logical device. This can be adequately achieved by slightly altering the device address so that it is still recognisable to NCP but not to CP. NCP then arranges to cause the network call to be cleared, allowing a delay of a few seconds to avoid overtaking the normal logout messages with the Clear Request packet. (It is not a serious disaster of course if the delay proves inadequate occasionally). In the case of a call using TS29, a Transport Service DISCONNECT is sent, in which case the caller need not be aware of the few seconds delay mentioned above. 0 Except in the above circumstances, the program branches according to the value of ISTAT. If ISTAT is less than 5 (i.e: not yet clearing), 'abort' signals from above (application) or below (line driver) are recognised and cause call clearance processing to begin. If there are no 'abort' signals, or if the state is anything except 5, call timeout is tested for, and if present causes call clearance processing to start. The 'Computed GO TO' covers all other cases. 0 If ISTAT=0, the call is just beginning and must have either been 'transferred' by the outgoing call controller (CHMAST), or be due to an Incoming Call packet from the network. In the former case, the IEXCH flag and the call - NCP : INTERNAL ORGANISATION PAGE 6 1 0 Ref. B2 0 type are stored, and control should normally go to label 3, as there will be no packet from the network to be picked up. If an Incoming Call packet has arrived however, processing of this begins immediately. 0 If ISTAT=4 (normal running state), the process looks first for an incoming packet and processes this, before attempting to deal with output. If ISTAT=5 (waiting to close down), the process ceases to be interested in data in either direction, and concentrates entirely on getting the necessary control information to the application and a Clear Request (or Clear Confirmation) out to the network. The other call states require no special explanation and should be understandable from the listing. 0 Processing of incoming packets: This section of code + __________ __ ________ _______ decides what type of packet has arrived, and whether it should be processed further or treated as an error. An unrecognisable packet will cause call clearance, and so will a Clear Indication packet or (at present) a RESET packet. 0 An Incoming Call packet (if ISTAT=0) causes the subroutine CRPIN2 to be called to analyse it. If it is unacceptable, COPOUT will eventually be called to send a Clear Request packet. Otherwise a 'CONNECT' (='CREATE') record will be set up and queued for sending to the application. Alternatively (for applications having no Transport Service interface), the 'CONNECT' record will be interpreted within NCP itself, causing a suitable 'ACCEPT' record to be generated and fed into COPOUT. If the 'CONNECT' is passed to the application, the latter should eventually pass back an 'ACCEPT' or a 'DISCONNECT'. 0 An incoming Call Connected packet (if ISTAT=2) causes CRPIN2 to be called to look at it. This should cause an 'ACCEPT' record to be set up for passing to the application. 0 An incoming Data, RR or RNR packet will cause the subroutine SUBIN to be called to process it. This processing includes checking of sequence numbers and updating of flow control variables. On return to CHFLOW, the setting of IREP indicates what needs to be done. Normally this is to queue the data for the application, or (if there is no data) to look for more work. 0 Interface to the application: This section of code deals + _________ __ ___ ___________ with the normal 4-subchannel VMCF-based interface to the application. Two subchannels are for data (one in each direction) and two are for Transport Service control records. Each subchannel is handled asynchronously and several subchannels may therefore be carrying information - NCP : INTERNAL ORGANISATION PAGE 7 1 0 Ref. B2 0 at the same time. The receiving subchannels normally sit with an I$MOVE operation pending, and the code merely uses I$CHEK to test whether the application has sent anything. The sending subchannels are used when there is information to send to the application on the data or control queues. When the call handler is in state 5 (waiting to close down), it will not move on to state 6 unless or until the control queue is empty and there is no more control information still waiting to go to the application. 0 Code for calls not using 4-subchannel interface: There + ____ ___ _____ ___ _____ _ __________ _________ are several special applications which do not use the standard interface because of the difficulty of incorporating this in pre-existing application software. 0 Process Timeouts: Before exit from CHFLOW (at label 98), + _______ ________ a timeout is normally set. If the timeout expires before the process has been re-activated for any other reason, NCP assumes that the call can be cleared. The timeout in the normal running state is about 10 minutes for CP/CMS calls and 15 minutes for everything else. 0 Process closure: This can result from various causes, for + _______ _______ instance timeout, application request, line failure or restart, or incoming Clear Indication packet. Essentially, it is necessary to send a Clear Request or Confirmation, to let the application know (unless it originated the closure), and to close down and release the call handler and all associated resources. The RESIGN subroutine is called when there is no further impediment to final closure. - 6. Principal Variables in the Call Record (CALREC) + _________ _________ __ ___ ____ ______ ______ 0 IDPROC: Process number assigned by IPC 0 IPRTYP: Process type: 100 = outgoing call controller 101 = ordinary call handler 104 = 'ITP' call handler 110 = garbage call handler 0 IEWF: Bit settings giving reason for dispatching (see IPC documentation for details) 0 ISTAT: Call state: -1 = not in use 0 = ready for call set-up 1,2,3 = interim set-up states 4 = normal running state 5 = will clear a.s.a.p. 6 = clearing (goes next to -1) >6 = various special states - NCP : INTERNAL ORGANISATION PAGE 8 1 0 Ref. B2 - ICLRA: Not used except by CHMAST before call record is initialised. 0 ICLRB: Non-zero if Clear packet received from network 0 ICOPUT: Non-zero if outgoing call 0 IEXCH : State of application interface: 0 = not using interface (yet) 1 = interface in use -1 = interface has failed 0 ISTRMS(4): Buffer pointers for the PUT, GET, PTC, GTC subchannels of the application interface: Equivalenced to JPUT, JGET, JPTC and JGTC. In call handlers not using the normal application interface, they are used for other purposes,e.g: equivalenced to JPACIN, JPACUT, JMESIN, JMESUT in the ITP routine. A non-zero pointer implies a buffer is held, so RESIGN looks at these variables and frees off the buffers as necessary at process closure time. 0 IR: Used in flow control calculations. Also used as a counter while in state 12, waiting for a Clear Confirmation. 0 ISPR: Used in some places for historical reasons: 0 = not one of the following 16 = call is to VNET (RSCS) 20 = call is to Bootstrap 0 IPTCQ: Head of IPC-maintained queue of control buffers destined for the application. Zero if empty queue. 0 IPUTQ: Head of IPC-maintained queue of data buffers destined for the application. Zero if empty queue. 0 IPCBID: Bits are used individually as follows, all bits being initially zero. 0 0 : On if TS ACCEPT in progress. Used in SUBIN. 0 1 : On if TS ACCEPT parameters complete. Used in SUBIN. 0 2 : On if TS ACCEPT not (any longer) allowed. Used in SUBIN. 0 3 : Incoming calls only: Set by FACIN if window size parameter was present in Facilities. Tested in FACUT. - NCP : INTERNAL ORGANISATION PAGE 9 1 0 Ref. B2 0 4 : CP/CMS incoming calls only: On if message is waiting to go into CP/CMS. Used in ITP routine. 0 5 : Set by SUBIN on receipt of RNR packet. Cleared by SUBIN on receipt of RR packet. Will also be cleared by RESET packet when implemented. Used also by SUBOUT. 0 6 : Set by FAIL3 on receipt of X25 RESTART packet. Used by FAIL2 to avoid sending Clear packets in this case. 0 7 : Waiting for CP/CMS to issue another WRITE ('ascii terminals'). 0 8 : 3270 : 'waiting for read' flag. 0 9 : No longer used 0 10 : No longer used 0 11 : On if continuation of a call level timeout is in progress, if bit 15 is also set 0 12 : 3270 : 'Waiting for ACCEPT' flag. 0 13 : On if the call is internally looped within NCP. 0 14 : No longer used 0 15 : On if a call timeout interval has been set. 0 ILM: Process no. of line driver used by this call 0 IX: Believed to be redundant 0 IY: Sum of maximum window sizes in the two directions 0 IP,IC,IN,IQ: Flow control variables. A description of how these are used is given in an Appendix to this paper. 0 ISEQIN, ISEQUT: Sequence number variables. The field covered by these variables is also equivalenced to an integer variable KKK, which is used as storage space by FAIL2, CHFLOW and SUBIN after the data phase of the call has ended. 0 LLX1, LLX2: Storage for LCN 0 LAX(6): Storage for miscellaneous details 0 IPROT: Protocol ID: 0 = Unclassified - NCP : INTERNAL ORGANISATION PAGE 10 1 0 Ref. B2 0 1 = FTP 2 = VDEV (VNET development) 3 = ITP 6 = VNET (RSCS) 7 = Bootstrap 8 = TS29 9 = XXX 10 = Outgoing terminals 0 JIFLGS: Bits are used individually as follows, all bits being initially zero. 0 0 : Not used 0 1 : Not used 0 2 : Used to signal to SUBOUT that M-bit should be set. Used by MASITP and CHFLOW. Reset by SUBOUT. 0 3 : On if an INTERRUPT packet has arrived and an ITP @Y or a XXX Indication of Break is being + / scanned for. 0 4 : Signal to SUBOUT that Q-bit should be set. Used by ITP, CPCHOP, etc. Reset by SUBOUT. 0 5 : Used by ITP routine to indicate a delay is in force during page wait. 0 6 : On if a buffer is reserved for sending TS ACCEPT. Used in CHFLOW and COPOUT. 0 7 : On if call is TS-compatible: X'7F' found in CUDF on input, or X'7FFFFFFF' inserted in CUDF on output. 0 KIFLGS: Bits are used individually as follows, all bits being initially zero. 0 0 : On when timeout has occurred in state 5. Used by CHFLOW. 0 1 : On if an Interrupt Confirmation is awaited from network. Used by CHFLOW and CRPOUT. 0 2 : On if EXPEDITED ACKNOWLEDGEMENT is awaited from application. Used by CHFLOW and CRPOUT. 0 3 : On if 'bad control message' response to application is queued. Used by CHFLOW and CRPOUT. - 0 NCP : INTERNAL ORGANISATION PAGE 11 1 0 Ref. B2 0 4 : Equal to M-bit setting in last incoming packet. Terminal calls only. Used by ITP. 0 5 : On if last packet received contained TS29 control information. Used by ITP. 0 6 : Equal to M-bit setting in last outgoing packet. Terminal calls only. Used by CHFLOW, CPCHOP, and ITP. 0 7 : On if awaiting Clear Confirmation from network. Used by CHFLOW, CRPOUT and SUBOUT. 0 MIFLGS: Bits are used individually as follows, all bits being initially zero. 0 0 : On if a TS DISCONNECT has been sent. Used by CPCHOP. 0 1 : On if a Clear Request or Clear Confirmation packet is ready to go and is pointed to by KKK. Used by CHFLOW and SUBOUT. 0 2 to 7 : Not yet used. 0 ICSPAR(2) : Spare. 0 NPRS, NPRT: Used in connection with flow control 0 IWIP : Window in/out; packetsize in/out (4 bits each) 0 LPRESD: Used by SUBIN in connection with TS ACCEPT 0 LCALTP : Call type: 0 This remains zero until the call type has been established. It may then take the following values: 0 x'84' : Standard interface, outgoing, via VMCF X'85' : Standard interface, incoming, via VMCF X'8D' : Incoming via VMCF with 2 subchannels (other than VNET) X'8F' : Terminal call (incoming) X'9D' : VNET (RSCS) X'AF' : 3270 call (incoming) 0 Bit significance in LCALTP: 0 Bit 0 : Always on if LCALTP is set Bit 1 : Currently zero Bit 2 : 0 = not 3270; 1 = 3270. Bit 3 : 0 = non-RJE; 1 = RJE Bit 4 : 0 = TS interface; 1 = TS within NCP - NCP : INTERNAL ORGANISATION PAGE 12 1 0 Ref. B2 0 Bit 5 : 0 = not VM; 1 = VM Bit 6 : 0 = not terminal; 1 = terminal Bit 7 : 0 = outgoing; 1 = incoming 0 JRNRQ: Head of IPC-maintained queue of packets delayed by an RNR packet. 0 IEXTRA(8): Available for non-terminal calls only. Last byte currently holds remote number in case of VNET calls. These 8 bytes overlay JSLOT, ISTATX and IDSCB. 0 JSLOT: LDSF device address (returned by CP) in range 4B00 to 4FFF 0 ISTATX: Believed to be no longer used 0 IDSCB: Used as pointer (terminal calls only) 0 IBYSCB to end: Used by terminal calls only. The use of most of these should be clear from the context except possibly the following: 0 IBYSCB: Latest LDSF interrupt code received from CP 0 JRETQ : Head of IPC-maintained queue of messages to be sent back to caller by NCP - 7. Transport Service + _________ _______ 0 There is no visible Transport Service level in NCP, but a subset of the Yellow Book Transport Service is implemented. The Transport Service can be considered as partly inside NCP, where it is effectively bolted on to the call handler software, and partly extending across the VMCF interface to applications processes, which must contain software able to understand the Transport Service primitives. 0 Transport Service CONNECT, ACCEPT, DISCONNECT, DATA, PUSH, EXPEDITED and ADDRESS are supported. RESET is not (yet) supported. CONNECT is supported in the simplified form recommended by the JNT. The ADDRESS primitive can transmit and receive addresses of up to 63 characters only. DISCONNECT from the application or from the network causes a Clear Request packet to be sent. - 8. Support for Incoming VNET (RSCS) Calls + _______ ___ ________ ____ ____ _____ 0 This is described in Ref. B4. - 0 NCP : INTERNAL ORGANISATION PAGE 13 1 0 Ref. B2 0 9. Support for Incoming Terminal Calls + _______ ___ ________ ________ _____ 0 This is described in Refs. B3, B6 and B7. - 10. Statistics + __________ 0 This topic is discussed in Ref. B5. - 11. Development and Diagnostic Aids + ___________ ___ __________ ____ 0 It is not desirable for some of these to be widely known, so they are mentioned here rather than in the Operators' documentation. 0 Various commands may be input to NCP from the console. The most useful of these are as follows: 0 (1) S W(n) = x: This command sets the nth element of the + __________ INTEGER*4 array W to the value x. W is equivalenced to the ICRD common area, and an arbitrary limit is imposed on n by routine DCODNL. 0 (2) SLNEn, DLNEn, PLNEn : These are commands to start, + _____ _____ _____ display and drain line n respectively. 0 (3) DIAGONn : This command turns on diagnostic printing + _______ for line n. One line of output is printed per block transmitted or received. If n=9 is used, the whole of every block on every line is printed (this can be voluminous). All printing goes onto the logging disc. DIAGOFFn turns the diagnostic + ________ printing off. 0 (4) FLUSH : This command causes any logging information + _____ still in store to be written away to the log. 0 (5) MONI : This causes the current state of the buffer + ____ histograms to be recorded in the log. 0 (6) TERMINATE : This terminates NCP cleanly with an + _________ 'abend code' of 0000. 0 (7) ABENDDUMP : This abends NCP with a dump, giving an + _________ abend code of 2650, and leaving the virtual machine in a usable condition. - 12. Virtual Machine Usage + _______ _______ _____ 0 To run NCP in a CMS virtual machine under VM, the virtual machine must have the REAL TIMER and ECMODE options on. - NCP : INTERNAL ORGANISATION PAGE 14 1 0 Ref. B2 0 To deal with interrupts in the most efficient manner, the VM-specific initialisation routine IEAVM alters the external and I/O new PSWs in the CMS nucleus to point to NCP's interrupt handling code. The original PSWs are restored by the STAE exit when the program terminates or abends, but it should be noted that this will not happen if the program is terminated by an HX command. For this reason HX should not be used: it will leave the virtual machine in an unusable condition. - 13. Abnormal Termination Dumps + ________ ___________ _____ 0 If the program terminates abnormally, a dump is produced and the abend code appears on the console in decimal. For instance a code of 0196 corresponds to the more familiar X'0C4'. 0 The PSW and registers quoted at the front of the dump should be ignored, apart from R0. 0 R0 points to the STAE work area, whose contents are as follows: 0 Word 0 : Zero Word 1 : Abend code Words 2-3: PSW within STAE exit Words 4-5: PSW at time of abend Words 6 ff : Registers 0 to 15 at time of abend 0 In addition to the abend codes listed in the IPC documentation (Ref. C1), the following may also occur: 0 2648 : Attempt to run program with invalid configuration parameters (can only occur during program initialisation). 0 2649 : Invalid title table or inability to read it from disc (can only occur during program initialisation). 0 2650 : Program aborted by operator command. - 14. References + __________ 0 Consult the Index to Documentation (Ref.I1) for all references used in this paper. - - 0 NCP : INTERNAL ORGANISATION PAGE 15 1 0 Ref. B2 0 APPENDIX 1 : ROUTINES + ________ _ ________ 0 This Appendix gives a summary of the function of each routine and entry point. An abbreviated list, for reference, will be found in the VMNCP Maintenance paper (Ref. E1). 0 1. FORTRAN ROUTINES + _______ ________ 0 MAIN : Calls VM initialisation (IEAVM) and NCP initialisation (MAIN1), then enters the IPC dispatcher at I$GO. All processes are set up and made initially dispatchable by calls to I$DISP in MAIN1. 0 BLOKDATA : Contains globally required variables, arrays, control blocks and constants. All the normal configuration constants can be altered by changing this routine alone. 0 CHFLOW : Call handler process main routine (one process per call). 0 CHMAST : Master outgoing call process (one process altogether). Listens for outgoing call requests from applications, and assigns a working call handler (CHFLOW) process to handle each call. Contains the list of 'trusted virtual machines' allowed to make outgoing calls. 0 COMM : Handles operator commands to the program. 0 CPCHOP : Called by CHFLOW. Handles abort or disconnection of calls to CP/CMS. 0 CRPIN2 : Called by CHFLOW. Handles Incoming Call packets and incoming Call Connected packets. 0 CRPOUT : Called by the COPOUT entry point in SUBIN. Handles outgoing Call Request and Call Accepted packets. Handles outgoing Clear Request packets sent in response to an Incoming Call packet. Also handles outgoing Transport Service control packets. 0 DCODNL : Used by COMM to analyse the syntax of operator commands. 0 FACIN : Called by CRPIN2. Analyses incoming X25 Facilities fields. - - NCP : INTERNAL ORGANISATION PAGE 16 1 0 Ref. B2 0 FACUT : Called by CRPOUT. Sets up outgoing X25 Facilities fields. 0 FAIL1 : Called by CHFLOW. Prepares a Clear Request packet following an application interface failure. 0 FAIL2 (entry) : Prepares a Clear Request (via SUBOUT) and sends a DISCONNECT control record to application (if needed) when NCP has decided to clear a call. 0 FAIL3 (entry) : Decides diagnostic code for various special reasons for clearing a call. 0 GETLAB : Called by CRPIN2 and CRPOUT. Assigns an LCN. 0 LOGLAB (entry) : Logs a newly assigned LCN. 0 IERR : Outputs call handler error messages to log. 0 INIT : Special initialisation process for Ethernet (could be removed). 0 ITP : Called by CHFLOW. Handles the application interface for incoming terminal calls. 0 LOGERR : Routines for outputting logging and diagnostics. 0 Entries: SOHENQ, LOGRRT, LINERR, DELAY, DIAGS, LOGNIP. 0 MAIN1 : Called by MAIN. NCP initialisation routine. 0 MONITR : Process for periodically outputting buffer usage histograms. 0 MONIT2 : Called by MONITR to deal with details of each histogram. 0 OUT : Writes to log (via DEFI package). 0 MARK (entry) : Writes a special debug record to log. 0 RESIGN : Called by CHFLOW. Closes down a call handler process. 0 RESIG2 (entry) : Closes down the application interface of a call handler process. 0 PURGE (entry) : Discards buffers queued on drained lines. - NCP : INTERNAL ORGANISATION PAGE 17 1 0 Ref. B2 0 STITLE : Called by CRPOUT and TSADDR. Performs transformations on Transport Service addresses. 0 SUBIN : Called by CHFLOW (other entry points are also called from other call handler routines). Analyses incoming X25 data, RR and RNR packets (Level 3). 0 SUBOUT (entry) : Handles outgoing X25 data, RR and Interrupt packets. 0 EXPOUT (entry) : Entry point to SUBOUT for Interrupt packets. 0 EMPOUT (entry) : Entry point to SUBOUT for RR packets. 0 COPOUT (entry) : Calls CRPOUT, then sends TS 'ACCEPT' message. 0 TELUSR : Queues a control record for application. 0 SETREP (entry) : Simulates incoming Clear Indication packet. 0 CLROUT (entry) : Simulates DISCONNECT record from application. 0 TERMIN : Process to terminate NCP cleanly. 0 TSADDR : Deals with outgoing TS ADDRESS message. 0 CMPRESS (entry) : Compresses incoming TS addresses. 0 ADDDTE (entry) : Add DTE no. to front of TS address. 0 TSADIN (entry) : Handle incoming TS ADDRESS message. - 2) ASSEMBLY ROUTINES + ________ ________ 0 DEFI : Free-standing disc I/O package. Deals with 4K blocks only. 0 DRIN (entry) : Reads a block. 0 DROUT (entry) : Writes a block. 0 FETCH : Called by ITP. Fetches a record from CP/CMS via LDSF. 0 SEND (entry) : Sends a record to CP/CMS via LDSF. - NCP : INTERNAL ORGANISATION PAGE 18 1 0 Ref. B2 - LDINIT (entry) : Initiates CP/CMS logical device. 0 LDTERM (entry) : Terminates CP/CMS logical device. 0 LDEND (entry) : Terminates LDSF interface. 0 GETTAG : Called by CHMAST. Picks up 'Tag' (Sub-Function name) of calling application. 0 IEAVM : Called by MAIN. Performs general VM initialisation and contains interrupt handling routines. 0 TIMDAT (entry) : Gets time and date. 0 RDTERM (entry) : Reads from console. 0 WRTERM (entry) : Writes to console. 0 SVC19 (entry) : Simulates SVC 19 for IPC. 0 SVC242 (entry) : Simulates SVC 242 (VMCF package entry). 0 RMBRANIP (entry) : Simulates GETMAIN branch entry for IPC. 0 RMBRANCH (entry) : Simulates GETMAIN branch entry for VMCF package. 0 IORGSW (entry) : Simulates IOS switch for VMCF package. 0 JOBNAM (entry) : Returns a 'job name'. 0 IEA0PT02 (entry) : Simulates 'POST' branch entry for IPC and VMCF package. 0 STAEXIT : STAE exit routine. 0 SVC13, SVC13A, SVC13B, SVC13C (entries) : Terminate the program (various codes). 0 EXTINT : General external interrupt handler. 0 SVC0 (entry) : Simulates EXCP for Level 2 line driver. 0 DEVINT : General I/O interrupt handler. 0 ETHER, PKTREF, DUMMY (entries) : Null. 0 TCBDUM (entry) : Dummy TCB and CVT. - NCP : INTERNAL ORGANISATION PAGE 19 1 0 Ref. B2 - IOMONI : Monitors line error thresholds and issues warnings to operator. 0 IPC : Free-standing package for inter-process communications. See Ref. C1. 0 Entries: I$MAIN, I$VMCF, I$DISP, I$GO, I$OPEN, I$MOVE, I$IO, I$CHEK, I$CLOS, I$TRAN, I$BUF, I$PCB, I$WAIT, I$GLOB, $TIMECB. 0 LMCALL : Called by LMFLOW. Decides type of call handler needed for incoming calls. 0 LMFLOW : Level 2 (BSC) Line Driver process. 0 MASITP : Called by ITP. Handles details of terminal protocols (ITP, XXX, TS29). MASITP itself handles outgoing records. 0 ITPMAS (entry) : Handles incoming records. 0 NCP : 'Distributor routine' for IPC. See Ref. C1. Enters appropriate main routine for whichever type of process is in control. 0 NCPCMS : Process which fields LDSF interrupts and feeds them to the appropriate Call Handler process. 0 STATS : Process for collecting X25 weekly statistics and maintaining them on disc. 0 TABLE : Called by MAIN1. Sets up the network address (title) table in store from CMS file VMNCP TITLES. 0 TRCONV : Performs ASCII/EBCDIC conversions and vice versa. 0 IEAVMCF : VMCF package. See Ref. C2. 0 IGC242 (entry) : Main entry point for VMCF handling. 0 LDSFEXT (entry) : LDSF interrupt handling routine. 0 VMCFEXT (entry) : VMCF interrupt handling routine. 0 IEAVMCF2 (entry) : Table of useful addresses - - - NCP : INTERNAL ORGANISATION PAGE 20 1 0 Ref. B2 0 APPENDIX 2 : FLOW CONTROL + ________ _ ____ _______ 0 This Appendix describes the X25 Level 3 flow control algorithms used by NCP. 0 Flow control operates on a per-call basis and normally end-to- end. The algorithms implemented in the DTE are the same, however, whether flow control is end-to-end or link-by-link. 0 (1) Basic Concepts + _____ ________ 0 The algorithms are described in terms of two 'ends' of a call, one of which is of course NCP itself. Each end is considered to "own" a number of data buffers, each of which may be used for sending one data packet, but which must then be passed back in some way before it can be re-used. The receiving end can control the rate of flow by withholding one or more of the other end's buffers until it is willing for them to be re-used. 0 The mechanism for returning buffers to the owner is to do one of the following: 0 a) Piggy-back them wherever possible onto a data packet flowing the other way 0 b) Use an "RR" packet, which can be sent at any time, even if the sender has no data to transmit or no data buffer of its own available. 0 The number of buffers owned by a particular end corresponds to the X25 window size, WOUT, for outgoing packets. - (2) Flow Control Variables + ____ _______ _________ 0 IQ = no. of buffers owned by this end, which are currently available at this end. 0 IN = no. of buffers owned by the other end (a fixed number) 0 IP = no. of buffers owned by the other end, which are currently at this end. 0 IC = no. of data buffers that this end is currently willing to receive. - (3) Call Set-Up + ____ ___ __ 0 Initialise: 0 IQ = no. of buffers owned by this end (WOUT) - NCP : INTERNAL ORGANISATION PAGE 21 1 0 Ref. B2 - IN = no. of buffers owned by other end (WIN) 0 IP = 0 0 IC = IN - (4) Receipt of Data Packet + _______ __ ____ ______ 0 Verify that the 'Send' sequence number in the incoming packet is correct. 0 Set: 0 IQ = IQ + NPAK (NPAK is the number of piggy-backed buffers being returned - see section (12) below) 0 IP = IP + 1 0 IC = IC - 1 - (5) Receipt of RR Packet + _______ __ __ ______ - Set: IQ = IQ + NPAK (NPAK is the number of buffers being returned - see section (12) below) - (6) When a Received Data Packet has been disposed of: + ____ _ ________ ____ ______ ___ ____ ________ __ 0 Set: IC = IC + 1 0 Note: What "disposed of" means depends on circumstances. It + ____ may mean: passed to the application level; or passed out on another link; or whatever the local implementor chooses. - (7) Deciding when to send a Packet + ________ ____ __ ____ _ ______ 0 In principle, a decision needs to be made whenever a significant change has occurred in any of the flow control variables, or whenever some data has become available for sending out. - (8) Deciding how many Buffers owned by the other End should be + ________ ___ ____ _______ _____ __ ___ _____ ___ ______ __ Returned: + ________ 0 A simple algorithm is as follows:- 0 Let IR be the number of buffers to be returned. Then:- - NCP : INTERNAL ORGANISATION PAGE 22 1 0 Ref. B2 - If IP = 0 or IC not > IN - IP set IR = 0 0 Otherwise, if IC not < IN set IR = IP 0 Otherwise set IR = IC - (IN - IP) - (9) Deciding what Type of Packet to send + ________ ____ ____ __ ______ __ ____ - If data is available and IQ > 0 , send a data packet. 0 Otherwise, if IR not 0, send an RR packet. 0 Otherwise, send nothing. - (10) When sending a Data Packet + ____ _______ _ ____ ______ 0 Set: 0 IQ = IQ - 1 0 IP = IP - IR 0 Indicate in the packet how many buffers are being returned (i.e: by means of the P(R) field - see section (12)) 0 Insert the correct 'Send' sequence number. - (11) When sending an RR Packet + ____ _______ __ __ ______ 0 Set: IP = IP - IR 0 Indicate in the packet how many buffers are being returned (see section (12)). - (12) Relation to X25 P(R) Fields + ________ __ ___ _ _ ______ 0 If: P(R)s = this end's current window edge for output (initially 0) 0 and: P(R)t = other end's current window edge for output (initially 0) 0 Then when receiving a data or RR packet: + ____ ____ _________ _ ____ __ __ ______ 0 NPAK = MOD (P(R) - P(R)s + 8 , 8) - NCP : INTERNAL ORGANISATION PAGE 23 1 0 Ref. B2 0 The new window edge this end is given by P(R)s = P(R) 0 or equivalently by: 0 P(R)s = MOD (P(R)s + NPAK , 8) 0 (On receipt of the packet, the receiving end should verify that P(R) in the packet lies in the inclusive range between the current window edge at this end, P(R)s, and one higher than the 'Send' sequence number in the last outgoing packet. Otherwise there is a breach of protocol). 0 When sending a data packet or RR packet, P(R) in the packet + ____ _______ _ ____ ______ __ __ ______ _ _ __ ___ ______ should be set as follows:- 0 P(R) = MOD (P(R)t + IR , 8) 0 Then, to keep the local variable up to date, set: 0 P(R)t = MOD (P(R)t + IR , 8) - - - - - - - - - - - - NCP : INTERNAL ORGANISATION PAGE 24