Network Support Encyclopedia 96-1/novell-nsepro-1996-1-cd2.iso/download/netware/spxspc.exe/SPX.DOC

Text File | 1994-11-22 | 85KB | 2,215 lines

NetWare SPX Services

Specification, Semantics and API






Revision:  1.00

Date:  February 9, 1993


















Unpublished Copyright⌐,  Novell, Inc.  All Rights Reserved

No part of this document may be duplicated, revised, translated, localized
or modified in any manner or uploaded or downloaded to or from any
computer system without the prior written consent of Novell, Inc.


This document is the property of Novell, Inc.  It is intended for the
internal use of Novell only.  This document is not to be construed as a
promise by Novell to develop a particular product.   Novell specifically
disclaims any promise to deliver a product conforming to the
specifications contained herein.


Preface

This manual provides a complete protocol reference for the SPX
implementer.  It consists of the SPX reference manual plus annotations.

The SPX reference manual alone provides a complete definition of SPX, but
the terse reference manual style leaves many reasonable questions
unanswered.  Discussions of why certain features are defined the way they
are, and how one might implement some particular feature have no place in
a reference manual, but are of interest to most implementers.  Such
discussions are presented as annotations.

Organization
The SPX reference manual consists of main sections which form the chapters
of this manual.  The reference manual proper is presented in 11 point
Times New Roman font.

_ Embedded annotations are presented in 9 point Arial, indented and
bracketed by a solid and an open square box, like this sentence. _

Acknowledgements
SPX could not have been developed without the use, suggestions, and
constructive criticism of the many NetWare users and developers.  In
addition, SPX is the result of papers and manuals written by a variety of
researchers in the communications and networking fields; particularly the
works on Xerox PARC XNS.

Special thanks to Dale Neibaur and Mark Hurst for the original SPX
implementation that this document describes.  Also the many Novell
Engineers who have written and fixed problems in the various SPX
implementations since the original DOS based SPX.

Edit History
    Revision          Date        Description
    0.90       13 Dec 93        Original draft from SPX II
specification
        1.00        9 Feb 94        Updated to include
server API descriptions and state tables.

Table of Contents

Preface      i
Organization      i
Acknowledgements      i
Edit History      i

Introduction      1
Definition of Key Terminology      1
Windowing Protocol      1
Large Packets      1

SPX Packet Format      3
SPX Header Definition      3
Checksum      3
Length      4
Transport Control      4
Packet Type      4
Destination Network      4
Destination Node      4
Destination Socket      4
Source Network      5
Source Node      5
Source Socket      5
Connection Control      7
Datastream Type      7
Source Connection ID      7
Destination Connection ID      7
Sequence Number      9
Acknowledge Number      9
Allocation Number      9
SPX Acknowledgement Packets      9
Normal SPX ACK      9
SPX Connection Management Packets     10
Connection Request     10
Connection Request ACK     10
Informed Disconnect     11
Informed Disconnect ACK     11

Connection Management     13
Packet Definitions for SPX Connections     13
Session Termination     13
Unilateral Abort     13
Informed Disconnect     13
SPX Watchdog Algorithm     14
Session Watchdog During Connection Establishment     14

Connection ID Numbers     16

Windowing Algorithm     17
Managing Sequence and Acknowledge numbers     17
Acknowledgements     17
Extensive Error Recovery Mechanisms     17
Data Packet Timeout     17
Window Size     18
Additional Resource Requirements     19

Congestion Control Algorithm     20

Calculating Timeouts and Round Trip Time     21
Calculating Round Trip Time     21

Appendix A - State Tables     22
SPX Connection State Table     23
SPX Transmit State Table     24
SPX Receive State Table     25
SPX Watchdog State Table     26

Appendix D - OS API and ECB     27
SPX Connection Establishment Functions     27
SPX Connection Termination Functions     27
SPX Data Transfer Functions     27
SPX Status and Control Functions     27
SPX Structures and Control Constants     28
Event Control Block definition     28
ECB status field completion codes and function return codes     28
SPX header definition     29
SPX connection control flags     29
SPX data stream type field codes     29
SPX_ConnStruct and SPX_ConnStruct2 sStatus field codes     29
Alphabetical SPX Function Descriptions     29
CSPXCancelECB     31
CSPXCancelSessionListen     32
CSPXCheckInstallation     33
CSPXEstablishConnection     34
CSPXGetConnectionStatus     36
CSPXGetConnectionStatus2     38
CSPXGetTimersAndCounters     40
CSPXListenForConnectedPacket     42
CSPXListenForConnection     44
CSPXListenForSequencedPacket     46
CSPXSendSequencedPacket     48
CSPXSetTimersAndCounters     50
CSPXTerminateConnection     52

Appendix E - API Semantics and Characteristics     54

Appendix G - Default, Minimum and Maximum Values     55
Documentation Constants     55
Connection Termination Reason Codes     55

Appendix H - IPX Checksums     56


 1    Introduction

With the introduction of Netware v2.0a in early 1986, NetWare supported a
guaranteed delivery protocol known as Sequenced Packet Exchange or SPX.
It was derived from the XEROX XNS protocol specification known as
Sequenced Packet Protocol or SPP.  This document specifies the SPX
protocol, the differences from the SPP and provides some implementation
details.

The characteristics of the SPX protocol are heavily influenced by the SPX
Application Programming Interface (API).  The API requires in most
instances that the application provide and initialize fields in the SPX
protocol header prior to calling the API function.  This header knowledge
has caused applications to be coded to the discovered implementation
characteristics of SPX rather than to a specification.  These
characteristics are referred to as the semantics of SPX and this document
attempts to identify and classify them.

SPX is considered a transport protocol in the ISO seven layer model.  It
is a guaranteed delivery protocol with packet oriented data transmission
and delivery and has the fundamental architecture necessary to identify
data unit boundaries and to support a transmission sliding window.

1.1    Definition of Key Terminology

SPX is the designator for the protocol.  Host, passive endpoint, and
listener all refer to the network node that is waiting for or has received
a connection request.  Client, active endpoint and requester all refer to
the network node that is making or has made the connection request.
Connection partner refers to the other endpoint and connection endpoint
refers to either endpoint participating in the connection, without respect
to its active or passive status.

1.2    Windowing Protocol

The SPX packet header has fields for managing sequencing, acknowledgments
and transmission window size.  SPX is very packet oriented and the numbers
in these fields are relative to packets rather than to bytes.  For
historical reasons, not completely understood, SPX always uses a
transmission window size of one packet, regardless of the window size
reported by the connection partner.  In later implementations the window
size of one may have been an attempt to not overrun the DOS SPX
implementation.  Under DOS the number of receive buffers posted to the IPX
socket dictated the window size. Having more than one SPX session
multiplexed over an IPX socket lead to the problem of determining the
proper window size for each session.  Since this could not be accurately
determined, the reported window size could not be trusted and other
implementations may have attempted to guard against this using a send
window size of one.

1.3    Large Packets
The original XNS specification defined a network packet size as 576 bytes
in length, allowing 512 bytes of data and 64 bytes header.  IPX does not
enforce this packet size, though it does require that all physical
networks that transmit IPX packets must be able to transmit packets of
this size.  IPX provides very little assistance in determining whether a
larger packet can be used, though all IPX routers will, if possible, route
larger packets.  However, if a network segment is incapable of
transmitting a larger packet, the packet is dropped with no notification
to the originating endpoint.

There are several IPX based services which use larger than 576 byte
packets by using a simple algorithm for determining the packet size.  If
both endpoints share the same physical wire and if the media supports
larger packets, then the largest media packet size is used.  Other IPX
services attempt to determine the end-to-end large packet size by sending
a large packet and having it echoed back.  If the large packet is echoed
back successfully then the application uses the larger packet size.  This
echo procedure requires a recovery mechanism, in case the network
dynamically reconfigures, and the larger packets are no longer viable over
the new route.

SPX is constrained by these features of IPX and as such does not support
larger packets without the application making some determination outside
of the SPX environment.

 2    SPX Packet Format

SPX packet structure consists of a packet header followed by optional
data.  The SPX header contains addressing, sequencing and acknowledgement
information.

2.1    SPX Header Definition

Here is the field definition for the SPX header:

    Description        Length    Type            Value
    Checksum*      2    High-Low Int    0xFFFF if no checksum
    Length*    2    High-Low Uint    42 - 65535
    Transport Control*    1    Ubyte    0 - 16
    Packet Type*    1    Ubyte    5, see detail

    Destination Network*    4    Ubyte 0 - 0xFFFFFFFF, see
detail
    Destination Node*    6    Ubyte    1 - 0xFFFFFFFFFFFE,
"  "
    Destination Socket*    2    High-Low Uint    0 -
0xFFFF, see detail

    Source Network*    4    Ubyte    0 - 0xFFFFFFFF, see
detail
    Source Node*    6    Ubyte    1 - 0xFFFFFFFFFFFE, "  "
    Source Socket*    2    High-Low Uint    0 - 0xFFFF,
see detail

    Connection Control    1    Ubyte        see
explanation
    Datastream Type    1    Ubyte    see explanation
    Source Connection ID    2    High-Low Uint    see
explanation
    Destination Conn. ID    2    High-Low Uint    see
explanation

    Sequence Number    2    High-Low Uint    see
explanation
    Acknowledge Number    2    High-Low Uint    see
explanation
    Allocation Number    2    High-Low Uint    see
explanation
Fields marked with '*' are IPX packet header fields

