

                  IPX/SPX Library Documentation
     Copyright (c) April 1992, Ryu Consulting, 916/722-1939


1. Introduction

This document covers the access of the IPX/SPX libraries  for  C.
These libraries are composed of thr e  files:  NETWORK.LIB,  NET-
WORK3.LIB and NETWORK.H.  NETWORK.LIB contains the functions  for
Microsoft's or Watcom's 286 C compilers.   NETWORK3.LIB  contains
the functions for Watcom's 386  C  compiler.   NETWORK.H  is  the
header file that contains definitions a d  prototypes  for  func-
tions and variables.  The application written by  the  programmer
should include the NETWORK.H file and link with either of the li 
braries.

The purpose of the library is provide  the  programmer  with  the
tools to access the low-level network facilities without the need 
to deal with the variety of low-level functions that are unfamil 
iar to the higher-level programmer.  The network  resources  have
been consolidated into a system of functions  that  resemble  the
stream I/O functions that come with all C compilers.

This library sends and receives packets of data using either  IPX
or SPX.  IPX provides the lowest level channel  with  the  lowest
overhead.  IPX does not guarantee that the packet sent will reach 
its intended target.  IPX does not guarantee the order  in  which
the packets are received by the listener.  IPX is the only proto 
col that can be used to broadcast a packet to all listeners.  SPX 
is a higher level protocol than IPX.  SPX guarantees reception of 
all transmitted packets and guarantees  the  reception  order  of
those packets.  SPX is slower than IPX; however,  SPX  guarantees
delivery.


2. Definitions

Several predefined  values  are  declared  within  the  NETWORK.H
header file.  They should be used by the  programmer  to  control
and check status of the functions  within  the  library.   It  is
suggested that the programmer only scan these definitions briefly 
before looking at the functions.  Althou h  the  definitions  in-
clude descriptions, real understanding will only come  after  the
functions themselves are studied.

The definition FAR is used in place of far (or any of its compil 
er specific derivatives) so that there will be no  difference  in
prototypes between the real and protected mode  versions  of  the
library.


2.1 In use flags for ECBs

These flags can be used to check the  status  of  an  information
packet.  They pertain to the in_use field of the IPX_PACKET_T and 
SPX_PACKET_T structures.  This field is set by  the  IPX  process
and should not be altered by the programmer.

                           1






IU_DONE        Indicates that the  ECB  has  been  processed  and
               completion code is valid

IU_HOLDING     Send/receive has occurred, but ECB is  in  holding
               queue waiting to be processed

IU_SCHEDULED   Event has been scheduled and is waiting f r  time-
               out

IU_LISTENING   IPX is listening for incoming packets at a socket

IU_SENDING     ECB is being sent or in the process of being sent

IU_PROCESSING  ECB is being processed by IPX

IU_WAITING     ECB has been put in a waiting  queue  because  IPX
               was busy


2.2 Completion codes for transmission ECBs

These flags are used by IPX to signal the completion condition of 
an IPX/SPX transaction.  These values are  placed  in  the  field
completion_code of the IPX_PACKET_T and SPX_PACKET_T  structures.
The completion_code field is  not  valid  until  IPX  has  placed
IU_DONE in the in_use field.

CC_SUCCESS     The packet has been sent successfully

CC_CANCELLED   Send request for this ECB has been cancelled, just 
               like Twin Peaks

CC_CHALLEDGED  Packet was malformed (eg. IPX  packet  <30  bytes,
               SPX<42 bytes, packet > 576 bytes)

CC_UNDELIVERED Packet couldn't be sent, no listener available

CC_FAILURE     Network  was  physically  unable  to  deliver  the
               packet

CC_OVERFLOW    The size of the fragment received is either  0  or
               too large (>576 bytes)

CC_CLOSED      The reception socket was not open

CC_CANCEL_FAIL The ECB could not be cancelled


2.3 xPX_OPEN flags

These definitions are to be used when opening a xPX stream.  They 
can be merged with a bitwise OR, but they should not be summed.

XPX_READ       Sets up listening packets for the stream

XPX_WRITE      Sets up talking packets for the stream



                           2





XPX_RW         Sets up talking  and  listening  packets  for  the
               stream

XPX_WAIT       xPX_OPEN() waits for a response before returning

XPX_NOWAIT     xPX_OPEN() returns  immediately  after  stream  is
               opened

XPX_SPX        xPX_OPEN() creates an SPX stream

XPX_IPX        xPX_OPEN() creates an IPX stream


2.4 xPX Error Codes

The following definitions are possible error codes  that  can  be
returned by any of the library functions.

ERR_SOCKET_OPEN     Socket was already open

ERR_NO_SOCKET       Socket does not exist

ERR_SOCKET_FULL     Socket table is full

ERR_NO_IPX_PATH     No path to destination node found

ERR_MEMORY          Not enough memory to allocated for function

ERR_IPX_TIMEOUT     Timeout occurred during a waiting period

ERR_POINTER         Pointer contents are  not  supported  by  the
                    function

ERR_PARAMETER       One of the passed parameters is not kosher

ERR_OPEN            Stream is already open

ERR_NOT_OPEN        Stream is not open or invalid stream pointer

ERR_NO_SUPPORT      Tried to read a WRITE ONLY or  write  a  READ
                    ONLY stream

ERR_NO_NULLS         Tried  to  write  with  a  NULL  flag  while
                    _Asynch_Flag == !0


2.5 Control parameters

The following definitions should not be  set  by  the  programmer
unless (s)he has a complete knowledge of  their  affect  and  the
source code to all the libraries.  Changing any of  these  values
requires a full regeneration of the lib files.  They are included 
for completeness.

DEFAULT_TALKERS     Number of talkers normally  created  with  an
                    open

DEFAULT_LISTENERS   Number of listeners normally created with  an


                           3





open

NODE_ADDRESS_SIZE   Number of bytes in  a  node  address,  either
                    local or global

