IEN 150                                                  W. Plummer  BBN
                                                          J. Postel  ISI
                                                               June 1980

                       TCP JSYS CALLING SEQUENCES

This memo describes the TENEX and TOPS20 JSYSs for using TCP.  There are
a number of parameters that are common to this set of JSYSs and these
are described first.

These JSYSs use a Job Connection Number or "JCN" for connections in much
the same way file manipulating JSYSs use a Job File Number or "JFN" for
files.

   Typically a small number, the JCN is a handle on a connection, and is
   assigned by the OPEN JSYS.

These JSYSs also use a Connection Block , either directly or implicitly
by reference to an associated JCN.  The Connection Block is a 3-word
block:

   Word-0:  16-bit Local Port.
   Word-1:  8-bit Foreign Network and 24-bit Foreign Host.
   Word-2:  16-bit Foreign Port.

   These values are right justified in the 36-bit word.

These JSYSs take flags in the left half of AC 1.
Not all of these JSYSs look at all of the flags.  The flag bits are:

   Bit-0:  RH has JCN rather than pointer to connection block.
   Bit-1:  Wait for the JSYS to complete.
   Bit-5:  ForceSync -- cause SYN to be sent when OPEN executed.
   Bit-6:  Persist -- keep resending SYN packet.
   Bit-7:  Return statistics (STAT call only).



















Plummer & Postel                                                [page 1]


June 1980                                     TCP JSYS Calling Sequences



The SEND and RECV JSYSs use data buffers which have control blocks and
which may be chained together to form a ring of buffers.  These control
blocks are called Data Buffer Ring Elements.  The Data Buffer Ring
Element Format is:

   Word-0:  Flags,,unused by TCP (typically a pointer to next buffer
             header)
   Word-1:  0,,Address of data buffer
   Word-2:  Word/Byte count for this buffer

   Flags:

      Done:
         Cleared when TCP receives this buffer. Set when TCP has
         finished with it.

      Error:
         Buffer has an error associated with it.

      EOL:
         Send an end-of-letter with this buffer. Or, end-of-letter
         received with this buffer.

      WordMode:
         Buffer is formatted as 36-bit bytes. Off if buffer has four
         8-bit bytes per word. (Not Implemented Yet, 36-bit mode not
         supported.)

      Flag Bit Assignments:

         Bit 0:      Error
         Bit 1:      Local
         Bit 2:      Permanent
         Bits 3-7:   Error Number
         Bits 8-11:  Unused
         Bit 12:     Done
         Bits 13-15: Unused
         Bit 16:     EOL
         Bit 17:     Word Mode

      The error numbers are listed under "Error Returns".









[page 2]                                                Plummer & Postel


TCP JSYS Calling Sequences                                     June 1980



The OPEN ans SEND JSYSs take a "Retransmission Parameters" word.  This
is controls the retransmission function.

   The right half is the initial retransmission Interval which is to be
   used.  If the right half is 0, the initial Interval will be computed
   based on the measured round trip time. The left half of the
   parameters word has two 9-bit quantities, called the Numerator and
   the Denominator. In computing the next retransmission Interval from
   the previous one, the TCP multiplies the Interval by the Numerator
   and then divides by the Denominator.

      Interval = Interval * ( Numerator / Denominator )

   Common retransmission functions are:

   SRI PR demo:  Numerator=1, Denominator=1, Initial Interval=3.

      3 seconds constant retransmission interval with no backoff.

   BBN (vanilla):  Numerator=3, Denominator=2, Initial interval=0.

      Used in "average" conditions involving congested gateways and few
      dropped packets.  150% backoff from best guess initial interval.

   BBN (old):  Numerator=4, Denominator=2, Initial interval=0.

      Same as above but 200% backoff.  Quickly hits the 1 minute maximum
      interval and turns into slow, constant period retransmission.






















Plummer & Postel                                                [page 3]


June 1980                                     TCP JSYS Calling Sequences



Error Returns

   When a JSYS does an error return (returns  +1 instead of +2), AC 1
   contains an error code.  This code is an 8-bit number (right
   justified in the 36-bit word) composed as follows:

      Bit Assignments:

         Bit 28:       Error
         Bit 29:       Local
         Bit 30:       Permanent
         Bits 31-35:   Error Number

      The error numbers are:

         0  Unknown Error
         1  Argument Error in JSYS (no access, bad JCN, etc.)
         3  Connection Not Open
         4  Temporarily Out of Resources
         6  Connection Already Exists
         7  Connection Error or Rejected (No such TCB either here or
            there.)
         9  Transmission Timeout
         12 Connection Closed or Closing (Closed remotely.)
         15 Bad Buffer Argument
         17 Bad Argument to CHANL
         20 Funny pointer to STAT (wraps around memory, etc)
         21 Bad Transfer Size to STAT
         29 Cannot change security level (SCSLV)
         31 TCP Not Available

   The Error bit indicates if an error occured, for example error number
   12 might not have the Error bit set in response to a CLOSE call.  The
   Local bit indicates if the situation is local to this host or is due
   to the remote host.  The Permanent Bit indicates if the situation is
   permanent, or temporary.














[page 4]                                                Plummer & Postel


TCP JSYS Calling Sequences                                     June 1980



OPEN (JSYS 742)

   1/  Flags,,Pointer-to-Connection-Block
   2/  Persistence in seconds
   3/  Retransmission parameters

                                  OPEN

   R+1:  failure, code in AC 1
   R+2:  OK, JCN (Job Connection Number) in AC 1

   Flags:

      ForceSync:

         On to force synchronization without any data having been sent.

      Wait:

         Don't return until connection is opened.

      Persistent:

         Keep trying by sending SYN packets periodically.


























