1 0 Ref. D1 - A TRANSPORT SERVICE INTERFACE VIA IPC (Ref. D1) + _ _________ _______ _________ ___ ___ ___ __ 0 Version 4 + _______ _ 0 8 March 1982 + _ _____ ____ 0 P M Girard + _ _ ______ 0 1. Introduction + ____________ 0 To facilitate eventual transition to an ISO Standard Transport Service, hopefully manufacturer-supported, it is important that Applications should all use the same Transport Service interface. This paper defines the interface and describes the software that implements it. 0 The Transport Service interface is built upon various lower level facilities. The basic component is the IPC Package (Ref. C1), which provides the necessary network "Access Method" facilities to OPEN and CLOSE connections and to PUT and GET data on those connections. Ref. C1 also specifies in detail how the user's software needs to be structured to make use of these facilities. Essentially, the implementor can choose whether to use the Access Method facilities only (single process mode), or to use IPC to handle his multi-process environment generally (multi-process mode). A user who wishes to drive multiple Transport Service connections is advised to use multi- process mode if at all possible. 0 The user will also need to refer to Section 9 of Ref. A3, which describes the formats of the various control records used by the Transport Service interface, and to Section 6 of Ref. A3, which gives a list of allowed Sub-Function names. - 2. Summary of Relevant IPC Functions + _______ __ ________ ___ _________ 0 At least the following functions will be needed. 0 CALL I$GLOB('SUBFNAME','USERID ',reason,reply) CALL I$VMCF ('SUBFNAME',slots,subs,reply) CALL I$OPEN (port,type,addressing,reply) CALL I$MOVE (port,type,length,data,reply) CALL I$CHEK (port,type,reply,status) CALL I$CLOS (port,reply) 0 Full details are given in the IPC documentation (Ref. C1). It should be remembered that I$OPEN and I$MOVE are asynchronous, and merely initiate an activity. I$CHEK tests for completion of an asynchronous activity. - A TRANSPORT SERVICE INTERFACE VIA IPC PAGE 1 1 0 Ref. D1 - 3. Modes of using the IPC Package + _____ __ _____ ___ ___ _______ 0 The package was designed originally to handle multi- process programs, and such programs get going by issuing I$MAIN, I$GLOB, I$VMCF, I$BUF, and I$DISP calls, followed by an I$GO call which passes control to a main routine within the package. This routine then activates user processes whenever they become dispatchable. 0 The application may, however, be intrinsically a single- process program, or it may be a program that runs under its own multi-process supervisor and consequently could not easily use the multi-process facilities of IPC. In either of these cases, the program may be set up to look like a single IPC process, and need not relinquish control to the package when issuing the I$GO. This "single- process mode" is indicated by using a zero argument with I$GO, which causes control to return immediately to the user's next instruction. To suspend the process subsequently to wait for a timer or other IPC-controlled event, the user may issue an I$WAIT call. Control will return in due course to the instruction following the I$WAIT call. 0 There is currently a limit of 255 'connections' per IPC process, so a program running in single-process mode is restricted to 255 network calls. 0 Details of how to use the multi-process and single-process modes will be found in the IPC documentation (Ref. C1). The use of multi-process mode is recommended wherever possible, if multiple asynchronous activities are involved, as the package was not really designed to handle a large number of asynchronous activities per process. If necessary, it may be possible to enhance the package to handle such situations more efficiently. 0 The user's virtual machine must have the REAL TIMER and ECMODE options on. 0 The user's attention is drawn to the requirements stated in Ref. A3 for the receipt of control records from NCP (i.e: on the 'GTC ' subchannel). Briefly these are that a record area of at least 265 bytes should be provided, and control records of unknown type should be tolerated but ignored. These provisions should ensure upwards compatibility with further developments to NCP. - 4. Issuing a GLOBAL DISCONNECT + _______ _ ______ __________ 0 CALL I$GLOB ('SUBFNAME','USERID ',reason,reply) - A TRANSPORT SERVICE INTERFACE VIA IPC PAGE 2 1 0 Ref. D1 0 For Transport Service use, 'USERID ' should be the name of NCP's virtual machine. Use of this function before a corresponding I$VMCF will ensure that any connections left hanging from a previous use of the Sub-Function will be closed down. The user should supply a reason code in the range 0 to 9. - 5. Declaring a Sub-Function + _________ _ ___ ________ 0 To allow for the possibility that connections may be of several different kinds, the concept of a Sub-Function was introduced. This makes it possible to perform global operations (such as GLOBAL DISCONNECT) on one whole class of connections without disturbing connections of other classes. In practice, the use of multiple Sub-Functions is probably only of interest to programs such as NCP itself, which handles several different types of network call. The normal Transport Service user will need to define only one Sub-Function. 0 A list of allowed Sub-Function names for Transport Service users will be found in Section 6 of Ref. A3. 0 The calling sequence is as follows: 0 CALL I$VMCF ('SUBFNAME',slots,subs,reply) 0 For Transport Service use, the arguments should be set as follows: 0 'SUBFNAME' is the 'Sub-Function name', which will form part of the network address of the service. See Section 6 of Ref. A3. 0 "slots" is the maximum number of network calls required. 0 "subs" must be set to zero (this will cause a normal 4-subchannel VMCF connection to be set up). 0 "reply" is set by the package and should be zero on return unless there has been an error. For errors, see Appendix 1 in the IPC documentation (Ref. C1). - 6. Opening a Connection to NCP + _______ _ __________ __ ___ 0 CALL I$OPEN (port,type,address array,reply) 0 For Transport Service use, the arguments should be set as follows: - - A TRANSPORT SERVICE INTERFACE VIA IPC PAGE 3 1 0 Ref. D1 0 "port" may be any constant in the range 1 to 255. It subsequently identifies this connection. 0 "type" must be set to 255 to listen for an incoming call, or to 254 to initiate an outgoing call. 0 The "address array" is a 56-byte area, which must be set up as follows:- 0 Bytes 0- 7 : blanks Bytes 8-15 : 'L ' if listening 'C ' if calling Bytes 16-23 : blanks Bytes 24-31 : Sub-Function name Bytes 32-47 : blanks Bytes 48-55 : userid of NCP virtual machine (may be blanks if listening) 0 Details of "reply" codes are given in Ref. C1. 0 The completion of I$OPEN is asynchronous and must be tested by means of I$CHEK, as described in Ref. C1. - 7. Transport Service CONNECT and ACCEPT + _________ _______ _______ ___ ______ 0 Once the connection to NCP has been established, it becomes possible for the TS CONNECT and ACCEPT records to be sent. These are transmitted in the appropriate directions on the pair of control subchannels provided by the connection. 0 Section 9 of Ref. A3 should be consulted for all TS control record formats. 0 If the application is listening for a call it should expect a CONNECT record by issuing: 0 CALL I$MOVE (port,'GTC ',length,record area,reply) 0 The completion of the I$MOVE is asynchronous and must be tested by I$CHEK as explained in Ref. C1. 0 Having completed reception of a CONNECT record, the application may decide whether to return an ACCEPT or a DISCONNECT record (see Ref. A3). 0 To return the appropriate type of record, it must set it up in the form described in Ref. A3, and send it to NCP on the control subchannel ("type" = 'PTC '). As usual, the I$MOVE must be followed up by an I$CHEK to test for its completion. - 0 A TRANSPORT SERVICE INTERFACE VIA IPC PAGE 4 1 0 Ref. D1 0 If the application is launching a call rather than listening for one, a similar interchange takes place in the reverse direction. The application sets up a TS CONNECT record and sends it on the control subchannel ("type" = 'PTC ') to NCP using I$MOVE and I$CHEK. It then sets itself up to receive a TS ACCEPT or a TS DISCONNECT on the control subchannel ("type" = 'GTC '), again using I$MOVE and I$CHEK. - 8. Transport Service DATA and PUSH Primitives + _________ _______ ____ ___ ____ __________ 0 The application may send an arbitrary length of data ( <32K ), with or without a Transport Service PUSH on the end. The VMCF 'PUSH' bit is set appropriately, as defined in Ref. A3. Un-pushed data will be built up into full packets by NCP and the X25 M-bit will be used accordingly. A PUSH on its own may be sent by specifying a data length of zero (I$CHEK is still needed as usual). 0 CALL I$MOVE (port,type,length,data address,reply) 0 "port" is the port number quoted in the I$OPEN. 0 "type" has the value 'PUT ' for pushed data or 'PUTN' for un-pushed data. 0 "length" is the number of bytes of data ( <32K ) 0 "data address" is the address of the data 0 "reply" is set by the package in the usual way (see Ref. C1). 0 The completion of the I$MOVE, being asynchronous, must be checked using I$CHEK. Completion will not occur until the full number of bytes specified has been transmitted (unless an error occurs). The value of the "status" argument in I$CHEK is set by the package, but has no usefulness in this context. - 9. Reception of Transport Service DATA and PUSH + _________ __ _________ _______ ____ ___ ____ 0 When the application is willing to receive data from NCP it should issue an I$MOVE with "type" = 'GETS', following this as usual with an I$CHEK. No assumption is involved that NCP is already trying to send something, as it does not matter which side of the interface issues an I$MOVE first. 0 The length of data specified may be anything less than 32K. The operation will complete on reception of the full - A TRANSPORT SERVICE INTERFACE VIA IPC PAGE 5 1 0 Ref. D1 0 number of bytes specified, or on receipt of a Transport Service PUSH (deduced from a zero M-bit in an incoming network packet) if this occurs sooner. More than one I$CHEK operation may be needed before the I$MOVE completes. The "status" argument in the I$CHEK is set by the package to the residual byte count (i.e: to the number of bytes requested which have not in fact been sent). The residual count cannot be still positive on final completion of the I$MOVE, unless PUSH has been received. The last bit of the "reply" argument in the I$CHEK will be set to zero if a PUSH was received, and to 1 if a PUSH was not received. 0 If 'GET ' instead of 'GETS' is used in the I$MOVE, the operation will complete in practice at the end of the first network packet. This may be an acceptable mode of operation, though in general packet boundaries are irrelevant to the application level, and 'GETS' is likely to be more convenient in most circumstances. - 10. Transport Service DISCONNECT + _________ _______ __________ 0 This may be transmitted to or from NCP on the control subchannels, using the record format given in Ref. A3. To be able to detect an incoming DISCONNECT (or other Transport Service control functions), the application must leave an I$MOVE pending with "type" = 'GTC '. If a DISCONNECT arrives, the application should assume that the network call is dead, and should close down its own end of the connection using I$CLOS. 0 The application may itself send out a TS DISCONNECT by means of an I$MOVE with "type" 'PTC '. When the I$CHEK indicates that this has been taken, it should issue an I$CLOS. If the application closes the connection without sending a DISCONNECT, NCP will assume there has been an application failure, and will clear the network call with an appropriate error code. - 11. Transport Service EXPEDITED Primitive + _________ _______ _________ _________ 0 Once a connection has been fully established, the application may send or receive EXPEDITED data. 0 EXPEDITED data is not subject to the same flow control provisions as ordinary DATA, and is given priority over the latter wherever possible. In particular, EXPEDITED data is guaranteed to be presented to the destination application before any subsequently issued ordinary data. - - A TRANSPORT SERVICE INTERFACE VIA IPC PAGE 6 1 0 Ref. D1 0 EXPEDITED data is conveyed across the application/NCP interface by means of EXPEDITED records on the appropriate control subchannel. The format of an EXPEDITED record is defined in Ref. A3, and it will be noted that each record must contain one and only one byte of EXPEDITED data. 0 The application must not send an EXPEDITED record until the call is fully established (i.e: an ACCEPT record has crossed the interface in one direction or the other). Having sent an EXPEDITED record, the application must not send another until it has received on the control subchannel an EXPEDITED ACKNOWLEDGEMENT record, as defined in Ref. A3. 0 If the application receives an EXPEDITED record from NCP, it should in due course send back an EXPEDITED ACKNOWLEDGEMENT record; otherwise the remote end will be unable to send any more EXPEDITED data. The application must not send an EXPEDITED ACKNOWLEDGEMENT unless an EXPEDITED record has been received. 0 If the application disobeys the above rules, or sends an unrecognisable control record of any kind, it is liable to receive an INFORMATION record on its incoming control subchannel. This is defined in Ref. A3. It will contain a diagnostic code implying a breach of protocol by the application, and the state of the connection will be left unaltered. An INFORMATION record will not necessarily be returned for every breach of protocol: to protect itself from berserk applications, NCP will simply discard bad control records if an INFORMATION record for a previous breach of protocol is still awaiting delivery. - 12. Transport Service ADDRESS Primitive + _________ _______ _______ _________ 0 The application may send and receive Transport Service ADDRESS messages. These are sent on the data subchannels, and their position relative to preceding and following data is preserved. 0 To send an ADDRESS message, the application must issue an I$MOVE procedure call, specifying a "type" of 'PUTA'. The message must be constructed as defined in the Transport Service specification, complete with a qualifier value and (if desired) a final zero byte indicating PUSH. Whether the PUSH byte is present or not, the ADDRESS message is transmitted to the network as soon as flow control allows. 0 When NCP has passed an ADDRESS message to the application, the latter's reception area will contain a single ADDRESS message with no preceding or following data. This is so because an ADDRESS message cannot validly follow un-pushed - A TRANSPORT SERVICE INTERFACE VIA IPC PAGE 7 1 0 Ref. D1 0 data, and because the interface forces completion of an ADDRESS message transfer whether or not it is followed by a Transport Level PUSH signal. An ADDRESS message may be detected by testing the last-but-one bit of the "reply" argument returned by I$CHEK. This is set to 1 if an ADDRESS message has been received. The last bit of the "reply", which for normal data indicates NO-PUSH if set to 1, is always zero for an ADDRESS message. This does not imply the presence of a Transport Level PUSH however; in the case of an ADDRESS message, a Transport Service PUSH (if present) is indicated by a zero byte on the end of the ADDRESS message, as defined in the Transport Service specification. 0 NCP imposes certain limitations on the lengths of addresses: the address itself as sent to the network or received from the network by NCP must not exceed 63 bytes, and if the application sets the qualifier to 'FROM' the address length as presented to NCP must not exceed 8 bytes. Similar limitations are imposed on addresses in CONNECT messages. - 13. Transport Service RESET Messages + _________ _______ _____ ________ 0 At the present time there is no support for RESET messages. Receipt of a RESET message from the network will cause the network call to be cleared with the appropriate diagnostic code. - 14. A Note on the use of I$CHEK + _ ____ __ ___ ___ __ _ ____ 0 An I$CHEK should be issued immediately after an I$OPEN or I$MOVE in case the operation has already completed. If it has not completed, the application should do other processing or suspend the process as appropriate. I$CHEK may be safely issued as often as desired until completion occurs. The mere re-activation of a process may imply that completion has probably occurred (if it is not doing much else), but some guidance as to whether it is worth re-trying an I$CHEK is given in the event-wait field in the process work-space (see Section 5 of Ref. C1). - 15. How to use the Transport Service Interface + ___ __ ___ ___ _________ _______ _________ 0 Three components must be linked into the application program: 0 (1) The IPC Package: The VM version is operating-system + ___ ___ _______ independent, so it should be usable as it stands under CMS or other virtual machine operating systems. - A TRANSPORT SERVICE INTERFACE VIA IPC PAGE 8 1 0 Ref. D1 0 (2) The VMCF Package: This too can be used under MVT, CMS + ___ ____ _______ or other operating systems. 0 (3) An IEAVMC Module: This is specific to a particular + __ ______ ______ operating system. However, it is small and simple, and it should be fairly easy to write an equivalent routine to run under other systems. The operating-system dependency consists in its use of GETMAIN/FREEMAIN facilities, a trap for external interrupts, and the use by the interrupt handler of some information provided by the operating system. 0 For single-process mode under VM, the module called IEAVMC may be suitable as it stands. For multi-process mode, it is probably worth studying both IEAVMC and IEAVM (which NCP itself uses) to assess what is required for a particular application. It should be noted that GETMAIN and FREEMAIN are very little used by the software (probably only during initialisation), so it is of no importance to make the GETMAIN/FREEmain simulation efficient. 0 With the above three components incorporated, the application program must issue the following IPC procedure calls to get going: 0 CALL IEAVMC(N) (N = no. of Sub-Functions) CALL I$MAIN( ) CALL I$GLOB( ) (optional: 1 per Sub-Function) CALL I$VMCF( ) (one per Sub-Function) CALL I$BUF( ) CALL I$DISP( ) (one per IPC process) CALL I$GO( ) 0 The user is then free to use the Transport Service facilities as described in this paper. - - - - - - - A TRANSPORT SERVICE INTERFACE VIA IPC PAGE 9 1 0 Ref. D1 0 16. References + __________ 0 A3: The Application/NCP Protocol using VMCF (P M Girard) 0 C1: Inter-Process Communications Package (IPC) (P M Girard) - - - - - - - - - - - - - - - - 0 A TRANSPORT SERVICE INTERFACE VIA IPC PAGE 10