MAX_PACKET_SIZE     Maximum size of a  packet  including  IPX/SPX
                    header

IPX_TYPE            Packet type number for IPX packets

SPX_TYPE            Packet type number for SPX packets


3. Structure Definitions

A couple structures are used by the application program to inter 
act with the xPX library functions.  There are several more  that
are used by the xPX stream functions to  interact  with  the  IPX
resources.   The  xPX  stream  structures   are   defined   first
(NET_ADDRESS_T and XPX_STREAM_T) and  the  others  are  described
later for completeness.


3.1 Network Address Structure

The network address structure allows the  application  to  define
any node on the network.

typedef struct NET_ADDRESS_S
{
     unsigned long  network;
     unsigned char  node[NODE_ADDRESS_SIZE];
     unsigned short socket;
} NET_ADDRESS_T;

where,
network   Contains the number of the network cabling system  upon
          which the node resides.  If the destination node is  on
          the current network, a 0 should be use .   No  signifi-
          cance is placed upon the magnitude of this number.

node      Node number of the node.  This is usually the  physical
          address assigned to the network adapter.   A  broadcast
          may be made by using a node number  of  0xFFFFFFFFFFFF.
          No significance is placed upon the  magnitude  of  this
          number.

socket    Socket number of a mailbox in a particular node.  There 
          can be multiple socket numbers at each node.  A  socket
          of 0 will prompt IPX to generate a unique socket number 
          for the application.


3.2 Stream Definition Structure

This structure defines the accesses a d  packet  management  per-
formed by the xPX function upon a  stream.   All  of  the  fields
within this structure are managed by the libraries and should not 


                           4





be altered by the application.  They may  be  viewed,  but  their
placement and significance is dynamic, so proceed  with  caution.
Consider this structure to be analogous  to  the  FILE  structure
used by the normal file stream functions.


typedef struct XPX_STREAM_S
{
     struct XPX_STREAM_S FAR *next;
     SPX_PACKET_T FAR *first_allocated;
     SPX_PACKET_T FAR *last_allocated;
     SPX_PACKET_T FAR *first_unread;
     SPX_PACKET_T FAR *last_unread;
     SPX_PACKET_T FAR *first_free;
     SPX_PACKET_T FAR *first_error;
     SPX_PACKET_T FAR *last_error;

     NET_ADDRESS_T  dest;
     char           local_target[NODE_ADDRESS_SIZE];
     unsigned short connection_ID;
     int            total_talkers;
     int            total_listeners;
     int            unread_count;
     int            free_count;
     int            maximum_unread;
     int            error_count;

     unsigned long  total_transmissions;
     unsigned long  total_receptions;
     unsigned long  total_errors;

     int            open_flags;
     NET_ADDRESS_T  last_read;
} XPX_STREAM_T;

where,

next                Points to the next stream  structure  in  the
                    linked list of structures managed by xPX.

first_allocated     Points to the first allocated pack t  associ-
                    ated with this xPX stream.

last_allocated      Points to the last allocated packet associat 
                    ed with this xPX stream.

first_unread        Points to the first packet that has reception 
                    data that has not been read  y  the  applica-
                    tion.

last_unread         Points to the last packet that has  reception
                    data that has not been read  y  the  applica-
                    tion.

first_free          Points to the next  packet  available  for  a





                           5





transmission (write) operation.

last_read           Contains the full network address of the last 
                    packet read through  this  stream.   This  is
                    filled in by xpx_read() whenever a packet  is
                    read by the application.


3.3 ECB_HEADER_T Structure

The structure ECB_T (and all other definitions  that  follow)  is
only included for completeness and can be ignored by the applica 
tion programmer.  The ECB  (Event  Control  Block)  associates  a
packet (either IPX or SPX) with a source or destination node.  No 
gaps are allowed between any of the fields within  any  of  these
structures (eg. pack(1)).


typedef struct ECB_HEADER_S
{
     struct ECB_HEADER_S FAR *next;
     void (FAR *function)(void);
     unsigned char  in_use;
     unsigned char  completion_code;
     unsigned short socket;
     unsigned char  IPX_work[4];
     unsigned char  driver_work[12];
     unsigned char  dest_address[NODE_ADDRESS_SIZE];
     unsigned short fragment_count;
} ECB_HEADER_T;

where,

next                Used by IPX/SPX when the packet is active  to
                    point to the next packet in line.

function            This function is  called  when  the  function
                    that this ECB is associated with is complete. 
                    If the function is NULL, no call is made.

in_use              Set by IPX/SPX when the ECB is in use to  the
                    current state of transmission/reception.  Set 
                    to 0 when the operation is complete.

completion_code     Filled by IPX/SPX  with  a  valid  completion
                    code when the in_use field has been set to 0.

socket              Socket  number  with  which  this  packet  is
                    associated.

IPX_work            Work area used by IPX/SPX.

driver_work         Work are used by the IPX/SPX driver.

dest_address        Local address (node only) of pack t  destina-
                    tion/source.

fragment_count      Number of buff r  pointer/size  fragment  de-


                           6





scriptors   that   immediately   follow   the
                    ECB_HEADER_T structure.


The structure of a fragment that follows the ECB_HEADER_T  is  as
follows:


typedef struct FRAGMENT_S
{
     void FAR       *ptr;
     unsigned short size;
} FRAGMENT_T;

where,

ptr       Points to a buffer that will be used with the ECB.

size      Size of the ECB buffer, in bytes.


3.4 IPX_T Structure

The IPX_T structure provides a definition for the type of  packet
being transmitted or received.  It is  incorporated  into  larger
superstructures for use by this library.  The IPX_T structure  is
a subset of the SPX_T structure.


typedef struct IPX_S
{
     unsigned short checksum;
     unsigned short length;
     unsigned char  control;
     unsigned char  type;
     NET_ADDRESS_T  dest;
     NET_ADDRESS_T  src;
} IPX_T;

where,

