SPX Design Enhancements to the NetWare Requester for OS/2 (v1.3)

Bryan R. Clark 
Systems Engineer 
Systems Engineering Division

Robert Perry 
Senior Technical Writer 
Systems Engineering Division

Abstract: 
This AppNote contains information for developers who write applications using 
Novell's Sequenced Packet Exchange (SPX) in the OS/2 environment.  It 
explains recent enhancements to SPX with the March 1991 release of the 
NetWare Requester for OS/2 v1.3, including general design improvements as 
well as specific changes to data structures and the Application Programming 
Interface (API).  



Disclaimer

Novell, Inc. makes no representations or warranties with respect to the 
contents or use of these Application Notes (AppNotes) or of any of the 
third#party products discussed in the AppNotes. Novell reserves the right to 
revise these AppNotes and to make changes in their content at any time, 
without obligation to notify any person or entity of such revisions or 
changes. These AppNotes do not constitute an endorsement of the third#party 
product or products that were tested. Configuration(s) tested or described 
may or may not be the only available solution. Any test is not a 
determination of product quality or correctness, nor does it ensure 
compliance with any federal, state or local requirements. Novell does not 
warranty products except as stated in applicable Novell product warranties or 
license agreements.

Copyright { 1991 by Novell, Inc., Provo, Utah. All rights reserved.

As a means of promoting NetWare AppNotes, Novell grants you without charge 
the right to reproduce, distribute and use copies of the AppNotes, provided 
you do not receive any payment, commercial benefit or other consideration for 
the reproduction or distribution, or change any copyright notices appearing 
on or in the document.

Contents

Introduction		55

Overview of Improvements to the OS/2 Requester		55

Design Enhancements		55

ECBs Linked to Connection		55

Problems Solved		55

SPX API Enhancements		56

Removal of the Socket-based Listen API		56

Other APIs Dropped		56

Modified APIs		57

New APIs		57

Structures Changed		57

ECB Structure Changes		57

Connection Status Structure Changes		58

SPX Throughput Increased and Memory Reduced		58

Improved Buffer Management		59

Summary of SPX Changes		60

Appendix A		61

Acknowledgements		61

Introduction

This AppNote is addressed to developers who write SPX applications that run 
under OS/2.  The changes to the application programming interface (API) and 
structures are explained briefly in this document.  For developers needing 
more detail, an appendix at the end of the AppNote lists the Software 
Developer's Kit (SDK) which includes the complete SPX specification for OS/2 
workstations.

Overview of Improvements to the OS/2 Requester 

As part of the continuing effort to enhance the functionality of Novell OS/2 
products, an enhanced NetWare Requester for OS/2 (v1.3) was released with 
NetWare v3.11.  Release 1.3 of the Requester provides enhancements to the SPX 
API, an increase in SPX throughput, a significant reduction in memory 
requirements, and improved buffer management.

Design Enhancements

ECBs Linked to Connection

From its inception, SPX has always been a connection-based protocol. However, 
because of the strong coupling of a socket to a connection, the two notions 
became almost synonymous.  This led to the convention of linking Event 
Control Blocks (ECBs) to the socket rather than the connection. The new 1.3 
Requester SPX driver now links ECBs only to connections.

Problems Solved

Previously, when multiplexing both socket-based and connection-based 
applications on the same socket, there were problems. First was the matching 
of incoming received packets to listen ECBs. SPX could not properly determine 
if the incoming packet was destined for the socket or connection. Since ECBs 
are now linked only to a connection, this matching problem has been solved.

Secondly, when multiplexing on the same socket, remote machines could not 
determine the number of listen ECBs available. For example, look at the 
configuration shown in Figure 1. Suppose a socket on A has two connections 
(one to B and one to C), and that it has posted four listen ECBs on the 
socket. In this situation, B would think that there are four ECBs available, 
and so would C. Thus, if both B and C wanted to send at the same time, there 
would be eight incoming packets and only four listen ECBs to receive them. 
Obviously, this would result in errors that require retransmission. Now that 
ECBs are posted on the connection, A would post two ECBs to each connection.  


: Old method of multiple connections on the same socket. 

By having ECBs linked to the connection rather than to a socket, the problem 
of running out of listen ECBs, as described in Figure 1, is now solved as 
well.

SPX API Enhancements

The SPX APIs have been updated to remove the usage of sockets where 
connections should be used. Several of the APIs were modified to better 
support the connection-based protocol. Other APIs were removed because their 
functionality existed elsewhere. 

Removal of the Socket-based Listen API

Due to its use of the socket parameter, the SPXListenForSequencedPacket API 
has been removed. It should be replaced by SPXListenForConnectionPacket, 
which correctly uses a connection parameter instead of a socket for posting 
ECBs.

Other APIs Dropped

Some of the APIs have been dropped because their functionality is now 
provided elsewhere.  The functions of SPXGetTime can now be accessed with 
DOSGetTimeAndDate.  The function of SPXCleanUp is now handled by 
SPXTerminateConnection, since cleanup is now associated with a connection.

Modified APIs

Several APIs were modified to support the SPX enhancements.  Both the 
SPXOpenSocket and SPXCloseSocket now return IPX error codes, which will 
require IPXError.H to included.  Also note that SPX_ SUCCESSFUL has been 
chaged to 0x3000.  This may require logic changes in your application's code. 
 

SPXCleanup is no longer available to the application, but this functionality 
has been included in the SPXTerminateConnection call.  SPXCloseSocket no 
longer does clean up. Before closing a connection, a semaphore should be set 
and SPXTerminateConnection called. Once the semaphore is cleared, you can 
call SPXCloseSocket.  In a more minor change, SPXGetVersion no longer returns 
revDate; the revision date can now be obtained by using NVER.EXE.

New APIs

With the changes in SPX, new APIs have been introduced.  The first of these, 
SPXECBErrorCheck, enables or disables extensive error checking on ECBs, 
including extensive listings of errors encountered.  

An additional pair of APIs, SPXEstablishConnection2 and 
SPXListenForConnection2, introduce the new ListenECB parameter.  These APIs 
ensure that a listen ECB is preposted to a connection before it is 
established.  Previously, if a remote partner was trying to send, SPX would 
block the send waiting for a listen ECB to be posted.  With the new APIs the 
first packet can be sent immediately after establishing the connection.  This 
also reduces the number of LSL buffers used and minimizes SPX timeouts or 
retransmitions. 

Structures Changed

ECB Structure Changes

The ECB structure itself has been modified. Minor changes involved moving 
HSEM from its position in the ECB's Reserved structure (at offset 10) to its 
own place at offset 34 (the Reserved structure remains in place for future 
use), and removing Connection Number from the ECB's Protocol Workspace 
structure.  Figure 2 shows the old and new ECB structure.

: The SPX Event Control Block structure, before and after modification    

Connection Status Structure Changes

The structure of SPXGetConnectionStatus has also been changed.  The 
LocalSocket (offset 32) and SupressedPackets (offset 54) fields were deleted. 
 The RemoteSequenceNumber was added (at offset 12) to facilitate buffer 
management.  Also, the RetransmitCount was renamed to RetryCount (offset 44). 
 Figure 3 shows the old and the new versions of the SPXGetConnectionStatus 
structure.

SPX Throughput Increased and Memory Reduced

The new SPX provides an increase in performance. It also minimizes the use of 
LSL buffers and simplifies the LSL buffer management. The amount of memory 
required to load the SPX driver has been reduced to a fraction of what it 
used to be.

: The SPXGetConnectionStatus structure, before and after modificiation 

Improved Buffer Management

During an SPX call, the memory segment containing the ECB buffer is now 
locked, preventing relocation of memory. An application must not change the 
ECB fields while an SPX call is being made. The application should use a 
semaphore to wait for the completion of the SPX call.  Alternatively, by 
passing a NULL for the ECB semaphore handle and polling the ECBStatus field, 
an OS/2 application can determine when the SPX call has completed.

Summary of SPX Changes

This section is included as a brief listing of all the key SPX- related 
changes involved in release 1.3 of the NetWare Requester for OS/2. 



Appendix A

To obtain the latest Software Developer's Kit (SDK), call Novell Developer 
Relations at 1-800-RED-WORD (1-800-733-9673). The part numbers are listed 
below:

1.3 OS/2 Requester SDK (5 1/4-inch diskettes)  Part Number 883-000940-001 
1.3 OS/2 Requester SDK (3 1/2-inch diskettes)  Part Number 883-000941-001

Acknowledgements

A special thanks to Bob Young and Mike Lasky for their help with this 
AppNote.  

Editor's Note: The author accepts written feedback at FAX (801) 429#5511.