All numeric fields in an SPX header are in high-low format or "network
order", and the length designator is in number of 8 bit bytes or octets.

2.1.1    Checksum
This field is normally set to 0xFFFF indicating that no checksum was
performed. However, if this field is not 0xFFFF it holds a checksum of the
entire SPX packet, including the SPX header and data.  Checksum
verification is an IPX option that must be specified when the IPX socket
is opened and would therefore cover all SPX connections that are
multiplexed over the IPX socket.  There is no method for SPX to control
this option, and therefore it must be coordinated by the application.

2.1.2    Length
This field contains the length of the complete SPX packet, which is the
length of the header plus the length of the data.  The minimum length of
an SPX packet is 42 bytes, and the maximum length is 65535.

2.1.3    Transport Control
This field is used by IPX routers.  SPX always set this field to zero
before sending any packets.

2.1.4    Packet Type
This field indicates the type of service offered or required by the
packet.  The following values are defined:
    0    Unknown packet type (do not use)
    1    Routing information packet
    2    Echo packet (not currently supported)
    3    Error packet (not currently supported)
    4    Packet exchange packet (normal IPX packet, also used by
SAP)
    5    Sequenced packet (SPX and SPX II)
    17    NetWare Core Protocol standard packet
    20    IPX NetBIOS broadcast

2.1.5    Destination Network
This field contains the network number of the network to which the
destination node belongs.  Networks within an internetwork are assigned
unique 4 byte network numbers by a network administrator.

When this field is 0, the destination node is assumed to reside on the
same network as the source node.  Such a packet is not processed by an IPX
router.

2.1.6    Destination Node
This field contains the physical address of the destination node.  Not all
LAN topologies use the same size address field.  A node on an ethernet
network requires all 6 bytes to specify its address, while a node on an
arcnet network requires only 1 byte. If a physical network needs less than
6 bytes to specify a node address, the address occupies the least
significant portion of the field and the most significant bytes are set to
zero.

A broadcast node address (0xFFFFFFFFFFFF) is explicitly disallowed by
SPX.  All connection requests to this node address will be ignored.

2.1.7    Destination Socket
This field contains the socket address of the packet's destination
process.  Sockets route packets to different processes within a single
node.  The following socket numbers are reserved by the IPX protocol suite:

    2h        Echo protocol socket
    3h        Error handler packet

In addition Novell has defined and reserved the following sockets for use
by NetWare:

    0x451        NetWare Core Protocol
    0x452        NetWare Service Advertising Protocol
    0x453        NetWare Routing Protocol
    0x456        NetWare Diagnostics Protocol

NOTE:  Novell administers a list of sockets that are well-known in all IPX
environments. Software developers writing IPX, SPX or SPX II based
value-added packages that require well-known addresses, should obtain
socket assignments from Novell.  Dynamic sockets within the IPX suite
begin at 0x4000 and end at 0x7FFF and well-known sockets assigned by
Novell begin at 0x8000.

2.1.8    Source Network
This field contains the network number of the network to which the source
node belongs. Networks within an internetwork are assigned unique 4 byte
network numbers by a network administrator.

This field may contain a value of zero which means the physical network to
which the source node is connected is unknown.  All packets with a zero in
this field that pass through a IPX router will have this field set to
their source network number.  Thus, whenever a packet is received from a
node on a different network, the source network field is always set
properly.  Packets whose source and destination nodes are on the same
network may contain a zero in this field.

2.1.9    Source Node
This field contains the physical address of the source node.  Not all
physical LAN topologies use the same size address field.  A node on an
ethernet network requires all 6 bytes to specify its address, while a node
on an arcnet network requires only 1 byte. If a physical network needs
less than 6 bytes to specify a node address, the address should occupy the
least significant portion of the field and the most significant bytes
should be set to zero.

2.1.10    Source Socket
This field contains the socket address of the process that transmits the
packet.  In a client server dialogue, the server node usually listens on a
specific socket for connection requests.  In such a case, the source
socket is not necessarily the same or even significant.  All that matters
is that the server sends its replies to the source socket contained in the
connection request packet.
As in the case of destination sockets, these numbers can be static or
dynamic.  Source socket numbers follow the same conventions as those for
destination sockets.

2.1.11    Connection Control
This field contains single-bit flags used by SPX and SPX II to control the
bidirectional flow of data across a connection.
    Value    Symbol        Description
    0x01    XHD        Reserved by SPX II for extended
header
    0x02    RES1        Undefined, must be 0
    0x04    NEG        SPX II negotiate size
request/response, must be 0 for SPX
    0x08    SPX2        SPX II type packet, must be 0 for
SPX
    0x10    EOM        Set by an SPX client to indicate
end of message.
    0x20    ATN        Reserved for attention indication
(Not supported by SPX)
    0x40    ACK        Set to request the receiving
partner acknowledge that this packet has been received.  Acknowledgement
requests and responses are handled by SPX.
    0x80    SYS        Set to indicate a packet is a
system packet.  System packets are internal SPX packets, are not delivered
to the application, and do not consume sequence numbers.

2.1.12    Datastream Type
This field is a 1 byte flag that indicates the type of data found in the
packet.  For SPX the following types are defined:
    0x00-0x7F        Defined by the client.
    0x80-0xFD        Reserved
    0xFE            End of connection notification
    0xFF            End of connection acknowledge

NOTE:  Originally 0x00-0xFD were available for SPX application use,
however, to be consistent with the SPX II specification, these values are
now recommended.

2.1.13    Source Connection ID
This field contains a connection identification number assigned by SPX at
the packet's source and was generated during connection establishment.

2.1.14    Destination Connection ID
This field contains a connection identification number assigned by SPX at
the packet's destination and was generated during connection
establishment.  On a connection request this field is set to 0xffff.

Connection ID numbers are used to demultiplex incoming packets from
multiple connections arriving on the same socket.  All currently active
connections and all recent connections on a given machine are guaranteed
to have unique connection ID numbers.

See section on Connection ID Numbers for additional detail on how
connection ID numbers are generated and the bounds of uniqueness.  Also
see Connection Management for a description of how Connection ID numbers
are used during connection establishment.

2.1.15    Sequence Number
This field keeps a count of packets exchanged in one direction on the
connection.  Each side of the connection keeps its own count.  The number
wraps to zero after reaching 0xFFFF.   SPX acknowledgement packets have
this field set to the sequence number of the most recently sent data
packet.

See section on Windowing Algorithm for additional detail on how sequence
number, acknowledge number and allocation number work together.

2.1.16    Acknowledge Number
This field is used by SPX to indicate the sequence number of the next
packet expected from the connection partner.  Any packet with a sequence
number less than the specified acknowledge number has been correctly
received and need not be retransmitted.

2.1.17    Allocation Number
This field is used by SPX to identify to the connection partner the
largest sequence number that can be sent and is used to control the number
of unacknowledged packets outstanding in one direction on the connection.
SPX only sends packets until the sequence number equals the last
allocation number received from the connection partner.

2.2    SPX Acknowledgement Packets

SPX is a guaranteed delivery service and requires that the connection
endpoints verify that each packet has been received.  The SPX ACK is an
SPX header with the SYS bit set in Connection Control and Acknowledge
Number set to acknowledge the packet(s) received (all packets up to but
not including the acknowledge number have been received) andocation
Number set to open/adjust the transmission window.