checksum  Dummy checksum of the  IPX  packet.   This  is  set  to
          0xffff by IPX and disregarded.

length    Length of the  complete  IPX  packet,  including  data.
          This field is filled in by IPX.

control   Transport control byte filled in by IPX  to  facilitate
          movement throughout the entire network.

type      Type of packet described by this structure.   This  can
          either be a 1 or a 4.  This library uses 4.

dest      Full network/node/socket address of the destination for 
          the IPX packet.  Filled in by this libra y  for  trans-
          missions and filled in by IPX for receptions.

src       Full network/node/socket address of the source  of  the


                           7





IPX packet.  Filled in  by  IPX  for  transmission  and
          receptions.


3.5 SPX_T Structure

The SPX_T structure provides a definition for the type of  packet
being transmitted or received.  It is  incorporated  into  larger
superstructures for use by this library.  The SPX_T structure  is
a superset of the IPX_T structure.


typedef struct SPX_S
{
     unsigned short checksum;
     unsigned short length;
     unsigned char  control;
     unsigned char  type;
     NET_ADDRESS_T  dest;
     NET_ADDRESS_T  src;

     struct
     {
          unsigned char reserved1:4;
          unsigned char end_of_msg:1;
          unsigned char reserved2:1;
          unsigned char ACK_req:1;
          unsigned char sys_packet:1;
     } con_control;
     unsigned char  datastream;
     unsigned short src_ID;
     unsigned short dest_ID;
     unsigned short sequence;
     unsigned short ACK_number;
     unsigned short allocation;
} SPX_T;

where,

checksum       Dummy checksum of the SPX packet.  This is set  to
               0xffff by SPX and disregarded.

length         Length of the complete SPX packet, including data. 
               This field is filled in by SPX.

control        Transport control byte filled in by SPX to facili 
               tate movement throughout the entire network.

type           Type of packet described by this structure.   This











                           8





field is set to 5 by this library.

dest           Full network/node/socket address  f  the  destina-
               tion for the SPX packet.  Filled  n  by  this  li-
               brary for transmissions and filled in by  SPX  for
               receptions.

src            Full network/node/socket address of the source  of
               the SPX packet.  Filled in by SPX for transmission 
               and receptions.

reserved1      Reserved by the network gods for u e  in  the  fu-
               ture.

end_of_msg     End of message bit used by SPX internally.

reserved2      See previous reservation.

ACK_req        Set to indicate to t e  destination  that  an  ac-
               knowledge  packet  is  required  to  complete  the
               handshake.

sys_packet     System packet.

datastream     This is a status byte that  may  be  used  by  the
               application for its own use.  Values of 0-0xFD are 
               ignored by SPX, 0xFE and  0xFF  are  reserved  and
               should not be used.

src_ID         ID of the source that is used and filled  by  SPX.
               This number is  generated  when  a  connection  is
               established.

dest_ID        ID of the destination that is used and  filled  by
               SPX.  This number is generated when  a  connection
               is established.

sequence       Each packet is sequenced and must have a  sequence
               number.  This field is used by SPX to assure  that
               the packets are received in the  same  order  that
               they were transmitted.

allocation     Allocation number used and filled by SPX.


3.6 SPX_PACKET_T Structure

The SPX_PACKET_T structure incorporates an SPX_T  structure  (and
its subset IPX_T), an ECB_HEADER_T structure, a  single  fragment
descriptor, and a additional fields that are used by this library 
for packet bookkeeping.  The SPX_PACKET_T structure can  be  used
for either IPX or SPX  transmissions  and  receptions.   The  xPX
library uses this structure for all transactions.  All fields  in
SPX_PACKET_T with the same name as those that occur in previously 
defined structures have the same function.  The descriptions that 
follow the structure definition will  only  include  fields  that
have not been described in previous structures.



                           9






typedef struct SPX_PACKET_S
{
     struct SPX_PACKET_T FAR *next;
     void (FAR *function)(void);
     unsigned char  in_use;
     unsigned char  completion_code;
     unsigned short socket;
     unsigned char  IPX_work[4];
     unsigned char  driver_work[12];
     unsigned char  dest_address[NODE_ADDRESS_SIZE];
     unsigned short fragment_count;
     SPX_T FAR *    hdr;
     unsigned short size_hdr;
     void FAR *     buffer_ptr;
     unsigned short buffer_size;

     struct SPX_PACKET_S FAR *next_allocated;
     struct SPX_PACKET_S FAR *next_sibling;
     struct XPX_STREAM_S FAR *parent;
     void FAR *     default_buffer;
     unsigned short default_size;
     char FAR *     done_flag;

     unsigned short checksum;
     unsigned short length;
     unsigned char  control;
     unsigned char  type;
     NET_ADDRESS_T  dest;
     NET_ADDRESS_T  src;

     struct
     {
          unsigned char reserved1:4;
          unsigned char end_of_msg:1;
          unsigned char reserved2:1;
























                           10





          unsigned char ACK_req:1;
          unsigned char sys_packet:1;
     } con_control;
     unsigned char  datastream;
     unsigned short src_ID;
     unsigned short dest_ID;
     unsigned short sequence;
     unsigned short ACK_number;
     unsigned short allocation;
} SPX_PACKET_T;

where,

fragment_count Stores the number of packet  fragments  associated
               with this structure.  Set to 2 by xPX.

hdr            Points to the field checksum of this structure.

size_hdr       Number of bytes in the IPX  or  SPX  header.   IPX
               would be 30 bytes and SPX is 42.

buffer_ptr     Points to the beginning of the data buffer that is 
               to be transmitted or used for reception.

buffer_size    Number of bytes in the data buffer.

next_allocated Points to the  next  SPX_PACKET_T  that  has  been
               allocated for an  xPX  stream.   This  is  set  by
               xpx_open().

