DEIMOS Vsn 5, 11 April '85 B. Gilmore Yellow Book GATE - to - TASK Interface ======================================= This note describes the interface between a Task and a 'Yellow book' GATE. The intention with a 'yellow book' GATE is that the interface is common accross NSI, (TS)BSP and X25, though each protocol will require a different GATE. The interface operates by the sending of messages as records, 'P', in the format: %BYTEINTEGER SER, REPLY, FN, S1, %C (%RECORD (MEF) %NAME MES, %C %BYTEINTEGER GATE PORT, TASK PORT) %OR (%STRING (3) FACILITY) where SER = service number of receiving task REPLY = service number of sending task FN = function code S1 = use is dependant on function MES = pointer to a parameter area, use is dependant on function. GATE PORT = a reference value for a virtual call supplied by GATE TASK PORT = a reference value for a virtual call supplied by TASK NB: In both cases, 0 is reserved for the case when the relevant side has not yet defined it. FACILITY = A Facility name - See Enable/Disable Facility The general format of MEF is as follows:- %RECORDFORMAT (MEF) %NAME LINK, %C %BYTEINTEGER LEN, TYPE, %C (%STRING (7) PROTOCOL USE, %BYTEINTEGERARRAY DATA(0:238)) % %OR %BYTEINTEGERARRAY PARAMS(0:250)) where: LINK = A pointer that may be used by Task to link buffers LEN = Number of bytes used in the array P_MES_DATA or P_MES_PARAMS TYPE = 0 is a 256 byte block, x'80' is a 'short' block. PROTOCOL USE = Area used by the particular protocol in use - no assumptions can be made about it. DATA = Contains user data either going to Gate or received from Gate by the Task on Put Output and Input Here calls PARAMS = A number of text strings, packed together, used in Connect, Accept Call and Disconnect. The various functions available in the two directions accross the interface are as follows (FN code in brackets): TASK to GATE ============ (1) Connect (2) Accept Call (3) Disconnect (4) Enable Input (5) Put Output (6) Expedited Data (7) Reset (8) Datagram (Not Used in X25) (9) Datagram reply (Not Used in X25) (10) Enable Facility (11) Disable Facility (12) Put Control Output (for XXX use only) GATE to TASK ============ (1) Connect (2) Accept Call (3) Disconnect (4) Enable Output (5) Input Here (6) Expedited Data (7) Reset (8) Datagram (Not Used in X25) (9) Datagram Reply (Not Used in X25) (12) Input Control Data (for XXX only) In detail, these functions are as follows Interface: TASK to GATE ======================== Connect: P_MES_PARAMS = Parameters. P_TASK PORT = TASK's reference number, which will be quoted by GATE in all subsequent refs to this connection P_S1 = 0 - implies a YB Call = 1 - implies an XXX call (X25 only) = 2 - implies a YB Call, but requests that the YB accept is sent through explicitly as a Control Data packet (X25 only). This call opens a virtual connection. The parameters are put in 'PARAMS' and consist of 4 strings: The strings are packed tight against each other, ie no unneccessary bytes - though still preceeded by their individual lengths. NB: The strings may only contain printable characters The format of is as follows: "W=n/m,P=n/m" or "W=n/m" or "P=n/m" Where n and m are integer values, W specifies the window size (or equivalent) in the forward (n) and reverse (m) directions, if W is not specified, then a default of 2/2 will be used. P specifies the maximun packet size in the forward and reverse directions. If p is not specified, then a default of 128 will be used in the case of X25, 238 otherwise. GATE will reply to the TASK with a 'Accept Call' or a Disconnect Accept Call: P_MES_PARAMETERS = parameters P_GATE PORT = Reference used by GATE in its 'Connect' P_TASK PORT = A reference number supplied by the TASK that GATE will quote in future A Task uses this function to reply to a 'Connect' from GATE, it specifies that the virtual connection is to be established and the reference number that GATE will use for this call. The format of Parameters is as follows: Disconnect: P_GATE PORT = Gate's reference number P_TASK PORT = The Task's reference number P_MES_PARAMS = Disconnect parameters P_S1 = This call: 1) Rejects a Connect from Gate 2) Forces the close of a connection 3) Answers a Disconnect from Gate The values of are given in full in Appendix B of Part 1 of the Yellow Book, a summary follows: meaning 0 Normal Disconnect 1 Reply to a Disconnect 16-24 rejection reasons 32-45 errors The disconnect parameters are in the form: as two packed strings (see Connect) They may be null. Enable Input: P_GATE PORT = GATE's reference number P_TASK PORT = The TASK's reference number P_S1 = The number of blocks of input that the TASK is prepared to accept without further intervention to GATE. Note: This should not be zero ! When a connection is established, the count is started at the window size, so the task will receive 'window' blocks before Gate blocks further input. Put output: P_GATE PORT = GATE's reference number for this connection P_TASK PORT = The TASK's reference number. P_MES_DATA = User data. P_S1 = Push flag (1 means issue Push) The actual data is carried in the aray DATA, no assumpions can be made about what P_MES_PROTOCOL USE contains. LEN is the actual number of user data bytes in DATA. Gate will queue Put Output requests as necessary. It is the tasks responsibility to ensure that it doesn't send enough requests to empty the system of buffers. The Push flag is implemented end-to-end as in Yellow Book. Expedited Data: P_GATE PORT = Gate's reference number P_TASK PORT = The Task's reference number P_S1 = A single character OR P_MES_PARAMS= A string of characters (and S1 = 0) This function is used to force a 'message' through against the normal flow control, it should be noted that most implementations: will only allow one outstanding at a time. In X25, only one character may be sent. Reset: P_GATE PORT = Gate's reference number P_TASK PORT = Task's reference number P_S1 = Coded Reason P_MES_PARAMS=
This function forces a reset of a virtual circuit. 'Coded Reason' is the same as in Disconnect, and Params is two packed strings as in disconnect. In some implementations this may be implemented as a disconnect. Datagram: P_TASK PORT = Task's reference number P_MES_PARAMS = Parameters This call sends a 'datagram' (network dependant!- not X25) into the network, the format of Params is the same as for 'Open Call' exept That is now the Datagram text and may be binary. Datagram Reply: P_GATE PORT = Gate's reference number from 'Datagram' P_MES_PARAMS = Parameters & reply text P_MES_S1 = This call is used by the Task to acknowledge a 'Datagram' from gate, params is the same as Disconnect, exept that is the reply text and may be binary. Enable Facility: P_S1 = Flag P_FACILITY = Facility Name Or P_MES_PARAMS = Facility Name Requests that calls of a particular type, ie ITP, RJE, FTP, Datagram will be sent to TASK. Subsequent similar calls on Enable Facility simply supercedes earlier calls. Various generic names will normally be used, eg: RJE, FTP, MAIL, LP etc (Note: in X25 itp is RTP, otherwise it is ITP) If the name is less then 4 characters it may be put in P_FACILITY and the flag P_S1 = 0, longer names are put in P_MES_PARAMS and P_S1 = 1. Disable Facility: P_S1 = Flag P_FACILITY OR P_MES_PARAMS = Facility Name The reverse of Enable Facility. Interface: GATE to TASK ======================== Connect: P_GATE PORT = Gate's reference number for this connection P_MES_PARAMS = Parameters This call is used by Gate when it receives a call from the network. Parameters are the same as Connect (Task->Gate) Task should reply with a Accept Call or a Disconnect. Accept Call: P_GATE PORT = Gate's reference number P_TASK PORT = Task Port specified in Connect P_MES_PARAMS = Parameters This call is used by Gate when it receives confirmation of a Connect send into the network, the format of Params is the same as for 'Accept Call' (Task->Gate) Note: In X25, the Gate sends an Accept Call when it receives the X25 Level 3 Accept, NOT on receipt of the YB accept. When the YB accept is received, it is ditched. If a YB Disconnect is received, Gate clears the call down normally. For a Task which wants to know about the YB accept, then see P_S1 = 2 on the Connect function. Input Here: P_GATE PORT = Gate's reference number for this conection P_TASK PORT = Task's reference number for this connection P_S1 = Push Flag (1 = Block was 'Pushed'), 0 no push P_MES_DATA = Array containing the User data This call is used by Gate when a block has been received from the network. Enable Output: P_GATE PORT = Gate's reference number P_TASK PORT = Task's reference number P_S1 = The number of blocks that Task may send This call is used by Gate to signal the Task that S1 more blocks have been sent to the remote end. A Task should use this information to limit the size of output queue it expects Gate to handle. Disconnect: P_GATE PORT = Gate's Reference number for this connection P_TASK PORT = Task's reference number P_S1 = P_MES_PARAMS = This is the same as Disconnect (Task->Gate) Expedited Data: P_GATE PORT = Port number as assigned by Gate P_TASK PORT = Task's reference number. P_S1 = Single character of data OR P_MES_PARAMS= Multiple character data (and P_S1=0) This function is the same as Gate -> TASK RESET: P_GATE PORT = Port Number as assigned by Gate P_TASK PORT = Task's reference number This function is the same as Gate -> Task Datagram: P_GATE PORT = Port number assigned by Gate P_PARAMS = Parameters This call is the same as Datagram (Task->Gate) Datagram Reply: P_TASK PORT = Port supplied by Task on Datagram P_MES_PARAMS = Parameters P_S1 = This call is the same as Datagram Reply (Task->Gate) Implementation Details ====================== 1) NSI a) Call Closedown The Yellow Block spec defines 'disconnect' to be destructive. This is satisfactory for both ITP & FTP but not for RJE. The proposal is that while RJE is around, the RJE server will 'Push' the last data block, when the other end sees the Push it will issue a Disconnect(normal) to clear the call. To avoid timing problems, Status+disconnect will have to be flagged so that Disconnect(normal) can be distinguished from Disconnect(error) It would appear reasonable to use the user flag field, so that all implementations should set this word non-zero (ie not-normal) at the earliest opportunity. b) a problem is in the 'user flag' byte used by RJE and to a lesser extent by Send Message. Since the byte lies within the NSI header it is virtually impossible to carry it accross to a different network as only some connections are using it. There are 2 possible solutions 1) Consider the user flag byte to be the first byte of the data block, rather than in the NSI header. 2) Scrap it. All files go as binary over NSI If the first solution is used, it will mean that all other high level protocols will need to carry an RJE byte on the beginning. Ie both ITP & FTP would have to be redefined to include this unneccessary byte. This of couse has external implications when not going through a full gateway. There are only two instances that will cause problems if the second solution is adopted. 1) Paper Tape output has parity bits & CR added when mode=iso 2) Glasgow use binary cards (ie no LF is added) The problem of paper tape can be solved in two ways, either each host adds parity before sending out the file or a new facility number is used to signify 'add parity'. The Glasgow problem can be solved if they pass binary cards in using facility 13(paper tape input). c) Call Setup & Qual of Serveters All address will be passed in text form, and the only service parameter that is currently used is window size, eg "N155T155S13" "" "W=3/0" "" d) Header sizes The NSI header size is only 6 bytes on data blocks, whereas 8 have been allowed. It is proposed that the protocol handler will be changed to both transmit & receive packets two bytes further down the blocks than at present. If you have any comments/suggestions please give them to me ASAP