2.2.1    Normal SPX ACK
The SPX ACK packet consists only of an SPX header with these fields set:

    Description            Value
      Checksum            See SPX Header Definition
      Length                42
      Transport Control        0
      Packet Type            5
      Destination Address        See SPX Header Definition
      Source Address            See SPX Header Definition
      Connection Control        SYS bit set
      Datastream Type        0
      Source Connection ID        > 0 and != 0xFFFF
     ::╩( Destination Conn. ID        > 0 and != 0xFFFF
      Sequence Number        current #
      Acknowledge Number        current #
      Allocation Number        m

2.3    SPX Connection Management Packets

In order for SPX to establish and maintain a connection between two
endpoints, a specific connection request packet exchange must take place.
SPX does not support an orderly connection termination, but supports two
different types of termination.  One type requires a packet exchange
between the endpoints while the second type does not. The primary
connection management packets are:
   _    Connection Request
   _    Connection Request ACK
   _    Informed Disconnect
   _    Informed Disconnect ACK

2.3.1    Connection Request
The SPX Connection Request packet has the following SPX header with these
fields set:

    Description            Value
      Checksum            See SPX Header Definition
      Length                42
      Transport Control        0
      Packet Type            5
      Destination Address        See SPX Header Definition
      Source Address            See SPX Header Definition
      Connection Control        SYS, & ACK bits set
      Datastream Type        0
      Source Connection ID        > 0 and != 0xFFFF
      Destination Conn. ID        0xFFFF
      Sequence Number        0
      Acknowledge Number        0
      Allocation Number        m
  "m" is indicative of the current window size, where the window size is
calculated as Alloc - Ack + 1.  Therefore, to indicate no available window
during connection establishment Alloc would need to be set to -1
(0xFFFF).  ECB based implementations of SPX determined this value based on
the number of ECBs posted to the IPX socket before the connection request
was made.

2.3.2    Connection Request ACK
The SPX Connection ACK is a standard ACK packet and has the following SPX
header with these fields set:

    Description            Value
      Checksum            See SPX Header Definition
      Length                42
      Transport Control        0
      Packet Type            5
      Destination Address        See SPX Header Definition
      Source Address            See SPX Header Definition
      Connection Control        SYS bit set
      Datastream Type        0
      Source Connection ID        > 0 and != 0xFFFF
      Destination Conn. ID        > 0 and != 0xFFFF
      Sequence Number        0
      Acknowledge Number        0
      Allocation Number        m


2.3.3    Informed Disconnect
The SPX Informed Disconnect or Terminate Request packet has the following
SPX header with these fields set:

    Description            Value
      Checksum            See SPX Header Definition
      Length                42
      Transport Control        0
      Packet Type            5
      Destination Address        See SPX Header Definition
      Source Address            See SPX Header Definition
      Connection Control        ACK bits set
      Datastream Type        0xFE
      Source Connection ID        > 0 and != 0xFFFF
      Destination Conn. ID        > 0 and != 0xFFFF
      Sequence Number        current #
      Acknowledge Number        current #
      Allocation Number        m

2.3.4    Informed Disconnect ACK
The SPX Informed Disconnect ACK packet has the following SPX header with
these fields set:

    Description            Value
      Checksum            See SPX Header Definition
      Length                42
      Transport Control        0
      Packet Type            5
      Destination Address        See SPX Header Definition
      Source Address            See SPX Header Definition
      Connection Control        None
      Datastream Type        0xFF
      Source Connection ID        > 0 and != 0xFFFF
      Destination Conn. ID        > 0 and != 0xFFFF
      Sequence Number        0
      Acknowledge Number        (Informed Disconnect Seq # + 1)
      Allocation Number        m

 3    Connection Management

SPX is a connection oriented guaranteed delivery service and tracks state
information about the endpoints utilizing the connection.

3.1    Packet Detions for SPX Connections

Assuming a normal SPX to SPX connection, the sequence of packets on the
wire is as follows:

    Packet originator        Packet Definition
      Client            ∙î  SPX Connection Request
      Host              SPX Connection ACK

The client issues an SPX Connection Request with the SYS bit set.  If the
host was waiting for a connection request the host returns a standard SPX
Connection ACK and then informs the application of the connection request.

3.2    Session Termination

When one endpoint of an SPX session decides to terminate the connection
there are two ways of accomplishing it:  Unilateral Abort, or Informed
Disconnect.

3.2.1    Unilateral Abort
A Unilateral Abort should only be used when one endpoint has detected a
connection failure, through retry failure or watchdog failure.  In this
case there is no benefit in sending an Informed Disconnect, since the
connection partner is not responding there would be no way to confirm that
the Informed Disconnect had arrived.  A Unilateral Abort assumes that the
connection partner has failed or will be able to detect that the
connection is no longer valid.

3.2.2    Informed Disconnect
An Informed Disconnect terminates the session immediately without giving
the connection partner an opportunity to complete any transmissions.  The
Informed Disconnect differs from the Unilateral Abort by exchanging
disconnect packets between the endpoints.  An Informed Disconnect has the
following packet sequence:

    Packet originator        Packet Definition
      Endpoint 1          SPX Informed Disconnect
      Endpoint 2          SPX Informed Disconnect Ack

The Informed Disconnect packet is queued for transmission behind all other
data packets and given the SPX window of one, is not transmitted until all
data packets have been acknowledged.  It should be retried as a normal
data packet and if transmission failure is detected and all retries are
exhausted then the endpoint may perform a Unilateral Abort. An Informed
Disconnect packet is not subject to window closure (See Additional
Resource Requirements).

An Informed Disconnect may cause data to be lost.  This happens if data is
currently in the output queue for the endpoint that receives the Informed
Disconnect.  SPX sends the Informed Disconnect ACK immediately upon
receiving the Informed Disconnect and then cleans up the session.  Any
data packets that may be queued for transmission are returned to the
application.

NOTE:  An extended protocol environment such as STREAMS based TLI which
requires data queues to be flushed to ensure the Informed Disconnect  is
properly processed, may also cause both outbound and inbound data to be
lost.

3.3    SPX Watchdog Algorithm

The watchdog routine is a passive element in SPX.  Watchdog packets are
sent only if there is a period of time with no traffic on the session.
There are two timeout values associated with the watchdog.  The first,
VERIFY_TIMEOUT (default is 3 seconds) is the time SPX will wait after a
data transmit before sending a watchdog packet.  Any packet that is sent
resets this timer to 0.  The second timeout value, ABORT_TIMEOUT (default
30 seconds) is the time SPX will wait after receiving a packet from its
connection partner before the connection is aborted. Any packet that
arrives for a session will reset the watchdog timer for that session.
This includes system packets as well as user data packets (ie. incoming
data, an incoming ACK for transmitted data or an incoming ACK to a
watchdog packet would reset the timer).

A watchdog request packet consists of an SPX header with the SYS and the
ACK bits set. The receiver will respond to this packet with a watchdog
acknowledgement packet.  A watchdog acknowledgement packet consists of an
SPX header with the SYS bit set and is indistinguishable from an normal
SPX ACK.  The Sequence, ACK and Alloc fields contain the current values.

If the watchdog algorithm has sent repeated watchdog request packets
(default 10, every 3 seconds for 30 secondsd has not received a
response from the connection partner, then SPX assumes that the partner is
unreachable and performs a Unilateral Abort to terminate the connection.

See the annotation in the section Calculating Window Size for additional
information how the watchdog assists in window management.

3.4    Session Watchdog During Connection Establishment

SPX considers a connection to exist once an endpoint has both connection
IDs.  This happens after the receipt of a Connection Request at the
passive endpoint, or the receipt of a Connection ACK at the active
endpoint.  Once this exchange has taken place the connection is
established and the watchdog timeÅm╩rs begin running.

 4    Connection ID Numbers

Connection ID numbers are assigned as follows.  Each endpoint determines a
random starting point for connection ID numbers when that endpoint first
becomes active.  When a new connection ID number needs to be generated,
SPX increments the current number and then checks to see if the new number
is in use.  If the new number is in use, SPX again increments the number
and checks to see if the new number is in use.  This process continues
until an ID number is found that is not in use.

_ As a performance improvement it is suggested that the implementation use
Connection ID as a direct index into the session table.  This can be
accomplished by incrementing the Connection ID and wrapping at the current
maximum table size.  Implementations where the configured table size can
be changed while running should ensure that table size reduction does not
move the end of the table below the last currently used slot.

In an attempt to prevent a reboot of the system from allocating the same
Connection ID numbers in the same order it is suggested that the
implementation initialize the Connection ID number with a random value.
This number might be taken from the system clock, if available. _


 5    Windowing Algorithm

Though the SPX header has fields for managing the transmission window, SPX
does not currently utilize these fields fully.  SPX uses a transmission
window of one, requests an ACK for each data packet sent, and does not
send the next data packet until the ACK packet has arrived.

5.1    Managing Sequence and Acknowledge numbers

The sequence number is an ever increasing (except when wrapping past zero)
number that identifies the order of the data being sent and received.  The
acknowledge number is also an ever increasing number identifying all the
data packets that have been successfully received. The acknowledge number
also indicates the sequence number of the next packet that is expected by
the receiving endpoint.  The first data packet sent has Sequence Number
zero and the ACK sent in response to that data packet has Acknowledge
Number set to one.

_ There is an easy way to manage these two values (there are actually two
sets of values, the numbers for sending and the numbers expected when
receiving).  When sending a data packet, increment Sequence Number after
placing the data packet on the "to be sent" queue or if no queueing
mechanism is used, upon return from the send function.  When generating an
ACK, set Acknowledge Number in the ACK packet to the received data
packet's Sequence Number plus one. _


5.2    Acknowledgements

A normal SPX acknowledgement is defined as an SPX header with the SYS bit
set in Connection Control, the Sequence Number set to the current
transmission sequence number and Acknowledge Number set to the next packet
expected by the receiver.

An acknowledgement can be "piggy-backed" on a data packet with Acknowledge
Number set to the next packet expected by the receiver (ACKs can be
"piggy-backed" on any packet, data, system or watchdog).

5.3    Extensive Error Recovery Mechanisms

When standard SPX detects an error it does not know how to handle, it
aborts the session. However, SFT III has introduced the need for better
SPX error handling, to correctly handle an SFT III switch over.

5.Data Packet Timeout
During normal operation if the connection partner fails to acknowledge a
packet, the sender must retry the packet RETRY_COUNT/2 times, each time
increasing the round trip time value by 50%, up to MAX_RETRY_DELAY
(default is 5 seconds).  If the packet still has not been acknowledged,
the sender must attempt to locate a new route to the connection partner.
If a new route is located then reset the retry count and retransmit.  If
no new route was found, then continue to retransmit until all retries are
exhausted and if unsuccessful the connection is aborted with a Unilateral
Abort.

On route failure each endpoint must determine the failure independently
and this only happens during data send.

In short, the steps are:
   _    Retry the data packet RETRY_COUNT/2 times, increasing the
timeout value before each retry
  ¥aJ _    Attempt to locate a new route
   _    If new route found resume sending data packet RETRY_COUNT times
   _    If a new route is not found, retry the data packet the
remaining RETRY_COUNT/2 times and if unsuccessful perform a Unilateral
Abort.
   _    After a successful retransmission on the new route, resume
normal operation.

_ The algorithm is using 1/2 the RETRY_COUNT in order to give preference
to the possibility of route failure over endpoint failure or network
congestion.  By retrying less before attempting to relocate a new route
the protocol will recover faster on very dynamic networks.  This is better
than just reducing the RETRY_COUNT to a smaller number, because it still
provides more retries and longer delays between retries on congested
networks. _



5.4    Window Size

It is the responsibility of the receiver at each endpoint to calculate the
window size for packets
received by that endpoint.  The receiver then communicates this number to
the transmitter via the allocation number field in the SPX II header by
adding the calculated window size to the current sequence number.  The
receiver is free to change the window size during the session with the
stipulation that the receiver can never reduce an already granted window.
The transmitter is allowed to send packets while the sequence number is
less than or equal to the allocation number.

SPX currently ignores the reported allocation window size and uses a
window of one.

_ The reason that the advertised window size cannot be reduced has to do
with the processing of the allocation and sequence numbers.  The
transmitter is allowed to send packets until the sequence number is equal
to the allocation number.  If the receiver tried to reduce the allocation
number after the transmitter had already sent a packet with that sequence
number, the transmitter would perceive that the window had grown to nearly
64k packets.  The only way for the receiver to reduce the window size is
to allow the acknowledge number to grow without increasing the allocation
number.

For example, the receiver could not send a packet indicating an allocation
number of 1210 and then send a subsequent packet indicating an allocation
number of 1208.  However the receiver could send a subsequent packet
indicating an allocation number of 1210 even though the acknowledge number
may have increased by 2, effectively reducing the window size by 2. _

During window management it is possible, because of resource limitation or
other reason, for the receiving side to close the data receive window
completely by sending a packet indicating that the next sequence number
expected is greater than the next allocation number.  When this happens
the receiver must be prepared to reopen the window after the flow control
condition has cleared, and must handle the possibility that the reopen
packet may be lost.

_ Once a window has been closed it is reopened with either a normal data
packet or a system packet indicating an allocation number greater than or
equal to the sequence number.  If this reopen information is attached to a
data packet the normal data retry mechaniill ensure delivery.
However, if the data flow over the connection is primarily one way or the
window also happens to be closed in the opposite direction, the reopen
information will be included in a system packet which is not retransmitted
and may be lost.

If the reopen packet is lost, the watchdog will eventually send a series
of system packets that will reopen the window, however there will be a
delay of up to VERIFY_TIMEOUT (default 3 seconds) before this occurs. When
window management is reopening a window with a system packet it could
request the watchdog system to increase the frequency of the watchdog
packets.  The watchdog system would remain in this increased frequency
state until a data packet arrives. _

There are several options for the receiver to select a window size.  The
implementor is free to select any algorithm as long as the protocol
specification is not violated by the algorithm.

_ Perhaps the simplest approach is to select a hard coded value and use
it.  A number between 4 and 16 is q¡╢∞probably appropriate under most
circumstances.  A slightly more complex approach would have specific
values for different conditions.  For example, a value of 4 for "local"
LANs (less than 4 hops away) and a value of 8 for all others.  One could
also select an algorithm based on the reported time to net.  One such
algorithm would be to use the reported time to net (in IBM PC "ticks")
shifted left 2, with a maximum of value of 16.  More complex algorithms,
such as a heuristic determination based on dropped packets, are certainly
possible, but are beyond the scope of this document. _

5.5    Additional Resource Requirements

THIS IS NOT TRUE FOR SPX THOUGH IT PROBABLY SHOULD BE.

Only data packets are subjected to window size constraints, all system
packets and the Informed Disconnect packet can be sent even if the
receiving side has closed its receive window. This implies that there are
resources, considered system resources, which are not included in the size
of the window reported to the connection partner.

 6    Congestion Control Algorithm

SPX has a very simple congestion control algorithm.  Don't send until the
ACK for the previous packet has arrived.  Thus if the previous packet is
delayed or dropped due to congestion SPX will not flood the net with
packets.  However, delays that are greater than RETRY_TIMEOUT would cause
SPX to add to the congestion by retransmitting unnecessarily.

 7    Calculating Timeouts and Round Trip Time

7.1    Calculating Round Trip Time

SPX does not attempt to track round trip time closely.  It calculates
round trip time RTT by using the "time to net" value returned from the
nearest router.  This value is doubled and then  3/4 of a second fudge
factor is added.  Each time a retry is necessary, the current RTT is
increased by 50% and bounded by MAX_ROUND_TRIP_TIMEOUT.  RTT is tracked
and modified on a per session basis.

 8    Appendix A - State Tables

The following state tables have unique state numbers for each state.  In
addition, each table is identified to assist in state transitions that
move from one table to another. These identifiers are:
    C    SPX Connection State Table
    T    SPX Transmit State Table
    R    SPX Receive State Table
    W    SPX Watchdog State Table

Each state table represents a different state machine.  There is one state
machine that handles the connection events, one for transmitting data, one
for receiving data and one which monitors the connection to detect
connection failure, during idle time.  Only the first state machine
operates until a connection is established, after which the other three
state machines process the connection.  These are independent state
machines, however by sharing information between them, certain
optimizations in packet utilization and minimization can occur.

SPX Connection State Table

States
\
Events    Uninit

state    C0    Socket
Open
state    C1    Socket
w/ rcvbufs
state    C2    Listening

state    C3    Listening
w/ rcvbufs
state    C4    Connecting

state    C5    Connecting
w/ rcvbufs
state    C6
Socket Open Request    state    C1
Listen for Connect Req        state    C3    state    C4    state    C3    state    C4
Post Rcvbufs        state    C2    state    C2    state    C4    state    C4    state    C6    state    C6
Connect Request        state    C5    state    C6
Incoming Connect Pkt                state    C3'2    state    C4'2
Outgoing Connect Ack                state    T73
state    R7
state    W23    state    T7
state    R7
state    W23
Incoming Connect Ack                                                state    T7
state    R7
state    W23    state    T7
state    R7
state    W23
Retry timer
Fired                        state    C5    state    C6
Retry count
Exhausted                        state    C1    state    C2
Request Canceled            state    C21    state    C1    state    C2
Socket
Closed        state    C0    state    C0    state    C0    state    C0    state    C0    state    C0

        Note1:    If there are still receive buffers posted to SPX
after the cancellation, then stay in state 2, otherwise change to state 1.
        Note2:    State 3' and state 4' indicate that a minor state
transition has occurred into a transmit ACK state.
        Note3:    If multiple listen for connection buffers have been
posted to SPX, only one session transitions to Data xfr state, while all
others remain in state C3 or C4.  At this point the transmitting,
receiving and watchdog state machines begin handling the connection and
are thus represented by the transition to three separate states.

SPX Transmit State Table

States
\
Events    Data xfr1


state    T7    Data xfr
Tx_win
closed
state    T8    Data xfr
Tx_win
open
state    T9    Data xfr
Send packet
state    T10    Data xfr
wait for ACK
state    T11    Data xfr
Call ESR

state    T12    Discn
Send

state    T13    Discn
wait for ACK
state    T14    Discn
Call ESR

state    T15
Win Closure    state    T8    state    T8    state    T8
Win Open    state    T9    state    T9    state    T9
Send data
Request        state    T8    state    T10
Transmit
Complete                state    T11            state    T14
Incoming
Data ACK                    state    T12
Return from ESR                        state    T7            state    T12
Send disconnect Request        state    T8    state    T13
Incoming
Discon ACK                                state    T15
Retry timer
Fired                    state    T10            state    T13
Retry count
Exhausted                state    C12            state    C12
Request
Canceled
Socket
Closed    state    C0    state    C0    state    C0    state    C0    state    C0    state    C0    state    C0
state    C0    state    C0

        Note1:    Data xfr is a pseudo state that only serves as a
place holder in the state table to ensure proper state transition based on
already available information.
        Note2:    If there are receive buffers still posted to SPX
then this state transition is actually to state 2, however, for table
simplicity state 1 is specified.

SPX Receive State Table
States
\
Events    Data xfr1


state    R7    Data xfr
Rx_win
Closed
state    R16    Data xfr
Rx_open
Win
state    R17    Data xfr
Rx_win
Open
state    R18    Data xfr
Call ESR

state    R19    Data xfr
Send ACK

state    R20    Discn
Send ACK

state    R21    Discn
Call ESR

state    R22
Post RcvBufs    state    R17    state    R17
Incoming
Data                state    R19
Return from ESR                    state    R20            state    12
Transmit ACK
Complete            state    R18            state    R7
Incoming
Disconnect                state    R21
Transmit
Discn ACK Complete                            state    R22
Request
Canceled                state    R183
Socket
Closed    state    C0    state    C0    state    C0    state    C0    state    C0    state    C0    state    C0
state    C0

        Note1:    Data xfr is a pseudo state that only serves as a
place holder in the state table to ensure proper state transition based on
already available information.
        Note2:    If there are receive buffers still posted to SPX
then this state transition is actually to state 2, however, for table
simplicity state 1 is specified.
        Note3:    If there are still receive buffers posted to SPX
after the cancellation, then stay in state 18, otherwise change to state
16.

SPX Watchdog State Table
States
\
Events    Data xfr
Idle1

state    W23    Data xfr
Send watchdog

state    W24    Data xfr
Send watchdog
ACK request
state    W25
Watchdog timer2    state    W24
Verify timer3    state    W25
Abort timer4    state    15
Transmit complete        state    W23    state    W23

        Note1:    The Data xfr idle state is a non-event state, and is
defined to be a state entered when a period of non-activity exists on the
SPX session.  It essentially represents a combination of state 8 and 9,
with no incoming or outgoing packets to process.
        Note2:    The watchdog timer is reset to it's starting value
each time a packet is sent.
        Note3:    The verify timer is reset to it's starting value
each time a packet is received.
        Note4:    The abort timer is reset to it's starting value each
time a packet is received.
        Note5:    If there are receive buffers still posted to SPX
then this state transition is actually to state 2, however, for table
simplicity state 1 is specified.

 9    Appendix D - OS API and ECB

9.1    SPX Connection Establishment Functions

The following functions are used when establishing SPX connections.
   _    CSPXEstablishConnection - Establish an SPX connection with a
listening endpoint.
   _    CSPXListenForConnection - Inform SPX to allow and wait for an
incoming connection request.
   _    CSPXListenForSequencedPacket - Provide a receive buffer to SPX
for receiving data for any SPX connection on a specific IPX socket.

9.2    SPX Connection Termination Functions

The following functions are used when terminating SPX connections.
   _    CSPXCancelSessionListen - Discontinue waiting for an incoming
SPX connection request.
   _    CSPXAbortConnection - Terminate an existing SPX connection
without informing the connection partner.
   _    CSPXTerminateConnection - Terminate an existing SPX connection
and inform the connection partner.

9.3    SPX Data Transfer Functions

The following functions are used for data transfer on established SPX
connections.
   _    CSPXListenForConnectedPacket - Provide a receive buffer to a
specific SPX connection.
   _    CSPXListenForSequencedPacket - Provide a receive buffer to SPX
for receiving data for any SPX connection on a specific IPX socket.
   _    CSPXSendSequencedPacket - Send a data packet to the specified
existing SPX connection partner.

9.4    SPX Status and Control Functions

   _    CSPXCancelECB - Cancel the receive ECB previously submitted to
SPX.
   _    CSPXCheckInstallation - Determine if SPX is available and
retrieve configuration information.
   _    CSPXGetConnectionStatus - Obtain connection information from
SPX.
   _    CSPXGetConnectionStatus2 - Obtain connection information from
SPX.
   _    CSPXGetTimersAndCounters - Obtain default configuration
information from SPX.
   _    CSPXSetTimersAndCounters - Set the default configuration
information inside of SPX.

9.5    SPX Structures and Control Constants

Event Control Block definition
The comment characters in the IPX_ECB structure have the following
meanings:
           s - this field must be filled in prior to a send
    r - this field must be filled in prior to a receive
    R - this field is reserved
    A - this field may be used when the ECB is not in use by IPX/SPX
    q - the application may read this field

typedef struct
{
   void                *fragAddress;
   unsigned long        fragSize;
} ECBFrag;
typedef struct IPX_ECBStruct
{
   struct IPX_ECBStruct    *next;            /* A */
   struct IPX_ECBStruct    *prev;            /* A */
   unsigned short        status;            /* q */
   unsigned long        ESRAddress;        /* sr */
   unsigned short        lProtID;            /* R */
   unsigned char        protID [6];        /* R */
   unsigned long        boardNumber;        /* R */
   unsigned char        immediateAddress [6];    /* R */
   unsigned char        driverWS [4];        /* R */
   unsigned long        ESREBXValue;        /* R */
   unsigned short        socket;            /* sr */
   unsigned short        protocolWorkspace;    /* R */
   unsigned long        dataLen;            /* q */
   unsigned long        fragCount;        /* sr */
   ECBFrag        fragList [2];        /* sr */
} IPX_ECB;

ECB status field completion codes and function return codes
#define SPX_OK                    0x0000
#define SPX_CONNECTION_TERMINATED    0xFFEC
#define SPX_CONNECTION_FAILED        0xFFED
#define SPX_INVALID_CONNECTION        0xFFEE
#define SPX_CONNECTION_TABLE_FULL    0xFFEF
#define SPX_SOCKET_NOT_OPEN        0xFFF0
#define SPX_SOCKET_ALREADY_OPEN        0xFFF1
#define SPX_ECB_CANNOT_BE_CANCELEDFF9
#define SPX_EVENT_CANCELED        0xFFFC
#define SPX_PACKET_OVERFLOW        0xFFFD
#define SPX_MALFORMED_PACKET        0xFFFE
SPX header definition
typedef struct
{
   unsigned short        checksum;        /* hi-lo */
   unsigned short        packetLen;        /* hi-lo */
   unsigned char        transportCtl;
   unsigned char        packetType;
   unsigned long        destNet;            /* hi-lo */
   unsigned char        destNode[6];
   unsigned short        destSocket;        /* hi-lo */
   unsigned long        sourceNet;        /* hi-lo */
   unsigned char        sourceNode[6];
   unsigned short        sourceSocket;        /* hi-lo */

   unsigned char        connectionCtl;
   unsigned char        dataStreamType;
   unsigned short        sourceConnectID;    /* hi-lo */
   unsigned short        destConnectID;        /* hi-lo */
   unsigned short        sequenceNumber;    /* hi-lo */
   unsigned short        ackNumber;        /* hi-lo */
   unsigned short        allocNumber;        /* hi-lo */
} SPX_HEADER;

SPX connection control flags
#define SPX_CC_SYS                0x80
#define SPX_CC_ACK                0x40
#define SPX_CC_EOM                0x10

SPX data stream type field codes
/* 0 thru 127 (0 - 0x7f) are available for application use */
SPX_DS_TERMINATE                0xFE
SPX_DS_TERMINATE_ACK            0xFF

SPX_ConnStruct and SPX_ConnStruct2 sStatus field codes
#define SPX_SSTATUS_ABORTED        0x00
#define SPX_SSTATUS_WAITING        0x01
#define SPX_SSTZô<ATUS_STARTING        0x02
#define SPX_SSTATUS_ESTABLISHED        0x03
#define SPX_SSTATUS_TERMINATING        0x04

9.6    Alphabetical SPX Function Descriptions

The following pages contain alphabetical function descriptions for the SPX
functions.

CSPXAbortConnection

Name
CSPXAbortConnection - Terminate an existing SPX connection without
informing the connection partner.

Synopsis
        LONG CSPXAbortConnection(
                LONG sessionID);


Description
This function will terminate an existing SPX connection by aborting the
session. The connection partner is not informed of the termination.  The
sessionID was returned from a call to CSPXEstablishConnection or
CSPXListenForConnection.

If a connection has not been fully established (ie. CSPXListenForConnection
 has been called and no connection request has been received), then this
function acts the same as CSPXCancelSessionListen.  The status field of
the event control block (ECB) that was handed to CSPXListenForConnection
will be set to SPX_CONNECTION_FAILED and if the ESRAddress field is
non-zero the Event Service Routine (ESR) will be called.

If CSPXListenForConnectedPacket was used to provide ECB receive buffers to
SPX, then all the ECB receive buffers will be released by SPX and the
status field in the ECB will be set to SPX_CONNECTION_FAILED and if the
ESRAddress field is non-zero the ESR will be called, for each ECB.


Diagnostics
Returns SPX_OK on success or one of the following on failure:
        SPX_INVALID_CONNECTION

See Also
    CSPXTerminateConnection, CSPXCancelSessionListen

CSPXCancelECB

Name
CSPXCancelECB - Cancel the receive ECB previously submitted to SPX.

Synopsis
        LONG CSPXCancelECB(
                IPX_ECB *ecb);

Description
If the event control block (ECB) pointed to by ecb was submitted to SPX
through a call to CSPXListenForSequencedPacket or
CSPXListenForConnectedPacket then control of the ECB will be returned to
the application.  Also the status field of the ECB will be set to
SPX_EVENT_CANCELED.

SPX stores information in the ECB that is necessary to successfully cancel
the ECB.  If this information is invalid because the ECB has not been
previously submitted to SPX or SPX does not currently control the ECB, or
if the information has been changed by the application prior to the call
to CSPXCancelECB then the function will fail.

Diagnostics
Returns SPX_OK on success and one of the following on failure:
        SPX_INVALID_CONNECTION
        SPX_ECB_CANNOT_BE_CANCELED

See Also
    CSPXCancelSessionListen

CSPXCancelSessionListen

Name
CSPXCancelSessionListen - Discontinue waiting for an incoming SPX
connection request.

Synopsis
        LONG CSPXCancelSessionListen(
                IPX_ECB *ecb);

Description
If the event control block ) pointed to by ecb was submitted to SPX
through a call tßJ+ho CSPXListenForConnection then control of the ECB will be
returned to the application.  Also the status field of the ECB will be set
to SPX_EVENT_CANCELED.

SPX stores information in the ECB that is necessary to successfully cancel
the ECB.  If this information is invalid because the ECB has not been
previously submitted to SPX or SPX does not currently control the ECB, or
if the information has been changed by the application prior to the call
to CSPXCancelSessionListen then the function will fail.

Diagnostics
Returns SPX_OK on success and one of the following on failure:
        SPX_INVALID_CONNECTION
        SPX_ECB_CANNOT_BE_CANCELED

See Also
    CSPXCancelECB

CSPXCheckInstallation

Name
CSPXCheckInstallation - Determine if SPX is available and retrieve
configuration information.

Synopsis
        LONG CSPXCheckInstallation(
                WORD *version,
                LONG *maxConnections);

Description
If SPX is available on this machine then CSPXCheckInstallation will return
the major and minor SPX version number in the variable pointed to by
version.  The high order byte, (version & 0xff00) >> 8, is the major SPX
version number, and the low order byte, version & 0x00ff, is the minor SPX
version number.  The maximum number of connections that SPX can support is
returned in the variable pointed to by maxConnections and the return value
from CSPXCheckInstallation is the current number of SPX connections in use.

Diagnostics
Returns the current number of SPX connections in use if SPX is loaded,
otherwise, all three return values are 0.

See Also
    CSPXGetTimersAndCounter, CSPXSetTimersAndCounters

CSPXEstablishConnection

Name
CSPXEstablishConnection - Establish an SPX connection with a listening
endpoint.

Synopsis
        LONG CSPXEstablishConnection(
                BYTE retryCount,
                BYTE watchDog,
                LONG *sessionID,
                IPX_ECB *ecb);

Description
This function will request an SPX connection with the endpoint specified
in the destination address fields of the event control block (ECB)
identified by ecb. If the endpoint is waiting for SPX connection requests,
having called CSPXListenForConnection, then a bi-directional communication
connection will be established between the two endpoints.

The application can override SPX defaults by specifying new values in the
retryCount and watchDog parameters.  The range of values for retryCount is
0-255, where 0 indicates use SPX system configured default value, and any
other number is used as the maximum number of times SPX will retry a
transmission before considering the connection down.  Setting watchDog to
zero, indicates do not monitor the SPX connection by sending keep-alive
packets periodically, while setting watchDog to ENABLE_WATCHDOG, indicates
that keep-alive packets and monitoring should be used.  Note:  There is no
SPX system default value for watchDog.

Before calling this function, the following fields must contain valid
information in ecb:
       _    ESRAddress - may contain a 0 or the address of a
routine that will be called when the connection is established or aborted.
       _    socket - must contain the socket obtained from CIPXOpenSocketRTag.
       _    fragCount - must be set to 1
       _    fragList - fragment 0 points to a 42-byte buffer
containing an SPX header.

    The SPX header must contain valid information in the following
fields:
        destNet - 4 byte network address of the destination
endpoint
        destNode - 6 byte node address of the destination endpoint
        destSocket - 2 byte socket number of the destination
endpoint
All destination address fields are in high low byte order.  This means
that the most significant byte is in the lowest memory address, while the
least significant byte is in the highest memory address.

SPX allows applications to receive data packets in a fully asynchronous
fashion, therefore this is a non-blocking call and execution control will
return to the calling application before the connection is fully
esished.  Once the connection has been established or the retry count
has been exhausted, the status field of the ECB that was handed to
CSPXEstablishConnection will be set to the appropriate value and if the
ESRAddress field is non-zero the Es₧
│vent Service Routine (ESR) will be
called.

On return the application must test the return code.  If an invalid ECB or
invalid socket are passed, the call can fail.  In this case the status
field of the ECB is set to the same value as the return code, however the
ESR is not called.

    Valid values for the status field of ecb are:
        SPX_OK
        SPX_CONNECTION_FAILED

Diagnostics
Returns SPX_OK on success or one of the following on failure:
        SPX_MALFORMED_PACKET
        SPX_PACKET_OVERFLOW    (This is incorrectly returned)
        SPX_MALFORMED_PACKET    (This is the correct one)
        SPX_SOCKET_NOT_OPEN
        SPX_CONNECTION_TABLE_FULL
    Note:  The failure codes will also be placed in the status field of the
ECB.

See Also
    CSPXListenForConnection

CSPXGetConnectionStatus

Name
CSPXGetConnectionStatus - Obtain connection information from SPX.

Synopsis
        LONG CSPXGetConnectionStatus(
                LONG sessionID,
                void *buffer);

Description
Return connection information to the application.  The following 40 byte
buffer is returned in the location pointed to by buffer.  The sessionID
was returned from a call to CSPXEstablishConnection or
CSPXListenForConnection.

        typedef struct SPX_ConnStruct
        {
           unsigned char        sStatus;
           unsigned char        sFlags;
           unsigned
short        sSourceConnectID;    /* hi-lo */
           unsigned short        sDestConnectID;    /*
hi-lo */
           unsigned
short        sSequenceNumber;    /* hi-lo */
           unsigned
short        sAckNumber;        /* hi-lo */
           unsigned
short        sAllocNumber;        /* hi-lo */

           unsigned
short        sRemoteAckNumber;    /* hi-lo */
           unsigned
short        sRemoteAllocNumber;    /* hi-lo */

           unsigned
short        sLocalSocket;        /* Native */
           unsigned
char        sImmediateAddress[6];    /* Net order */

           unsigned
long        sRemoteNet;        /* Net order */
           unsigned
char        sRemoteNode[6];        /* Net order */
           unsigned
short        sRemoteSocket;        /* Net order */

           unsigned char        sRetransmitCount;
           unsigned char        sRetransmitMax;
           unsigned
short        sRoundTripTimer;    /* hi-lo */
           unsigned
short        sRetransmittedPackets;    /* hi-lo */
           unsigned
short        sSuppressedPackets;    /* hi-lo */
        } SPX_SESSION1;


On return the following fields contain very useful information:
        sStatus            Contains one of the
following status values:

_    SPX_SSTATUS_WAITING - waiting for connection request

_    SPX_SSTATUS_STARTING - waiting for response to
CSPXEstablishConnection

_    SPX_SSTATUS_ESTABLISHED - data transfer in full duplex mode

_    SPX_SSTATUS_TERMINATING - waiting for acknowledgment to terminate
request
        sRemoteNet            Network address of
connection partner
        sRemoteNode[6];        Node address of connection
partner
        sRemoteSocket        Socket address of connection
partner
        sRetransmittedPackets    Number of retries that have
occurred during the life of this session
        sSuppressedPackets    Number of duplicate packets that
have been tossed during the life of this session



Diagnostics
Returns SPX_OK on success or one of the following on failure:
        SPX_INVALID_CONNECTION

See Also
    CSPXGetConnextionStatus2

CSPXGetConnectionStatus2

Name
CSPXGetConnectionStatus2 - Obtain connection information from SPX.

Synopsis
        LONG CSPXGetConnectionStatus2(
                LONG sessionID,
                void *buffer,
                LONG bufferSize );


Description
Return connection information to the application.  The sessionID was
returned from a call to CSPXEstablishConnection or CSPXListenForConnection
.  The following 60 byte buffer is returned in the location pointed to by
buffer, however if bufferSize is less than 60 then only bufferSize bytes
are returned in the location pointed to by buffer. For new applications
this function should be used instead of CSPXGetConnectionStatus e it
protects against buffer overflow and provides more information and more of
it is in native machine order.

        typedef struct SPX_ConnStruct2
        {
           unsigned char           sStatus;
           unsigned char           sFlags;
           unsigned short
sSourceConnectID;        /* hi-lo */
           unsigned short
sDestConnectID;        /* hi-lo */
           unsigned short
sSequenceNumber;        /* hi-lo */
           unsigne.9>d short          sAckNumber;        /*
hi-lo */
           unsigned short          sAllocNumber;        /*
hi-lo */

           unsigned short
sRemoteAckNumber;        /* hi-lo */
           unsigned short          sRemoteAllocNumber;    /*
hi-lo */

           unsigned short          sLocalSocket;        /*
Native order */
           unsigned char           sImmediateAddrees[6];    /*
Net order */

           unsigned long
sRemoteNet;            /* Net order */
           unsigned char
sRemoteNode[6];        /* Net order */
           unsigned short
sRemoteSocket;        /* Net order */

           unsigned char           sRetransmitCount;
           unsigned char           sRetransmitMax;
           unsigned short
sRoundTripTimer;        /* Native order */
           unsigned short
sRetransmittedPackets;    /* Native order */
           unsigned short
sSuppressedPackets;        /* Native order */

           unsigned short
sLastReceiveTime;        /* Native order */
           unsigned short
sLastSendTime;        /* Native order
*/
           unsigned short
sRoundTripMax;        /* Native order */
           unsigned short
sWatchdogTimeout;        /* Native order */
           unsigned long
sSessionXmitQHead;        /* Native pointer */
           unsigned long
sSessionXmitECBp;        /* Native pointer */
        } SPX_SESSION2;

On return the following fields contain very useful information:
        sStatus            Contains one of the
following status values:

_    SPX_SSTATUS_WAITING - waiting for connection request

_    SPX_SSTATUS_STARTING - waiting for response to
CSPXEstablishConnection

_    SPX_SSTATUS_ESTABLISHED - data transfer in full duplex mode

_    SPX_SSTATUS_TERMINATING - waiting for acknowledgment to terminate
request
        sRemoteNet            Network address of
connection partner
        sRemoteNode[6];        Node address of connection
partner
        sRemoteSocket        Socket address of connection
partner
        sRetransmittedPackets    Number of retries that have
occurred during the life of this session
        sSuppressedPackets    Number of duplicate packets that
have been tossed during the life of this session

Diagnostics
Returns SPX_OK on success or one of the following on failure:
        SPX_INVALID_CONNECTION

See Also
    CSPXGetConnectionStatus

CSPXGetTimersAndCounters

Name
CSPXGetTimersAndCounters - Obtain default configuration information from
SPX.

Synopsis
        void CSPXGetTimersAndCounters(
                int *abortTimeout,
                int *listenTimeout,
                int *verifyTimeout,
                int *retryCount,
                int *configuredSessions,
                int *openSessions);

Description
Get several configuration timers and counters from SPX that are used as
the beginning defaults for new sessions.  Each parameter points to a
location that receives the following information.  If a NULL pointer is
passed for any parameter then SPX will not return the current value for
that variable.

        abortTimeout    Amount of time in PC tics that must
elapse without receiving a packet from the connection partner before SPX
will abort the connection.
        listenTimeout    Amount of time in PC tics that must
elapse without receiving a packet from the connection partner before SPX
will send an "are you there" packet.
        verifyTimeout    Amount of time in PC tics that must
elapse without sending a packet to the connection partner before SPX will
send a "keep alive packet".
        retryCount        Number of times SPX will retry a
send without receiving an ACK from the connection partner before SPX will
abort the connection.
        configuredSessions    Total number of SPX connections
that can be established, waiting for connection completion or listening
for connection requests at a given time.
        openSessions    Current number of SPX connections that are established,
waiting for connection completion or listening for connection requests at
the current time.

Diagnostics
No return value.


See Also
    CSPXSetTimersAndCounters

CSPXListenForConnectedPacket

Name
CSPXListenForConnectedPacket - Provide a receive buffer to a specific SPX
connection.

Synopsis
        LONG CSPXListenForConnectedPacket(
                IPX_ECB *ecb,
                LONG sessionID);

Description
This function delivers an event control block (ECB) and the buffer space
it identifies to SPX for the purpose of receiving a data packet and the
function is identical to CSPXListenForSequencedPacket except that it
allows you to post an ECB for the specific SPX session specified by
sessionID, which was returned from a successful call to
CSPXEstablishConnection or CSPXListenForConnection.  The function returns
execution control to the calling application.

     Before calling this function, the following fields must contain
valid information in ecb:
       _    ESRAddress - may contain a 0 or the address of a
routine that will be called when data has been placed in the buffer
defined by fragList.
       _    fragCount - must be at least 1
       _    fragList - must describe a buffer large enough to
receive the data expected from the connection partner.  Fragment 0 must be
at least 42 bytes long; the size of an SPX packet header.

SPX allows applications to receive data packets in a fully asynchronous
fashion. Therefore, this function only identifies the given ECB for use in
receiving data packets; the function does not wait for an actual packet to
be received.

The ECB will remain in SPX control until an incoming data, connection
termination or connection abort event occurs.  At the occurrence of one of
these events, the status field of the ECB will be set to SPX_OK,
SPX_CONNECTION_TERMINATED, or SPX_CONNECTION_FAILED respectively and if
the ESRAddress field is non-zero the Event Service Routine (ESR) will be
called.

When the application regains control of a valid ECB, there are two fields
in the SPX header, connectionCtl and dataStreamType that may contain
information set by the application at the other end of the connection.
connectionCtl could have the end of message flag SPX_CC_EOM set, which
implies that this data packet is the last packet of a larger transmission
service data unit (TSDU) or large message.  Also dataStreamType can
contain any application defined value between 0 and 127 inclusive.
    Although SPX provides the function CSPXTerminateConnection for
terminating a connection, it is up to the application to detect that this
has occurred by testing the dataStreamType field of each incoming data
packet for the value SPX_DS_TERMINATE.

If status is set to SPX_PACKET_OVERFLOW then the ECB did not define
sufficient buffer space to receive the incoming data, however, as much of
the data as would fit into the ECB is valid, the ESR will be called if
applicable and the connection is still active.

Diagnostics
Returns SPX_OK on success or one of the following on failure:
        SPX_INVALID_CONNECTION
        SPX_MALFORMED_PACKET

See Also
    CSPXListenForSequencedPacket

CSPXListenForConnection

Name
CSPXListenForConnection - Inform SPX to allow and wait for an incoming
connection request.

Synopsis
        LONG CSPXListenForConnection(
                BYTE retryCount,
                BYTE watchDog,
                LONG *sessionID,
                IPX_ECB *ecb);

Description
This function is used to inform SPX that the application is willing to
accept connection requests from other SPX endpoints.  The application can
specify in retryCount the number of times SPX will resend a data packet or
can use the system default by passing a zero.  A non-zero value for the
watchDog flag will inform SPX to keep track of the connection once it is
established by sending periodic "keep alive", and "are you there" system
packets.  A connection identification number will be returned in the
location pointed to by sessionID.  This value must be retained and is
required by other SPX calls.

Before calling this function, the following fields must contain valid
information in ecb:
       _    ESRAddress - may contain a 0 or the address of a
routine that will be called when the connection is established or aborted.
       _    socket - must contain the socket obtained from CIPXOpenSocketRTag.

SPX allows applications to receive connection requests in a fully
asynchronous fashion. Therefore, this function only identifies the given
ECB for use in receiving the connection request; the function does not
wait for an actual packet to be received.

The ECB will remain in SPX control until an incoming connection request,
or connection abort event occurs.  At the occurrence of one of these
events, the status field of the ECB will be set to SPX_OK, or
SPX_CONNECTION_FAILED respectively and if the ESRAddress field is non-zero
the Event Service Routine (ESR) will be called.

A call to CSPXAbortConnection or CSPXCancelSessionListen will cause SPX to
release the ECB and no longer accept connection requests for the
application.

Diagnostics
Returns SPX_OK on success or one of the following on failure:
        SPX_CONNECTION_TABLE_FULL
        SPX_SOCKET_NOT_OPEN

See Also
    CSPXAbortConnection, CSPXCancelSessionListen, CSPXEstablishConnection

CSPXListenForSequencedPacket

Name
CSPXListenForSequencedPacket - Provide a receive buffer to SPX for
receiving data for any SPX connection on a specific IPX socket.

Synopsis
        LONG CSPXListenForSequencedPacket(
                IPX_ECB *ecb);

Description
This function delivers an event control block (ECB) and the buffer space
it identifies to SPX for the purpose of receiving a data packet and the
function is identical to CSPXListenForConnectedPacket except that it
allows you to post an ECB for all SPX sessions being multiplexed on a
specific IPX socket.  Using this function ECBs can be given to SPX prior
to any connections being established.  The function returns execution
control to the calling application.

SPX allows applications to receive data packets in a fully asynchronous
fashion. Therefore, this function only identifies the given ECB for use in
receiving data packets; the function does not wait for an actual packet to
be received.

     Before calling this function, the following fields must contain
valid information in ecb:
       _    ESRAddress - may contain a 0 or the address of a
routine that will be called when data has been placed in the buffer
defined by fragList.
       _    socket - must contain the socket obtained from CIPXOpenSocketRTag.
       _    fragCount - must be at least 1
       _    fragList - must describe a buffer large enough to
receive the data expected from the connection partner.  Fragment 0 must be
at least 42 bytes long; the size of an SPX packet header.

The ECB will remain in SPX control until an incoming data, connection
termination or connection abort event occurs.  At the occurrence of one of
these events, the status field of the ECB will be set to SPX_OK,
SPX_CONNECTION_TERMINATED, or SPX_CONNECTION_FAILED respectively and if
the ESRAddress field is non-zero the Event Service Routine (ESR) will be
called.

When the application regains control of a valid ECB, there are two fields
in the SPX header, connectionCtl and dataStreamType that may contain
information set by the application at the other end of the connection.
connectionCtl could have the end of message flag SPX_CC_EOM set, which
implies that this data packet is the last packet of a larger transmission
service data unit (TSDU) or large message.  Also dataStreamType can
contain any application defined value between 0 and 127 inclusive.
    Although SPX provides the function CSPXTerminateConnection for
terminating a connection, it is up to the application to detect that this
has occurred by testing the dataStreamType field of each incoming data
packet for the value SPX_DS_TERMINATE.

If status is set to SPX_PACKET_OVERFLOW then the ECB did not define
sufficient buffer space to receive the incoming data, however, as much of
the data as would fit into the ECB is valid, the ESR will be called if
applicable and the connection is still active.

Diagnostics
Returns SPX_OK on success or one of the following on failure:
        SPX_INVALID_CONNECTION
        SPX_MALFORMED_PACKET
        SPX_SOCKET_NOT_OPEN

See Also
    CSPXListenForConnectedPacket

CSPXSendSequencedPacket

Name
CSPXSendSequencedPacket - Send a data packet to the specified existing SPX
connection partner.

Synopsis
        LONG CSPXSendSequencedPacket(
                LONG sessionID,
                IPX_ECB *ecb);

Description
This function will send the packet specified by ecb to the connection
partner specified by sessionID.  The sessionID was returned from a call to
CSPXEstablishConnection or CSPXListenForConnection.

SPX allows applications to send data in a fully asynchronous fashion.
Therefore, this function provides the given event control block (ECB) for
SPX to use until the packet has been acknowledged by the connection
partner; the function does not wait for the send to complete.

     Before calling this function, the following fields must contain
valid information in ecb:
       _    ESRAddress - may contain a 0 or the address of a
routine that will be called when the data in the buffer defined by fragList
 has been transmitted and acknowledged.
       _    fragCount - must be at least 1
       _    fragList - must describe the buffer(s) that make up
the intended data to send.  Fragment 0 must be at least 42 bytes long; the
size of an SPX packet header.

There are two fields in the SPX header, connectionCtl and dataStreamType
that can be set by the application.  connectionCtl should be initialized
to 0 or if this data packet is the last packet of a larger transmission
service data unit (TSDU) or large message, this field can be set to
SPX_CC_EOM.  dataStreamType can be set to any value between 0 and 127
inclusive.

The ECB will remain in SPX control until the data packet has been
acknowledged by the connection partner or until the retry count has been
exhausted.  When either of these events occurs, the status field of the
ECB will be set to SPX_OK or SPX_CONNECTION_FAILED respectively and if the
ESRAddress field is non-zero the Event Service Routine (ESR) will be
called.

Diagnostics
Returns SPX_OK on success or one of the following on failure:
        SPX_INVALID_CONNECTION
        SPX_PACKET_OVERFLOW

See Also
    CSPXListenForSequencedPacket, CSPXListenForConnectedPacket

CSPXSetTimersAndCounters

Name
CSPXSetTimersAndCounters - Set the default configuration information
inside of SPX.

Synopsis
        LONG CSPXSetTimersAndCounters(
                int abortTimeout,
                int listenTimeout,
                int verifyTimeout,
                int retryCount,
                int configuredSessions);

Description
Set several configuration timers and counters inside SPX that are used as
the beginning defaults for new sessions.  Each parameter identifies the
new value for the respective control variable.  Passing a value of zero
indicates, "leave previous value unchanged".

        abortTimeout        Amount of time in PC tics that
must elapse without receiving a packet from the connection partner before
SPX will abort the connection. Original system default value:  540 tics
(30 seconds).
        listenTimeout        Amount of time in PC tics
that must elapse without receiving a packet from the connection partner
before SPX will send an "are you there" packet.  Original system default
value:  108 tics (6 seconds).
        verifyTimeout        Amount of time in PC tics
that must elapse without sending a packet to the connection partner before
SPX will send a "keep alive packet".  Original system default value:  54
tics (3 seconds).
        retryCount        Number of times SPX will retry a
send without receiving an ACK from the connection partner before SPX will
abort the connection.  Original system default value:  10 retries (total
11 send attempts).
        configuredSessions    Total number of SPX connections
that can be established, waiting for connection completion or listening
for connection requests at a given time.  Original system default value:
2000 connections (fixed value in 4.10).

Diagnostics
No return value.

See Also
    CSPXGetTimersAndCounters

CSPXTerminateConnection

Name
CSPXTerminateConnection - Terminate an existing SPX connection and inform
the connection partner.

Synopsis
        LONG CSPXTerminateConnection(
                LONG sessionID,
                IPX_ECB *ecb);

Description
This function will terminate an existing SPX connection by sending a
terminate connection request to the connection partner.  The sessionID was
returned from a call to CSPXEstablishConnection or CSPXListenForConnection.

SPX allows applications to terminate connections in a fully asynchronous
fashion. Therefore, this function only informs SPX and provides the given
ECB for use in terminating the connection; the function does not wait for
the termination to complete.

Before calling this function, the application must initialize the ECB's
ESRAddress, fragCount, and fragList fields.  The first fragment in fragList
 must be at least 42 bytes long, which is the size of an SPX header.

The ECB will remain in SPX control until the termination packet has been
acknowledged by the connection partner or until the retry count has been
exhausted.  When either of these events occurs, the status field of the
ECB will be set to SPX_OK or SPX_CONNECTION_FAILED respectively and if the
ESRAddress field is non-zero the Event Service Routine (ESR) will be
called.

If a connection has not been fully established (ie. CSPXListenForConnection
 has been called and no connection request has been received), then this
function acts the same as CSPXCancelSessionListen.  The status field of
the event control block (ECB) that was handed to CSPXListenForConnection
will be set to SPX_CONNECTION_FAILED and if the ESRAddress field is
non-zero the Event Service Routine (ESR) will be called.

If CSPXListenForConnectedPacket was used to provide ECB receive buffers to
SPX, then all the ECB receive buffers will be released by SPX and the
status field in the ECB will be set to SPX_CONNECTION_FAILED and if the
ESRAddress field is non-zero the ESR will be called, for each ECB.



Diagnostics
Returns SPX_OK on success or one of the following on failure:
        SPX_INVALID_CONNECTION
        SPX_PACKET_OVERFLOW

See Also
    CSPXTerminateConnection, CSPXCancelSessionListen

 10    Appendix E - API Semantics and Characteristics

   _    The sending and receiving sides of an application assume that
the exact packet sent is the same packet received.
   _    Length of packets and hardware capabilities are assumed.
   _    There is an implied state in the receipt of a particular
packet.
   _    Very few applications use the end of message EOM bit

 11    Appendix G - Default, Minimum and Maximum Values

Documentation Constants
Throughout the document the following constants are used to indicate some
value.  The table below provides the default, minimum and maximum values
for each constant.
    Constant            Default        Min        Max
    RETRY_COUNT        10            3        50
    MIN_RETRY_DELAY    0  Zero means use standard algorithm.  See Calculating
Timeouts and Van Jacobsen Average and Mean Deviation Calculations.
            1 ms        60 seconds
    MAX_RETRY_DELTA    5 seconds        1 second    60
seconds
    MAX_RETRY_DELAY    (calculated from MIN_RETRY_DELAY and
MAX_RETRY_DELTA)
    VERIFY_TIMEOUT        3 seconds        3
seconds    5 minutes
    ABORT_TIMEOUT        30 seconds        30
seconds    50 minutes


Connection Termination Reason Codes
A connection can be terminated for several reasons.  The following
constants represent those reasons and provide the value that SPX II must
generate.

SPX_CONNECTION_TERMINATED    0xec    A disconnect inform packet
was received from the connection partner.
SPX_CONNECTION_FAILED    0xed    Watchdog timer detected failure,
or retry count reached zero during a send operation
SPX_PACKET_OVERFLOW        0xfd    Internal consistency check
failed, usually an indication that packet size negotiation failed to
negotiate correctly.
SPX_MALFORMED_PACKET    0xfe    Secondary internal consistency
check failed.  Usually used to report to application that an
implementation bug has been detected.

 12    Appendix H - IPX Checksums

With the introduction of NetWare SFT III v3.11, it became necessary to
provide checksum support for NetWare Core Protocol (NCP) packets.  IPX is
a datagram service and there is no way of "negotiating" whether the two
endpoints support checksums before the first packet is sent, so NCP
negotiates this option and then if both endpoints support checksums NCP
tells IPX to checksum the packets.  SPX II like NCP also has an option
negotiation mechanism during connection establishment.  If the endpoints
negotiate that checksums are to be used, the checksum algorithm is:

   _    Initialize the checksum field of the IPX header to zero
   _    Summation (add with carry) of all words (16 bits) in the
packet, with the words being picked up as "little endian" (Intel order)
unsigned values.
   _    If the number of bytes in the packet is odd, the high order
byte necessary for the last word summation is set to zero.
   _    Add in final overflow indication (carry flag).
   _    Negate (1's complement)
   _    Store in IPX header checksum field

To verify the checksum the steps are similar:

   _    Summation (add with carry) of all words (16 bits) in the
packet, with the words being picked up as "little endian" (Intel order)
unsigned values.
   _    If the number of bytes in the packet is odd, the high order
byte necessary for the last word summation is set to zero, then add in
final overflow indication (carry flag).
   _    Add in final overflow indication (carry flag).
   _    The result should be -1, if not an error has occurred.

The default negotiation value for checksums is NO checksums.  If an
application wants to negotiate checksums with its connection partner it
can do so using the TLI t_optmgmt function and by setting the
spxIISessionFlags field of the SPX2_OPTIONS structure to
SPX_SF_IPX_CHECKSUM.

If the implementation of SPX II at both endpoints support IPX checksums
and if both the host and client applications have requested IPX checksums,
then SPX II will checksum every packet after the session is in data
transfer state.  Once both endpoints agree that IPX checksums will be used
a packet with 0xFFFF in Checksum must still be accepted.  This allows for
a retransmitted Session Setup packet or for a delayed Session Setup ACK.

Index

Abort    13, 14, 18, 26, 40, 42, 44, 46, 50, 55
ACK    7, 9-11, 13-15, 17, 20, 23-26, 29, 40, 50, 56
Acknowledge Number    3, 9-12, 17, 18
Allocation Number    3, 9-12, 18, 19
Checksum    3, 9-11, 29, 56
Congestion    18, 20
Connection Ack    10, 13, 15
Connection Control    3, 7, 9-11, 17, 29
Connection ID    3, 7, 9-11, 16
Connection ID Numbers    7, 16
Connection Management    7, 10, 13
Connection Request    1, 5, 7, 10, 13, 14, 27, 30, 32, 37, 39, 44, 52
Daa Transfer State    56
Datastream Type    3, 7, 9-11
Default    14, 17, 19, 27, 34, 40, 44, 50, 55, 56
Destination Connection ID    7
Destination Network    3, 4
Destination Node    3, 4
Destination Socket    3, 4
Disconnect    10-14, 19, 24, 25, 55
Extended Acknowledge    7, 14
Header Definition    3, 9-11, 29
Informed Disconnect    10-14, 19, 30
Large Packets    1
Length    2-4, 9-11, 54
Maximum    4, 16, 19, 33, 34, 55
Minimum    4, 55
Negotiate Size Request    7
Negotiation    55, 56
Packet Definition    13
Packet Type    3, 4, 9-11
Retry    13, 17-21, 23, 24, 34, 35, 40, 48, 50, 52, 55
Round Trip Time    17, 21
Sequence Number    3, 7, 9-14, 17-19
Session Setup    56
Session Termination    13
Session Watchdog    14
Source Connection ID    3, 7, 9-11
Source Network    3, 5
Source Node    3-5
Source Socket    3, 5, 6
Timeout    14, 17-21, 55
TLI    14, 56
Transport Control    3, 4, 9-11
Unilateral Abort    13, 14, 18
Watchdog    13-15, 17, 19, 22, 23, 26, 34, 44, 55
Window    1, 9, 10, 13, 14, 17-19