next_sibling   Points to the next SPX_PACKET_T that is associated 
               with a stream group: waiting for packet reception, 
               waiting and full of a received packet, waiting for 
               transmission, or ready to  e  used  for  transmis-
               sion.

parent         Points to the XPX_STREAM_T structure that  defines
               the stream with which this packet is associated.

default_buffer Points to a buffer that  is  allocated  with  this
               packet structure that can be used by  default  for
               transmissions and receptions.

default_size   Size of the default buffer in bytes.

done_flag      Set by the ESR with the done  flag  that  the  ESR
               received from IPX/SPX.


3.7 ORPHAN_T Structure

When packets are received by a node and can not be matched with a 
currently open stream, that packet is an  orphan.   Depending  on
how the orphan control flag is set, these orphans will either  be
discarded or set aside to be queried by the application.

typedef struct ORPHAN_S
{


                           11





     NET_ADDRESS_T  src;
     unsigned short length;
     unsigned char  buffer[];
} ORPHAN_T;

where,

src       Full address of the source of the orphaned packet.

length    Size of the buffer received with the packet, in bytes.

buffer    Contains the data received with the orphaned packet.


4. Global Variables

The global variables associated with this  library  are  used  to
control the functions or provide information to the  application.
The variables are defined as follows:


NET_ADDRESS_T _Our_Address

This structure is filled  in  by  the  function  xpx_init().   It
contains the network and node address of the node  on  which  the
application is running.  It also contains a unique socket  number
that has been generated for the application by IPX.


char _Socket_Life

Defines the lifetime of sockets opened  by  the  function  within
this library.  If set to 0, all sockets opened by the application 
will be automatically closed when the applicati n  exits  to  MS-
DOS.  If set to 0xFF, the  socket  will  remain  open  after  the
application exits to MS-DOS (eg. TSR).  Any value other than 0 or 
0xFF is undefined and will  produce  uncertain  results.   Either
type of open socket can be explicitly closed.


unsigned short _SPX_Version

Filled by xpx_init() with the  version  of  SPX  running  in  the
application's node.


unsigned short _SPX_Max_Connections

Filled by xpx_init() with the maximum number of  SPX  connections
supported by the version of SPX in the application's node.


unsigned short _SPX_Available_Connections

Filled by xpx_init() with the number of SPX connections currently 
available to SPX.




                           12





unsigned char _SPX_Retry_Count

Set by the application to the number of retries attempted by  SPX
before a packet is considered undeliverable.  This should be  set
before a call xpx_init() if it is to be used.  If not set by  the
application five (5) retries will be attempted.


unsigned char _SPX_Bowser_Flag

Enables (1) or disables (0) the watchdog used by IPX/SPX to check 
on the status of undelivered packets.


int _Default_Talkers

Default number of talkers created when an xPX stream is opened.


int _Default_Listeners

Default number of listeners created when an xPX stream is opened.


void (FAR *_Default_Talk_ESR)()

Points to the Event Service Routine (ESR) used by xPX to  process
packets that have completed transmission.


void (FAR *_Default_Listen_ESR)()

Points to the Event Service Routine (ESR) used by xPX to  process
packets that have just received a packet.


XPX_STREAM_T FAR *_First_Stream

Points to the first stream structure allocated by  xPX  for  this
application.


SPX_PACKET_T FAR *_First_Nomatch

Points to the first packet received from a  node  that  does  not
match any currently open xPX stream (orphan).


SPX_PACKET_T FAR *_Last_Nomatch

Points to the last packet received from  a  node  that  does  not
match any currently open xPX stream (orphan).


int _Total_Nomatchs

Number of orphaned packets that have been receive  and  have  not
been processed.


                           13







int _Total_Open_Streams

Number of currently open xPX streams.


int _Wait_Timeout

Number of system ticks to wait  for  a  response  from  a  stream
opened as an XPX_IPX type.


char _Asynch_Flag

Set to !0 if all writes performed by  the  xPX  streams  will  be
asynchronous.


char _Ignore_Nomatch

Set to 0 if non matching packets (orphans) should be kept for the 
application to process.  If set !0, all orphaned packets will  be
discarded.




































                           14






5. Library Functions

The xPX library is organized alphabetically.  Groups  of  library
functions will begin with the same word.  Functions that  perform
IPX-specific operations begin with ipx_.  Functions that  perform
SPX-specific operations begin with spx_.  Functions that  perform
operations that can access IPX or SPX are given a suffix of xpx_.

The library includes  several  functions  that  do  not  directly
relate to IPX or SPX, but are related when taken  in  the  larger
context of peer-to-peer network communicatio .   Semaphore  func-
tions can be used for peer synchronization.   Broadcast  and  job
support functions are included for fun.   Several  data  movement
and comparison functions are included  o  provide  support  func-
tions that enhance the overall performance of the xPX functions.

The IPX, SPX and xPX functions do not require a file server to be 
present on the network.  They only require IPX.COM to  be  loaded
at all participating nodes.  All other network specific functions 
require a file server to be present for operation.

The prototypes for all these library functions are in the  header
file NETWORK.H.




































                           15






addrtoa


     Summary

     #include <network.h>

     void addrtoa( string, address )
     char FAR *string;        -> 12-byte ASCII string destination
     char FAR *address;       -> IPX/SPX 6-byte node address



     Description

     This function converts an  IPX/SPX  node  address  into  its
     ASCII representation. string[] will be zero terminated.   No
     range checking is performed.



     Return Value

     Node address is converted into a 12-byte ASCIIZ string



     See Also

     atoaddr





























                           16






atoaddr


     Summary

     #include <network.h>

     void atoaddr( address, string )
     char FAR *address;       -> IPX/SPX 6-byte node address
     char FAR *string;        -> 12-byte ASCII string to convert



     Description

     This function converts an ASCII representation of an IPX/SPX 
     node address into its binary equivalent.  string[] does  not
     need to be zero terminated.  No range checking is performed.



     Return Value

     ASCII string is converted into a node address.



     See Also

     addrtoa





























                           17






