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