home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Network Support Encyclopedia 96-1
/
novell-nsepro-1996-1-cd2.iso
/
download
/
netware
/
spxspc.exe
/
SPX.DOC
next >
Wrap
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