broadcast_to_console


     Summary

     #include <network.h>

     int broadcast_to_console( string )
     char *string;            -> ASCIIZ string to send to the
                                 system console



     Description

     This function sends a string of now more than  64  bytes  to
     the console of the fileserver.  If string[] is  longer  than
     64 bytes, the transmitted string will be truncated.



     Return Value

     0 if string was sent OK; otherwise, an appropriate  negative
     Netware error code.



     See Also






























                           18






close_semaphore


     Summary

     #include <network.h>

     int close_semaphore( handle )
     long handle;             Handle of semaphore to close



     Description

     This function closes a previously opened Netware  semaphore.
     This will cause the semaphore value to be decremented.



     Return Value

     0 if semaphore was closed properly; otherwise an appropriate 
     negative Netware error code.



     See Also

     get_semaphore_count   get_semaphore_value   open_semaphore
     signal_semaphore      wait_semaphore





























                           19






end_of_job


     Summary

     #include <network.h>

     int end_of_job( process )
     int process;             Process to close job for



     Description

     This function signals Netware that the current j b  is  com-
     plete.  If process is 0, only the job  associated  with  the
     current process is ended.  If process is -1,  all  processes
     at the application's workstation  are  ended.   End  Of  Job
     (EOJ) closes all  semaphores,  open  files  and  forces  all
     unstarted queued jobs to start or terminate.



     Return Value

     0 if EOJ was performed; otherwise  an  appropriate  negative
     Netware error code.
      


     See Also




























                           20






farcmpw


     Summary

     #include <network.h>

     int farcmpw( buffer1, buffer2, count )
     void FAR *buffer1;       -> a buffer to compare
     void FAR *buffer2;       -> buffer to compare to buffer2
     unsigned int count;      Number of bytes to compare



     Description

     This function is a high performance buff r  comparison  rou-
     tine.  The buffers must be comprised of an  even  number  of
     bytes.  The count must be even.  The buffers  should  be  on
     even byte boundaries and not cross a 64K segment.  No check 
     ing is done by this function.



     Return Value

     0 if the two buffers are equal.  1 if buffer1[]  is  greater
     than buffer2[].  -1 if buffer1[] is less than buffer2[].



     See Also

     _fmemcmp

























                           21






farmove


     Summary

     #include <network.h>

     void FAR farmove( dest_ptr, src_ptr, count )
     void FAR *dest_ptr;      -> destination buffer
     void FAR *src_ptr;       -> source buffer
     unsigned int count;      Number of bytes to move



     Description

     This function is a stripped down  buffer  movement  routine.
     The count can be even or odd.  The buffers should be on even 
     byte boundaries and not cross a 64K segment.  No checking is 
     done by this function.



     Return Value

     Pointer to the destination buffer.



     See Also

     _fmemmove



























                           22






farset


     Summary

     #include <network.h>

     void FAR *farset( buffer, value, count )
     void FAR *buffer;        -> buffer to set
     char value;              Value to set the buffer to
     unsigned int count;      Number of bytes to set



     Description

     This function  is  a  stripped  down  buffer  initialization
     routine.  It does no range or boundary checking.  The desti 
     nation buffer should start on  an  even  boundary  for  best
     performance.



     Return Value

     Pointer to the start of the destination buffer.



     See Also

     _fmemset



























                           23






get_semaphore_count


     Summary

     #include <network.h>

     int get_semaphore_count( handle )
     long handle;             Handle of semaphore to query



     Description

     This function queries Netware as to how many opens have been 
     performed on a semaphore.



     Return Value

     Number current opens on this semaphore  f  positive;  other-
     wise an appropriate negative Netware error code.



     See Also

     close_semaphore    get_semaphore_value   open_semaphore
     signal_semaphore   wait_semaphore





























                           24






get_semaphore_value


     Summary

     #include <network.h>

     int get_semaphore_value( handle )
     long handle;             Handle of semaphore to query



     Description

     This function queries Netware as to the current value of the 
     semaphore with respect to the process  that  is  making  the
     query.  A positive value indicates that the application  can
     access the resource that is associated with  the  semaphore.
     A negative value means  that  the  application  must  either
     enter a waiting queue by calling wait_semaphore() or abandon 
     hope of accessing the resource.



     Return Value

     Valid semaphore values are between -127 and 127.   A  return
     of -128 means that the semaphore handle is bad.



     See Also

     close_semaphore    get_semaphore_count   open_semaphore
     signal_semaphore   wait_semaphore
























                           25






ipx_add_listener


     Summary

     #include <network.h>

     int ipx_add_listener( ecb )
     ECB_HEADER_T FAR *ecb;   -> ECB descriptor to add



     Description

     This function adds a packet to the IPX listening chain.  All 
     the application related fields in the ECB and its associated 
     IPX packet descriptor must be filled  before  this  call  is
     made.  If no Event Service Routine  (ESR)  is  available  to
     process this ECB, the application must poll the in_use field 
     for completion.



     Return Value

     0 if the listening packet was accepted; otherwise  n  appro-
     priate negative Netware error code.



     See Also

     ipx_cancel_ecb   ipx_send_packet


























                           26