Plummer & Postel                                                [page 5]


June 1980                                     TCP JSYS Calling Sequences



CLOSE (JSYS 743)

   1/  Flags,,JCN-or-Pointer

                                 CLOSE

   R+1:  failure, code in AC 1
   R+2:  OK, connection fully closed

   Flags:

      JCNSupplied:

         On if RH of AC 1 has a JCN. Off if RH has Pointer-to-Connection
         Blk.

      Wait:

         Wait for close to happen in both directions.

   Note that if the wait bit is not set, the JCN will remain valid,
   allowing more RECVs to be done.  ABORT may be used to release the
   handle when it has been discovered that the connection has
   terminated.


























[page 6]                                                Plummer & Postel


TCP JSYS Calling Sequences                                     June 1980



SEND (JSYS 740)

   1/  Flags,,JCN or Pointer-to-Connection-Block
   2/  0,,Pointer-to-Data-Ring
   3/  Timeout in Seconds (0 for infinite)
   4/  Retransmission parameters

                                  SEND

   R+1:  failure, error code in AC 1
   R+2:  OK, JCN in AC 1

   Flags:

      JCNSupplied:

         On if RH of AC 1 has a JCN. Off if RH has Pointer-to-Connection
         Blk.

      Wait:

         Wait for close to happen in both directions.




























Plummer & Postel                                                [page 7]


June 1980                                     TCP JSYS Calling Sequences



RECV (JSYS 741)

   1/  Flags,,JCN or Pointer-to-Connection-Block
   2/  0,,Pointer-to-Data-Ring

                                  RECV

   R+1:  failure, error code in AC 1
   R+2:  OK, JCN in AC 1

   Flags:

      JCNSupplied:

         On if RH of AC 1 has a JCN. Off if RH has Pointer-to-Connection
         Blk.

      Wait:

         Wait for close to happen in both directions.






























[page 8]                                                Plummer & Postel


TCP JSYS Calling Sequences                                     June 1980



STAT (JSYS 745)

   1/  Flags,,JCN or Pointer-to-Connection-Block
   2/  -N,,Offset into TCB
   3/  -M,,Address in user's space

                                  STAT

   R+1:  failure, error code in AC 1
   R+2:  OK.

   Flags:

      JCNSupplied:

         On if RH of AC 1 has a JCN. Off if RH has Pointer-to-Connection
         Blk.

      Returns statistics:

         This flag causes the TCP to dump words from the statistics area
         rather than a specific TCB. Thus, the JCN is irrelevant.  The
         Source and Destination ACs are updated as if a TCB were being
         dumped.

   If successful min(M, N) words have been transferred from the TCB to
   the caller's space.  The TCB offset identifies where the transfer
   starts and the Address in user space identifies the start of the
   destination area.





















Plummer & Postel                                                [page 9]


June 1980                                     TCP JSYS Calling Sequences



CHANL (JSYS 746)

   1/  Flags,,JCN or Pointer-to-Connection-Block
   2/  Six 6-bit bytes (channel numbers)

                                 CHANL

   R+1:   failure, error code in AC 1
   R+2:  OK.  This fork will receive TCP PSIs

   Flags:

      JCNSupplied

         On if RH of AC 1 has a JCN. Off if RH has Pointer-to-Connection
         Blk.

   Each of the 6-bit bytes may be 77 (octal) if no PSIs are desired for
   the corresponding event.

      Bits  0- 5:   INTRP channel
      Bits  6-11:   RECV buffer done
      Bits 12-17:   SEND buffer done
      Bits 18-23:   Error
      Bits 24-29:   State change (open or close)
      Bits 30-35:   EOL acknowledged (Not implemented)

   PSIs for the above may be dropped or be VERY tardy on heavily loaded
   systems. Some defensive programming is required to guard against
   these problems.  See TCPTST.MAC which checks the buffer rings both
   when a "done" interrupt occurs and periodically.



















[page 10]                                               Plummer & Postel


TCP JSYS Calling Sequences                                     June 1980



ABORT (JSYS 747)

   1/  Flags,,JCN or Pointer-to-Connection-Block

                                 ABORT

   R+1:   error, code in AC 1
   R+2:  OK, connection deleted

   Flags:

      JCNSupplied:

         On if RH of AC 1 has a JCN. Off if RH has Pointer-to-Connection
         Blk.

   The local end of the connection is forgotten.  An attempt to notify
   the remote end is made by sending a RST packet.  Should this not be
   delivered, the other end will discover its half open connection the
   next time it attempts to use it.






























Plummer & Postel                                               [page 11]


June 1980                                     TCP JSYS Calling Sequences



SCSLV (JSYS 744)

   1/  Flags,,JCN or Pointer-to-Connection-Block
   2/  36 bit security value

                                 SCSLV

   R+1:  failure, error code in AC 1
   R+2:  OK.  The security value has been associated with the connection

   Flags:

      JCNSupplied

         On if RH of AC 1 has a JCN. Off if RH has Pointer-to-Connection
         Blk.

   The security value is not interpreted by the TCP (except to see that
   it matches).  The number of bits of the security value actually used
   varries depending on the actual security procedure being in use.  In
   all cases the rightmost bits of the word are used.





























[page 12]                                               Plummer & Postel