{Begin SubSec NS Level One Functions}
{Title NS Level One Functions}
{Text

The functions in this section are used to implement level two and higher NS protocols.  The packets used in the NS protocol are termed Xerox Internet Packets (XIPs).  The functions for manipulating XIPs are similar to those for managing PUPs, so will be described in less detail here.  The major difference is that NS host addresses are 48-bit numbers.  Since Interlisp-D cannot currently represent 48-bit numbers directly as integers, there is an interim form called {lisp NSHOSTNUMBER}, which is defined as a {lisp TYPERECORD} of three fields, each of them being a 16-bit portion of the 48-bit number.


{Begin SubSec Creating and Managing XIPs}
{Title Creating and Managing XIPs}
{Text

There is a record {lisp XIP} that overlays the data portion of an {lisp ETHERPACKET} and describes the format of a XIP.  This record defines the following fields: {lisp XIPLENGTH} (16 bits), {lisp XIPTCONTROL} (transmit control, 8 bits, cleared when a XIP is transmitted), {lisp XIPTYPE} (8 bits), {lisp XIPDESTNET} (32 bits), {lisp XIPDESTHOST} (an {lisp NSHOSTNUMBER}), {lisp XIPDESTSOCKET} (16 bits), and {lisp XIPSOURCENET}, {lisp XIPSOURCEHOST}, and {lisp XIPSOURCESOCKET}, analagously.  The field {lisp XIPCONTENTS} is a pointer to the start of the data portion of the XIP. 


{FnDef {Name ALLOCATE.XIP}
{Text
Returns a (possibly used) XIP.  As with {fn ALLOCATE.PUP}, the header fields are guaranteed to be zero, but there may be garbage in the data portion if the pup had been recycled.
}}


{FnDef {Name RELEASE.XIP} {Args XIP}
{Text
Releases {arg XIP} to the free pool.
}}


}{End SubSec Creating and Managing XIPs}


{Begin SubSec NS Sockets}
{Title NS Sockets}
{Text

As with pups, XIPs are sent and received on a {it socket}.  The same comments apply as with pup sockets ({pageref fn OPENPUPSOCKET}), except that NS socket numbers are only 16 bits.

{FnDef {Name OPENNSOCKET} {Args SKT# IFCLASH}
{Text
Opens a new NS socket.  If {arg SKT#} is {lisp NIL} (the normal case), a socket number is chosen automatically, guaranteed to be unique, and probably different from any socket opened this way in the last 18 hours.  If a specific local socket is desired, as is typically the case when implementing a server, {arg SKT#} is given, and must be a (up to 16-bit) number.  {Arg IFCLASH} governs what to do if {arg SKT#} is already in use, as with {fn OPENPUPSOCKET}.
}}


{FnDef {Name CLOSENSOCKET} {Args NSOC NOERRORFLG}
{Text
Closes and releases socket {arg NSOC}.  If {arg NSOC} is {lisp T}, closes all NS sockets (this must be used with caution, since it will also close system sockets!).  If {arg NSOC} is already closed, an error is generated unless {arg NOERRORFLG} is true.
}}


{FnDef {Name NSOCKETNUMBER} {Args NSOC}
{Text
Returns the socket number (a 16-bit integer) of {arg NSOC}.
}}


{FnDef {Name NSOCKETEVENT} {Args NSOC}
{Text
Returns the {lisp EVENT} of {arg NSOC}.  This event is notified whenever a XIP arrives on {arg NSOC}.
}}

}{End SubSec NS Sockets}


{Begin SubSec Sending and Receiving XIPs}
{Title Sending and Receiving XIPs}
{Text

{FnDef {Name SENDXIP} {Args NSOC XIP}
{Text
Sends {arg XIP} on socket {arg NSOC}.  If any of the {lisp XIPSOURCESHOST}, {lisp XIPSOURCENET}, or {lisp XIPSOURCESOCKET} fields is zero, {fn SENDXIP} fills them in using the NS address of this machine and/or the socket number of {arg NSOC}, as needed.
}}


{FnDef {Name GETXIP} {Args NSOC WAIT}
{Text
Returns the next XIP that has arrived addressed to socket {arg NSOC}.  If there are no XIPs waiting on {arg NSOC}, then {fn GETXIP} returns {lisp NIL}, or waits for a XIP to arrive if {arg WAIT} is {lisp T}.  If {arg WAIT} is an integer, {fn GETXIP} interprets it as a number of milliseconds to wait, finally returning {lisp NIL} if a XIP does not arrive within that time.
}}


{FnDef {Name DISCARDXIPS}
{Args NSOC}
{Text
Discards without examination any XIPs that have arrived on {arg NSOC} and not yet been read by a {fn GETXIP}.
}}


{FnDef {Name EXCHANGEXIPS}
{Args SOC OUTXIP IDFILTER TIMEOUT}
{Text
Useful for simple NS packet exchange protocls.  Sends {arg OUTXIP} on {arg SOC}, then waits for a responding XIP, which it returns.  If {arg IDFILTER} is true, ignores XIPs whose packet exchange ID (the first 32 bits of the data portion) is different from that of {arg OUTXIP}.  {arg TIMEOUT} is the length of time (msecs) to wait for a response before giving up and returning {lisp NIL}.  {arg TIMEOUT} defaults to {var \ETHERTIMEOUT}.{index \ETHERTIMEOUT Var}  {fn EXCHANGEXIPS} discards without examination any XIPs that are currently waiting on {arg SOC} before {arg OUTXIP} gets sent.
}}


}{End SubSec Sending and Receiving XIPs}




{Begin Note}
SubSec Miscellaneous NS Utilities:
need to write and document fns analogous to GETPUPWORD, GETPUPSTRING and friends
{End Note}


{Begin SubSec NS Debugging Aids}
{Title NS Debugging Aids}
{Text

XIPs can be printed automatically by {fn SENDXIP} and {fn GETXIP} analogously to the way pups are.  The following variables behave with respect to XIPs the same way that the corresponding PUP-named variables behave with respect to PUPs: {var XIPTRACEFLG}, {var XIPTRACEFILE}, {var XIPIGNORETYPES}, {var XIPONLYTYPES}, {var XIPPRINTMACROS}.  In addition, the functions {fn PRINTXIP}, {fn PRINTXIPROUTE} and {fn XIPTRACE} are directly analogous to {fn PRINTPUP}, {fn PRINTPUPROUTE}, and {fn PUPTRACE}.

{index XIPTRACEFLG Var}
{index XIPTRACEFILE Var}
{index XIPIGNORETYPES Var}
{index XIPONLYTYPES Var}
{index XIPPRINTMACROS Var}
{index XIPTRACE Fn}
{index PRINTXIP Fn}
{index PRINTXIPROUTE Fn}



}{End SubSec NS Debugging Aids}

}{End SubSec NS Level One Functions}