ipx_cancel_ecb


     Summary

     #include <network.h>

     int ipx_cancel_ecb( ecb )
     ECB_HEADER_T FAR *ecb;   -> ECB descriptor to cancel



     Description

     This function cancels any upcoming events associated with an 
     ECB.  This will deafen listeners and mute talkers  (if  they
     haven't sent their data yet).



     Return Value

     0 if the ESC was canceled; otherwise an appropriate negative 
     Netware error code.  -1 if the ECB is currently in use.   -7
     if the ECB can't be canceled.



     See Also

     ipx_add_listener




























                           27






ipx_close_socket


     Summary

     #include <network.h>

     int ipx_close_socket( socket )
     us socket;               Socket number to close



     Description

     This function closes an open socket number passed in socket. 
     Any  further  transactions  attempted  through  this  socket
     number will be stopped.  All current ECB  transactions  will
     be halted.  If the socket is not currently open, th s  func-
     tion request will be ignored.



     Return Value

     0 if the socket number was closed.  No error is possible.



     See Also

     ipx_open_socket




























                           28






ipx_open_socket


     Summary

     #include <network.h>

     int ipx_open_socket( socket )
     us FAR *socket;          -> variable to place the socket #



     Description

     This function opens a socket number passed  in  *socket  for
     future transactions.  If *socket is 0, IPX will  generate  a
     unique socket number for the application to use.   A  socket
     must be opened before any transmissions or receptions can be 
     performed using IPX or SPX.

     Socket numbers are returned in MSByte first format.

     Some socket numbers are predefined.  They are as follows:

          1              Routing information packet
          2              Echo protocol packet
          3              Error handler packet
          20h-3Fh        Experimental
          1-BB8h         Registered with Xerox
          451h           File service packet
          452h           Service advertising packet (SAP)
          453h           Routing information packet
          455h           NETBIOS packet
          456h           Diagnostic packet
          4000h-8000h    Range used to dynamically assign sockets



     Return Value

     0 if the semaphore was  opened  successfully;  otherwise  an
     appropriate negative Netware error code.



     See Also

     ipx_close_socket











                           29






ipx_read_orphan


     Summary

     #include <network.h>

     ORPHAN_T FAR *ipx_read_orphan( orphan )
     ORPHAN_T FAR *orphan;    -> orphan packet to fill



     Description

     This  function  reads  the  next  orphaned  packet  received
     through the xPX streams operation.  An  orphaned  packet  is
     one that has come into an open socket but has  no  receiving
     stream open to accept  the  information.   *orphan  will  be
     filled with the next available  orphan,  if  any  have  been
     received.  The buffer used  to  store  the  orphan  data  is
     allocated by this function, so it must be freed after it  is
     used.



     Return Value

     Pointer to the orphan packet sent to th s  function;  other-
     wise NULL if no orphan is available or not enough memory  is
     available to allocate.



     See Also

     xpx_orphan_status























                           30






ipx_send_packet


     Summary

     #include <network.h>

     int ipx_send_packet( ecb )
     ECB_HEADER_T FAR *ecb;   -> IPX ECB to send



     Description

     This function adds a packet to the  IPX  transmission  list.
     All the application related fields in the ECB and i s  asso-
     ciated IPX packet descriptor must be filled before this call 
     is made.  If no Event Service Routine (ESR) is available  to
     process this ECB, the application must poll the in_use field 
     for completion.



     Return Value

     0 if the packet was accepted for transmission; otherwise  an
     appropriate negative Netware error code.



     See Also

     ipx_add_listener   ipx_cancel_ecb


























                           31






ipx_target


     Summary

     #include <network.h>

     int ipx_target( local_address, full_address )
     char FAR *local_address; -> buffer to fill with local ID
     char FAR *full_address;  -> buffer filled with full address



     Description

     This function generates a local node address for  a  10-byte
     full network/node address that is  stored  in  full_address.
     The 6-byte local address is placed in  local_address[].   If
     the full address resides on the current network,  the  local
     address is the same as the node of the full address.  If the 
     full address indicates that  the  node  resides  on  another
     network, the local address will be the node address  of  the
     router.

     This function does not require a open socket or any  channel
     of communication to be established with the target.



     Return Value

     Number of system ticks estimated that packet  would  require
     to be sent to the  target  node;  otherwise  an  appropriate
     negative Netware error code if a path to the target  is  not
     found.



     See Also

     xpx_init


















                           32






isbroadcast


     Summary

     #include <network.h>

     int isbroadcast( address )
     char FAR *address;       -> IPX/SPX node address



     Description

     This function checks to see if the IPX/SPX node ID stored in 
     address[] is a broadcast address (eg. 0xFFFFFFFFFFFF).



     Return Value

     0 if address[] is a broadcast ID.



     See Also

































                           33






open_semaphore


     Summary

     #include <network.h>

     int open_semaphore( semaphore, initial, count, handle )
     char *semaphore;         -> name of the semaphore to open
     char initial;            Initial count value for semaphore
     char *count;             -> place for the current count
     long *handle;            -> variable to store the handle



     Description

     This function opens a semaphore associated with the name  in
     semaphore[].  If the semaphore is not currently open by some 
     other process, its initial value will be set to initial.  If 
     the open is successful, the number of current ope s  associ-
     ated with the semaphore will be placed in *count.  If  there
     are no other current opens, *count will  be  set  to  1.   A
     handle is generated and is placed in  *handle.   The  handle
     should be used in future queries of the open semaphore.



     Return Value

     0 if the semaphore was  opened  successfully;  otherwise  an
     appropriate negative Netware error code.



     See Also

     close_semaphore    get_semaphore_count   get_semaphore_value
     signal_semaphore   wait_semaphore




















                           34






signal_semaphore


     Summary

     #include <network.h>

     int signal_semaphore( handle )
     long handle;             Handle of semaphore to signal



     Description

     This function signals Netware  that  the  current  semaphore
     owner has relinquished use of the resource  with  which  the
     semaphore is bound.  This will have the effect of waking the 
     next process that is waiting on the semaphore.



     Return Value

     0 if the semaphore was signaled properly.  1 if there was  a
     semaphore value overflow.  -1 if the handle is bad.



     See Also

     close_semaphore   get_semaphore_count   get_semaphore_value
     open_semaphore    wait_semaphore



























                           35






spx_add_listener


     Summary

     #include <network.h>

     int spx_add_listener( ecb )
     ECB_HEADER_T FAR *ecb;   -> ECB descriptor to add



     Description

     This function adds a packet to the SPX listening chain.  The 
     communication channel with the target node must have already 
     been established.  All the application related fields in the 
     ECB and its associated IPX packet descriptor must be  filled
     before this call is made.  If no Event Service Routine (ESR) 
     is available to process this ECB, the application must  poll
     the in_use field for completion.



     Return Value

     0 if the listening packet was accepted; otherwise  n  appro-
     priate negative Netware error code.



     See Also

     spx_establish_communication   spx_send_packet   xpx_init

























                           36






spx_establish_communication


     Summary

     #include <network.h>

     int spx_establish_communication( ecb, id )
     ECB_HEADER_T FAR *ecb;   -> SPX ECB to use for connection
     unsigned short FAR *ID;  -> variable to fill with ID



     Description

     This function establishes an  SPX  connection  with  another
     node.  SPX uses the ECB *ecb to attempt to communicate  with
     the node.  Once a channel is opened to the  target  node,  a
     connection ID is generated and placed in *id.   This  ID  is
     used to continue transaction with the target.



     Return Value

     0 if the connection was established; otherwise  n  appropri-
     ate negative Netware error code.



     See Also

     spx_add_listener   spx_send_packet   xpx_init


























                           37






spx_send_packet


     Summary

     #include <network.h>

     int spx_send_packet( ecb )
     ECB_HEADER_T FAR *ecb;   -> IPX ECB to send



     Description

     This function adds a packet to the  SPX  transmission  list.
     The communication channel with the  target  node  must  have
     already  been  established.   All  the  application  related
     fields in the ECB and its associated IPX  packet  descriptor
     must be filled before this call is made.  If no Eve t  Serv-
     ice Routine (ESR) is available  to  process  this  ECB,  the
     application must poll the in_use field for completion.



     Return Value

     0 if the packet was accepted for transmission; otherwise  an
     appropriate negative Netware error code.



     See Also

     spx_add_listener   spx_establish_communication   xpx_init

























                           38






wait_semaphore


     Summary

     #include <network.h>

     int wait_semaphore( handle, ticks )
     long handle;             Handle of semaphore to wait on
     us ticks;                Number of system ticks to wait



     Description

     This function waits for either the semaphore associated with 
     handle to become free or the number of system ticks in ticks 
     to transpire.  If ticks is 0, the default  timeout  will  be
     used.



     Return Value

     0 if the resource bound to the semaphore is ready  for  use.
     -1 if the handle is bad.  -2 if there was a timeout.



     See Also

     close_semaphore   get_semaphore_count   get_semaphore_value
     open_semaphore    signal_semaphore


























                           39






xpx_close


     Summary

     #include <network.h>

     int xpx_close( sp );
     XPX_STREAM_T FAR *sp;    -> stream structure to close



     Description

     Closes a stream opened by a  previous  call  to  xpx_open().
     All memory allocated to that stream is released and if  this
     the last stream associated with a socket, that socket number 
     will be closed.  Any future IPX packets received  from  that
     stream will be  ignored.   Any  SPX  packets  will  also  be
     ignored and cause an error at  the  originator  of  the  SPX
     packet.



     Return Value

     0 if stream was closed properly;  otherwise  an  appropriate
     negative error code.



     See Also

     xpx_open   xpx_read   xpx_write

























                           40






xpx_error_status


     Summary

     #include <network.h>

     int xpx_error_status( sp );
     XPX_STREAM_T FAR *sp;    -> stream structure to query



     Description

     This function returns the number of  packeting  errors  that
     have been encountered by this stream.



     Return Value

     Number of errors encountered.



     See Also

     xpx_orphan_status   xpx_read_status   xpx_write_status































                           41






xpx_init


     Summary

     #include <network.h>

     int xpx_init( socket );
     int socket;              Socket number to open



     Description

     This function initializes all  IPX  and  SPX  internals  and
     prepares all global variables for operation.  This  function
     must be the first of the xPX library functions to be called, 
     because all of the other functions rely  on  its  processes.
     socket is the socket number that will be opened  and  placed
     in the global structure _Our_Address.  If socket is  0,  IPX
     will allocate a currently  unused  socket  number  for  xPX.
     This function may be called repeatedly, but will not  affect
     any open streams.



     Return Value

     0 if IPX and SPX were present and ready for  operation.   -1
     if the socket number given  is  already  open.   -2  if  the
     socket table is full.  -3 if IPX is not installed.



     See Also

     xpx_close   xpx_open   xpx_read   xpx_write






















                           42






xpx_open


     Summary

     #include <network.h>

     int xpx_open( dp, flags, sp );
     NET_ADDRESS_T dp;        Remote network/node/socket address
     int flags;               Open type and controls
     XPX_STREAM_T FAR **sp;   -> variable to fill with a pointer
                              to a xPX stream definition struc-
                              ture allocated for the open stream



     Description

     Opens an xPX stream to another  node  on  the  network.   dp
     defines the network address, node address and socket  number
     to use for communication.  If dp->socket is 0, a new  socket
     will be generated by IPX for this stream.   The  new  socket
     number will be placed in dp->socket.  sp should point  to  a
     variable that will be filled  with  a  FAR  pointer  to  the
     stream definition structure that is generated  if  the  open
     was successful.  flags is a bitwise OR amalgam  f  the  fol-
     lowing labels:


     XPX_READ

     Causes  ipx_open()  to  allocate  SPX_PACKET_T  packets  for
     receiving data from the node defined by dp.  The  number  of
     packets allocated is determined by the value in  the  global
     variable _Default_Listeners.  A stream can be opened as read 
     only.  A stream can be opened to receive all packets sent to 
     a socket if dp->node is set to 0xFFFFFFFFFFFF.


     XPX_WRITE

     Causes  ipx_open()  to  allocate  SPX_PACKET_T  packets  for
     transmitting data to the node defined by dp.  The number  of
     packets allocated is determined by the value in  the  global
     variable _Default_Talkers.  A stream can be opened as  write
     only.  A stream can be opened to broadcast  packets  to  all
     nodes associated with a particular socket if dp->node is set 
     to 0xFFFFFFFFFFFF.


     XPX_RW

     Combination of  XPX_READ  and  XPX_WRITE.   Has  no  special
     significance in itself.

xpx_open  (cont.)



                           43






     XPX_WAIT

     Causes xpx_open() to wait for _Wait_Timeout system ticks for 
     a response from the destination  of  the  stream.   This  is
     automatic if the stream is an SPX type.  If the target  node
     does not respond within the designated timeout  period,  the
     stream is closed and an error is returned.  This can be used 
     with a broadcast type stream.


     XPX_NOWAIT

     Causes xpx_open() to return without confirming that a target 
     node exists.  This only  affects  IPX  streams  because  SPX
     requires acknowledgement  from  the  target.   This  is  the
     default condition.  XPX_WAIT | XPX_NOWAIT yields XPX_WAIT.


     XPX_IPX

     Casts the opened communications channel as  an  IPX  stream.
     This is the  default  setting.   XPX_IPX  |  XPX_SPX  yields
     XPX_SPX.


     XPX_SPX

     Casts the opened communications channel as  an  IPX  stream.
     XPX_IPX | XPX_SPX yields XPX_SPX.



     Return Value

     0 if the stream was opened successfully; otherwise an appro 
     priate negative error code.























                           44






xpx_open  (cont.)



     Example

     To open an IPX stream to node 0x011234569828, socket 0x4200, 
     network 0x8765434 as a read/write channel the following code 
     sample could be used:


     NET_ADDRESS_T  target = {  0x8765434,
                               {0x1,0x12,0x34,0x56,0x98,0x28},
                                0x4200
                             };
     XPX_STREAM_T FAR *sp;
     int rv;


     rv = xpx_open( &target, XPX_IPX|XPX_RW|XPX_NOWAIT, &sp );
     if ( rv != 0 )
          printf( "\nReceived error code %d", -rv );



     See Also

     xpx_close   xpx_read   xpx_write































                           45






xpx_orphan_status


     Summary

     #include <network.h>

     int xpx_orphan_status( sp )
     XPX_STREAM_T FAR *sp;    -> stream structure to query



     Description

     This function returns the number of orphan packets that  are
     ready to be processed from this stream.  If  _Ignore_Nomatch
     has been set to !0,  all  orphans  will  be  discarded.   If
     orphans are not processed or discarded, they can use up  all
     the available listening packets for a stream,  leaving  none
     for normal transactions.



     Return Value

     Number of unprocessed orphan packets for this stream.



     See Also

     ipx_read_orphan



























                           46






xpx_read


     Summary

     #include <network.h>

     int xpx_read( sp, buffer, count );
     XPX_STREAM_T FAR *sp;    -> stream structure to read from
     void FAR *buffer;        -> buffer to read packet into
     int count;               Size of reception buffer, in bytes



     Description

     Reads data from the oldest received packet associated with a 
     particular stream defined by sp.  The amount of  data  moved
     into buffer[] is limited by count or  the  amount  of  bytes
     that are left unread in the oldest filled listening  packet.
     If there is not enough space available in buffer[],  only  a
     partial packet will be read.

     This function will only read the data buffer portion of  the
     received packet and does not concern itself with the  header
     portion of the received packet.  In order  to  discover  the
     source of the read packet, the application should query  the
     last_read structure field of sp after this  called  is  made
     successfully.  Once a packet is read, it will immediately be 
     sent back to the reception pool used by IPX.

     A single read will not cross  reception  packet  boundaries.
     The maximum size for IPX packets is 546 bytes.  The  maximum
     size for SPX packets is 536 bytes.  The maximum size used by 
     the library can be found by  subtracting  the  size  of  the
     packet type from the library definition MAX_PACKET_SIZE.



     Return Value

     Number of bytes read by this function.  If  no  packets  are
     available for reading, ipx_read() will return a  0  and  the
     last_read field of sp will be cleared to 0's.  If  an  error
     occurred during reception or the stream has not been opened, 
     an appropriate negative error code will be returned.



     See Also

     xpx_close   xpx_open   xpx_write







                           47






xpx_read_status


     Summary

     #include <network.h>

     int xpx_read_status( sp );
     XPX_STREAM_T FAR *sp;    -> stream structure to query



     Description

     This function returns the number of unread packets that  are
     queued from a stream.



     Return Value

     Number of unread packets.



     See Also

     xpx_error_status   xpx_orphan_status   xpx_write_status































                           48






xpx_write


     Summary

     #include <network.h>

     int xpx_write( sp, buffer, count, done_flag );
     XPX_STREAM_T FAR *sp;    -> stream structure to read from
     void FAR *buffer;        -> buffer to read packet into
     int count;               Size of reception buffer, in bytes
     char FAR *done_flag;     -> byte to set with the completion
                              code after the last packet has been
                              sent



     Description

     This function packed and writes a data buffer out to the xPX 
     stream sp.  count determines the number of bytes that can be 
     written from buffer[].  If there are not enough free packets 
     to hold the entire contents of  buffer[],  ipx_write()  will
     send as many as it can and then return to the caller.

     When the last packet has been sent, the byte pointed  to  by
     done_flag will be set to the completion code  of  that  last
     packet.  ipx_write() will set *done_flag to 0x01  while  the
     packet is waiting to be sent.   If  done_flag  is  NULL,  no
     operation will be performed with it.



     Return Value

     Number of bytes  that  could  be  sent  without  significant
     delay; otherwise a negative error code



     See Also

     xpx_close   xpx_open   xpx_read
















                           49






xpx_write_status


     Summary

     #include <network.h>

     int xpx_write_status( sp );
     XPX_STREAM_T FAR *sp;    -> stream structure to query



     Description

     This function returns the number of packets that a e  avail-
     able for transmission for a stream.



     Return Value

     Number of packets available for transmission.



     See Also

     xpx_error_status   xpx_orphan_status   xpx_read_status































                           50





