API Programmers Reference Guide - LINX Data Terminals

LINX V 

API Programmers 

Reference Guide

March 31, 2004 

Copyright LINX Data Terminals, Inc. 

All Rights Reserved

Contents 

LINX 5 API-C Programmers Reference Guide 1 

Overview ...................................................................................................................................1 

Function List:.............................................................................................................................1 

Include Files: .............................................................................................................................2 

Module Specifics .......................................................................................................................2 

The Unit Table...........................................................................................................................2 

Using the Server ........................................................................................................................2 

Time Management .....................................................................................................................3 

Writing Alternate Servers ..........................................................................................................3 

Special Stuff ..............................................................................................................................3 

Function Calling Sequences.......................................................................................................4 

Function: Ltime() ........................................................................................................4 

Function: Elapsed (t,n) ................................................................................................4 

Function: L5MakeTable (n)........................................................................................4 

Function: L5AddUnit (“hhhhhhhhhhhh”) ..................................................................4 

Function: L5SetServer(v) ............................................................................................4 

Function: L5Open (Bufs, NetBufs) .............................................................................5 

Function: L5Close()....................................................................................................5 

Function: L5C()..........................................................................................................5 

Function: L5Ready (n) ...............................................................................................5 

Function: L5StateText (n,s)........................................................................................5 

Function: L5AddrText (n, s, f) ...................................................................................6 

Function: L5ErrText (&string) ...................................................................................6 

Function: L5Idle () .....................................................................................................6 

Function: L5Send (n, “text”) .......................................................................................6 

Function: L5 Receive (s, &f).......................................................................................6 

Function: L5SetMonitor (v) ........................................................................................7 

Function: L5SetSubNetwork (v) ................................................................................7 

LINX 5 Protocol Reference.........................................................................................7 

Application Data..........................................................................................................8 

Linx Network Architecture Packet ..............................................................................9 

Linx 5 Full Server Implementation ...........................................................................10 

Linx 5 Limited Server Implementation .....................................................................11 

Alternate Servers .......................................................................................................11 

LINX 5 IPX Packet ...................................................................................................12 

LINX 5 LLC Packet Structure...................................................................................13 

LINX 5 Ethernet Packet Structure.............................................................................13 

Appendix A..............................................................................................................................15 

The Whole Packet .....................................................................................................15 

Net API Programmers Reference Guide 17 

Function List............................................................................................................................17 

Include File:.............................................................................................................................17 

Overview .................................................................................................................................18 

LINX V API Programmers Reference Guide 

Contents • iii

Predefined Types .....................................................................................................................18 

Function: NetAvail ( ) ..............................................................................................18 

Function : NetWrite ( &NetAddress, &data, n).........................................................18 

Function: NetFlush ( ) ..............................................................................................19 

Function: NetRead( &NetAddress, &data, n)...........................................................19 

Function: NetWrite (&NetAddress, &data, n)..........................................................19 

Function: NetOpen (buffersize, count, ssocket, dsocket) .........................................19 

Function: NetClose ( ) ..............................................................................................19 

Function: NetErr ( ) ..................................................................................................20 

Function NetErrText (&string)..................................................................................20 

LINX 5 DOS Utilities Users Guide 21 

Program List ............................................................................................................................21 

L5List.exe : List the LINX 5’s on the network.........................................................21 

L5Chat.exe : Direct interaction with LINX 5’s .......................................................22 

L5Load.exe : Download files to one or more LINX 5’s..........................................22 

L5Go.exe : Start a loaded Basic application............................................................23 

L5Abort.exe : Stop an executing Basic application.................................................23 

Close.exe : Close an open socket.............................................................................23 

LINX 5 Network Activity Statistics 24 

Introduction .............................................................................................................................24 

Passive Loading.......................................................................................................................24 

Inactive Loading ......................................................................................................................25 

Active Loading ........................................................................................................................25 

Conclusion...............................................................................................................................26 

iv • Contents 

LINX V API Programmers Reference Guide

LINX 5 API-C Programmers 

Reference Guide 

Overview 

This API (Applications Program Interface) is used to interact with a Linx 5 terminal 

network. 

Function List: 

L5MakeTable 

L5AddUnit 

L5SetServer 

L5Open 

L5Close 

L5C 

L5Ready 

L5StateText 

L5AddrText 

L5ErrText 

L5Idle 

L5Send 

L5Receive 

Ltime 

Elapsed 

L5SetSubNetwork 

: Creates a unit table 

: Adds a unit to the unit table 

: Set the server type for multiserver mode 

: Start the Linx 5 server 

: Shut down the Linx 5 server 

: Returns number of units in table 

: Returns TRUE if the unit is ready 

: Get the text description of the state 

: Get a text description of the unit address 

: Get text of the last bad error 

: Allow background server activity to continue 

: Send a record to a unit 

: Get a record from a unit 

: Time in milliseconds since midnight 

: Measures time elapsed in milliseconds 

: Enables subnetworks from ENET Gateways 

LINX V API Programmers Reference Guide LINX 5 API-C Programmers Reference Guide • 1

Include Files: 

Defines.h 

L5API.h 

: Required include files and contents 

: Function declarations 

Module Specifics 

This interface is written in Borland C version 4.0. The C++//comment is used 

throughout the code. If you recompile these modules with another compiler, you 

may need to change the comments to /*…*/form. 

The Defines.h include file will need to be included in your module before L5Api.h. 

The default buffer counts should be upped if you are implementing a number of 

programs on larger networks. 

The Unit Table 

The unit table is a structure internal to the L5 server. You have limited access to this 

table via these routines: 

Using the Server 

L5MakeTable 

: Creates a unit table 

L5AddUnit 

: Adds a unit to the unit table 

L5C 

: Returns number of units in table 

L5Ready 

: Returns TRUE if the unit is ready 

L5StateText 

: Get the text description of the state 

L5AddrText 

: Get a text description of the unit address 

This table has a maximum size that is set by L5MakeTable. If you don’t call 

L5MakeTable then it assumes a default size. As units are detected by the server, 

they are added to the table. The table has L5C() entries, a number which can only 

get larger as units are found. When a unit stops responding it is marked as Offline, 

but is NOT removed from the table. If your application sends to units that are not 

L5Ready() the record is ignored. 

Simple programs can begin by calling L5Open(0,0) to start the Linx Server. If your 

application has a predefined table of terminal addresses then you should first allocate 

the table using L5MakeTable and fill it with L5AddUnit. 

If L5Open returns TRUE then the server has started successfully. This does not 

mean that any units were detected. Use L5C for that. 

Reading consists of calling L5Receive until non-zero. You cannot select which unit 

will send you data. You must process the data as it becomes available. If your 

application has long periods in which it is not reading from the units then it should 

call L5Idle. Note that failing to call L5Receive can result in filled receive buffers 

and a fatal server error. 

2 • LINX 5 API-C Programmers Reference Guide LINX V API Programmers Reference Guide

Time Management 

L5Send will send a record to a single unit or all units. 

If any routine has an error, the text description of that error can be obtained with 

L5ErrText. 

You MUST call L5Close before exiting your program. Failure to do so may leave 

network resources unavailable for the next time you run the program. 

The following functions are made available for simple timer management: 

Ltime 

Elapsed 

: Time in milliseconds since midnight 

: Measures time elapsed in milliseconds 

The Elapsed function will not work properly if two times differ by more than 24 

hours. Any time comparisons should be within that range. These functions use bios 

calls that are compatible with Windows but NOT other operating systems. The 

actual timer resolution is only good to 55 milliseconds. Do not attempt to use 

Elapsed for shorter times since it won’t work. 

Writing Alternate Servers 

When in multiple server 

mode an attempt to start 

the main server will 

ALWAYS take more than a 

minute as it checks for the 

presence of alternate 

servers. 

If your application is running in a multiple server environment then you need to call 

L5SetServer BEFORE calling L5Open. When you call L5Open, it will return 

FALSE if you cannot be the server yet. You must repeatedly call L5Open until it 

returns TRUE. 

While running in Multiple server mode you must check the global variable: BOOL 

L5ServerReady every few seconds to determine if the server is still running. If a 

main server has taken over you must call L5SetServer and return to calling L5Open 

until your server is again allowed to run. 

Special Stuff 

To get printf monitoring of network traffic you can use: 

extern BOOL L5ShowRx = TRUE; //Display data as it is read 

extern BOOL L5ShowTX = TRUE; // Display data as it is written 


Function Calling Sequences 

Function: Ltime() 

Returns: Return the time since midnight in milliseconds 

Proto: longLtime (void) 

Function: Elapsed (t,n) 

Usage: Determine if a time interval has elapsed. 

This is used in conjunction with the Ltime function which returns the time 

since midnight in milliseconds. 

Returns: TRUE when n millisecond has elapsed. 

Example: long t=Ltime(); 

while (!Elapsed (t,1000)) {…do stuff for a second…}; 

Proto: BOOL Elapsed (long, long) 

Function: L5MakeTable (n) 

Usage: Allocate the Linx 5 status table. This MUST be called before L5Open if you 

need more thatn the default number of terminals. Se L5AddUnit to pre allocate 

places for units in the table. Each unit uses about 300 bytes of global memory. 

Returns: TRUE if successful 

Proto: BOOL L5MakeTable (int) 

Function: L5AddUnit (“hhhhhhhhhhhh”) 

Usage: Adds a LINX 5 to the table. Each AddUnit must be a unique fully qualified 

address in the format: “hhhhhhhhhhhhmmnn” ehrtr hhh… is the node number, 

“mm” is the optional master number, and “nn” is the optional station number. 

Unit handles are integers from l to L5C(); 

Returns: unit handle in the table (0 if table is full) 

Proto: L5HANDLE L5AddUnit (char*s) 

Function: L5SetServer(v) 

Usage: Set the type of server that this one is. 

0=normal server, no alternate servers allowed 

1=main server, take control from alternates 

2=alternate server, only take control if main stops 

This must be called before calling L5Open. Call L5Open repeatedly unit it 

becomes TRUE. 

Proto: void L5SetServer (int v) 


Function: L5Open (Bufs, NetBufs) 

Usage: Start a Linx 5 Server. All of the Linx 5 terminals are brought on line. If a 

unit has not been placed in the unit table by AddUnit then it will be added to the end 

of the table. This can take a few seconds to execute. Bufs specifies the number of 

receive buffers to allocate. 0 will default to the number of units in L5MakeTable. 

The NetBufs parameter is used to set the number of low level buffers. By default 

this is 30 but may be increased up to 50 if you find yourself losing packets. Both 

Bufs and NetBufs use about 256 bytes per buffer. Leave things 0 when you don’t 

understand them. 

Returns: TRUE if successful. 

Proto: BOOL L5Open (int, int) 

Function: L5Close() 

Usage: Shuts down the server and releases the buffers. This causes all Linx 5’s to 

go offline. 

Proto: Void L5Close(void) 

Function: L5C() 

Usage: Returns the current size of the unit table. This must be called every time the 

table is examined since new units can be added at any time. 

Returns: number of units in the terminal table 

Proto: int L5C(void) 

Function: L5Ready (n) 

Returns: Returns TRUE if the unit is Online and ready for data. 

Proto: BOOL L5Ready (L5HANDLE) 

Function: L5StateText (n,s) 

Usage: The state description string for unit n is placed into string s (3 to 10 

characters). If NULL is provided for the string then only the state number is 

returned. 

Returns: State number (see L5State enumerated type) 

Proto: int L5StateText (L5HANDLE, char*) 

Example: for (i=1;i< L5C();i++) { char s[11]; 

L5StateText(i,s); printf (“Unit%d:%s\n”,i,s);} 


Function: L5AddrText (n, s, f) 

Usage: Get the address string for unit n. The type of string to get is determined by f: 

f=0: “hhhhhhhhhhhh” (Network node only) 

f=1: “hhhhhhhhhhhh” mm-nn” (node, master, station) 

f=2: “nnnnnnnn hhhhhhhhhhhh mm-nn” (add network) 

f=3: “ssss nnnnnnnn hhhhhhhhhhhh mm-nn” (add socket) 

Proto: void L5AddrText (L5HANDLE, char*, int) 

Function: L5ErrText (&string) 

Usage: Returns the last error code and its text description 

Proto: WORD L5ErrText (char*txt) 

Function: L5Idle () 

Usage: Keeps the Linx 5 terminals on line. Does not need to be called if an L5Send 

or L5Receive is issued at least once every 30 seconds. 

Returns: TRUE if there was any network activity on this call 

Proto: BOOL L5Idle (void) 

Function: L5Send (n, “text”) 

Usage: Send a record. Note that this can cause a pause if the transmit buffer is full 

for this unit. It is rare for pauses to occur. Use n=0 for broadcast. 

Proto: void L5Send (L5HANDLE i, char*s) 

Function: L5 Receive (s, &f) 

Usage: Receive a data record and get the unit handle. 

The optional &f (may be NULL) is the type of the record. 

f=0 on status messages (ON, BASIC, etc. ) 

f=100 on BASIC errors (record starts with “BASIC”) 

f=101 on network diagnostic responses (start with “ND”) 

f=1 to 99 on normal records generated by applications. 

Returns: 0 if nothing is available. 

Proto: L5HANDLE L5Receive (char*, int*) 


Function: L5SetMonitor (v) 

Usage: Enable server monitoring to standard out 

0 = no monitoring 

1 = full, 2 = rx only, 3 = tx only 

Proto: void L5SetMonitor (int v) 

Any LINX 5 acting as a 

Gateway MUST have a 

Terminal Number of 1. 

This is the ONLY way that 

the gateway is identified. 

Function: L5SetSubNetwork (v) 

Usage: Set the type of server that this one is. 

0 = no subnetworking is allowed 

1 = subnetworks are supported 

Proto: void L5 SetSubNetwork (int v) 

LINX 5 Protocol Reference 

This is the low level protocol description for the LINX 5. Users of the L5API can 

usually remain blissfully unaware of any of the following material. It is included to 

make a detailed understanding of the operation of L5API and NETAPI possible. 

Due the wonders of modern communications layering when using the Novell IPX 

protocol the packet structure is: 

APPLICATION DATA is contained in an 

LNA PACKET which is enclosed in an 

IPX PACKET which is encapsulated in the 

LLC PACKET which is embedded in an 

ETHERNET IEEE 802.3 FRAME 

While this sounds really nasty (and it is), there is not actually a lot of overhead since 

the overall Ethernet frame has to be a minimum of 64 bytes long anyway. 

When using TCP/IP protocol, the structure is modified to: 

APPLICATION DATA is contained in an 

LNA PACKET which is enclosed in an 

UDP PACKET which is tagged onto an 

IP PACKET which is embedded in an 

LLC PACKET which is embedded in an 

ETHERNET IEEE 802.3 FRAME 


Application Data 

Application data falls into a few major categories. These are: 

BASIC Tx Data 

BASIC Rx Data 

LINX Status Messages 

NETWORK Directives 

NETWORK Directive replys 

TEST Record 

BASIC Tx Data: This is data generated by a BASIC application program and 

transmitted by the application to the HOST or NET devices. This can be wither 

LDATA (sequenced) or UDATA (unnumbered). All data received from LINX ¾ 

subnetworks is LDATA. 

BASIC Rx Data: This is data generated by the server or another LINX 5. Data from 

the server is SDATA when sequenced. UDATA may be from another LINX or the 

server. 

LINX status Messages: These are SDATA records from the LINX which have a 

transaction number of 0. These can be generated by LINX ¾’s on a SubNetork. A 

LINX 5 can send ‘ON’, ‘MO’, ‘ER’, and ‘ND’ status messages. 

NETWORK Directives: These are commands or requests for information send by a 

server. These include, but are not limited to: 

+xxxxx… File directive 

>,xxxxx… Basic pcode download 

>Sxxxxx… operating system download record 

>>G restart an aborted Basic program 

>>A abort a Basic program 

NETWORK Directives replies: These are actually ‘ND’ LDATA STATUS records 

that the LINX sends in response to Network requests. 

TEST Record: This is a TEST broadcast packet that the LINX sends when it is in 

Ethernet Block Transmit mode. The packet is of the form: 

“..aaaaaaaaaaaaa ssssssss eeeeeeee hhmmssnnyymmddw” 

The “aaaaaaaaaaaa” is the hex ethernet address of this LINX. The “ssssssss” is a 32 

bit hex record count which starts at 0 every time the test starts. The “eeeeeeee” is a 

32 bit hex error count that increments every time there is a collision. The 

“hhmmssnnyymmddw” is the time/data stamp. 


This test can be started by a server by broadcasting a’ >B’ network directive. The 

directive can have an optional argument that is the number of 100ths of a second to 

wait between transmits. By default the LINX sends once a second. 

The network directive ‘>A’ terminated the block transmit test. 

The Ethernet Block Receive diagnostic will count the number of test records 

received. They are otherwise ignored. 

Linx Network Architecture Packet 

This packet structure is adapted from one in use on LINX 2, 3, and 4 terminals for 

RS 485 and RS 232 communications. 

The initial release of the 

LINX 5 does not support 

subnetworked LINX 3s and 

4s. The server should set 

Master and Station to 0. 

Position Field Explanation 

0 Data Size: xx Number of bytes of Data (may be o) 

1 Master: xx Concentrator/Master 

2 Station: xx Terminal number that is responding 

3 Retries: xx Total retry count 

4 Sequence: xx Record sequence number 

5 Type: xx Transaction number or block type 

6 Data: xx 0to 248 bytes of data 

DataSize: This is the number of valid characters (usually ASCII) in the Application 

Data Packet. 

Master: This field may be 00 for records received from the server. The LINX 5 

places it own Terminal Numer in this field for records that it generates. 

If the LINX 5 is forwarding records fro a LINX 3 or 4 attached to a subnetwork then 

this may be set to the terminal number of an attached SubMaster. If the server is 

sending records to Subnetworked LINX terminals then this must be set to the 

Terminal Number of an attached SubMaster. 

Station: This field may be 00 for records received from the server. The LINX 5 

places its own Terminal Number in this field for records that it generates. 

If the LINX 5 is forwarding records from a LINX 3 or 4 attached to a subnetwork 

then this may be set to the terminal number of an attached SubMaster. If the server 

is sending records to Subnetworked LINX terminals then this must be set to the 

Terminal Number of an attached SubMaster. 

Retries: This field is set to 0 for each new record generated. It is incremented by 

the LINX 5, each time the record fails to receive an ACK from the server or when 16 

collisions force the LINX to back off. The server can use this to keep track of 

network problems. 

The server sets this to 0 in records it generates. It is ignored by the LINX 5. 


If the LINX has not yet 

received an ACK to a 

packet that it has sent then 

it will simply ignore any 

DATA sent by the server 

until the data has been sent 

successfully. It is thus the 

server’s responsibility to 

accept data whenever the 

LINX has sent it. It is also 

the servers responsibility to 

insure that it has received 

an ACK to every DATA 

packet that it sends. 

Sequence: The sequence number is used to maintain an orderly flow of sequenced 

data. For each LDATA record generated by the LINX, the sequence number is 

incremented when a positive acknowledge Type=’g’ is received that has the same 

sequence number. 

Sequence numbers are 1 to 99. Any LDATA reeived by the server with a sequence 

of 1 to 99 requires an ACK before the LINX will send the next record. If the server 

fails to respond within the slave timout then the record will be resent. 

The server should increment the sequence number for each packet sent to the LINX. 

The LINX will respond with an ACK to each DATA packet. 

The server sends a POLL packet with a sequence number of 0 to a specific LINX 

(not a broadcast packet) to cause that LINX to come ONLINE. This tells the LINX 

that there is a valid server which is waiting to receive packets. The LINX responds 

with a Type 0, sequence 0, ‘ON’ status packet. 

Type: This is the packet type. 

ASCII ‘p’ POLL packets (used to bring LINX on line) 

ASCII ‘g’ ACK type packet 

ASCII ‘x’ SDATA is a sequenced data packet from the server 

ASCII ‘u’ UDATA is unsequenced data from a LINX or server 

ASCII ‘s’ SERVER AVAILABLE 

ASCII ‘q’ SERVER UNAVAILABLE 

ASCII ‘l’ LINX AVAILABLE 

ASCII ‘t’ TEST record 

BINARY 0 to 99 LDATA sequenced data packet from the LINX Data Terminals 

BINARY 0 LDATA STATUS data packet from the LINX Data Terminals 

Linx 5 Full Server Implementation 

A LINX 5 Server is an application program that executes on a host computer. 

NetLIO is an example of a server. A full server is one that performs sequenced IO 

with each LINX. The server starts and stops in an orderly manner which makes it 

easy for the BASIC applications to know that there is a program that is accepting 

data or processing transactions. 

A full server maintains a table of all LINX’s that it has communicated with since it 

began its operation. It may also have a table saved in a file to be sure that the 

network it expects is present. 

The server must maintain a transmit and receive packet sequence number for each 

LINX. When the server receives a second copy of a record from a LINX (as 

indicated by a duplicated receive sequence #) then it should ACK the record and 

discard it. This prevents reception of duplicate data when there are a lot of collisions 

and undeliverable packets on the network. 


Normal operation of a full server works like this: 

1) A server broadcasts SERVER AVAILABLE. This is how the LINX determines 

an address to send data to. 

2) The LINX 5’s reply with LINX AVAILABLEs to the server’s address. This 

gives the server an address for each LINX in the network. 

3) The server sends a POLL to each of the specific LINX’s and receives an ‘ON’ 

LDATA STATUS message. The server sends ACK. This causes each LINX’s 

to come ONLINE since now it is certain that the server has received a valid 

address. 

4) LINX 5’s send LDATA to the server as it becomes available. The server replies 

with ACK to each packet received. 

5) The server sends SDATA to the LINX’s. If the server fails to receive an ACK 

from a LINX then it should resend the data. If the server receives an LDATA 

block from the LINX then it should ACK the block before attempting to resend 

the data block. 

6) Periodically (once every 30 seconds) the server should send a SERVER 

AVAILABLE. If a LINX fails to receive either a data block or a SERVER 

AVAILABLE for 60 seconds then it will go OFFLINE. 

7) When the server terminates it broadcasts SERVER unavailable a few times. 

This causes all LINX to immediately assume the OFFLINE state. 

Note that if the LINX receives a UDATA block then it will immediately send it to 

the application program if the buffer is free. If there is no place to put the data, it is 

ignored. UDATA is not ACKed. UDATA does not assure delivery so it should only 

be used in peer to peer applications where the application programs are assuring that 

the data gets handled properly. 

Linx 5 Limited Server Implementation 

Limited servers are very simple. A limited server sends and receives only UDATA 

packets. The limited server needs to have the full network address of each LINX 

that it needs to communicate with stored in a table somewhere. The BASIC 

applications send only UDATA packets to the NET device using the network address 

obtained from UDATA received from the server. 

Since it is entirely the application programs responsibility to assre correct 

transmission of data, there is no handshaking at the LINX protocol level. 

Alternate Servers 

An Alternate Server just waits around and listens to the network. If more than 65 

seconds goes by without the alternate receiving a Server Available broadcast, then 

the Main Server is probably down (or the Server Available messages are lost due to 

network traffic or signal noise problems). The alternate server can then begin 

operation as a main server. 


If a Main Server wants to take over operation from an alternate server then it should 

start out by listening to the network for up to 65 seconds. If an alternate server is not 

detected then it can begin normal operation. If an alternate server is detected then 

the main takes control by: 

1. Sending a direct POLL to the alternate server. 

2. Receiving an ACK from the alternate server. 

3. Issuing broadcast Server Unavailables. 

4. Starting as a normal server. 

LINX 5 IPX Packet 

The IPX Packet is structured as follows: 

Position Field Value 

0 CheckSum: FF FF 

2 Length: xx xx 

4 Transport Control: 00 

5 PacketType: 04 

6 Destination Network: xx xx xx xx 

10 Destination Node: xx xx xx xx xx xx 

16 Destination Socket : xx xx 

18 Source Network : 00 00 00 00 

22 Source Node : xx xx xx xx xx xx 

28 Source Socket : xx xx 

30 LNA Packet : 13 to 254 bytes of data 

CheckSum: Set to FFFFand not used. 

Length: This is 30+ the size of the LINX Packet. AS with all two byte values in the 

packet, this is in MSB, LSB order (the opposite of the x86 standard). 

Transport Control: Set to 0. May be set to a non-zero value on packets routed by a 

file server. 

Packet Type: This is 4 for IPX communications. Records received from the server 

may have a different value. This is ignored by the LINX. 

Destination Network: The LINX sets this to 0 for peer/peer packets. If this is a 

reply to a packet from the server this will be set to the servers network number. 

Novell uses network numbers of 1, 2, 3… for each physical network attached to a 

given set of file servers. 

Destination Node: Same as the Ethernet address. Set to FFFFFFFFFFFF for 

broadcast packets. 

Destination Socket: The LINX will IGNORE any packets that do not have the same 

socket that is defined in the System Menu. 


NOTE: LINX will contact NOVELL and obtain one or more permanent socket 

assignments. Novell assigns sockets starting at 8000h and going up. The NOVELL 

shell randomly assigns sockets from 4000-7FFF when an OPEN SOCKET request 

is made that does not ask for a specific set of socket numbers. We will try to get 8 

numbers. 

The default LINX 5 socket number is currently CC D8 (where CC is the MSB). 

Source Network: The LINX sets this to 0. Packets received from a host will have a 

network address which must be used during replies to the host. 

Source Socket: When the LINX receives packets from a server this may be any 

value. The LINX always replies to the server using the full 12 byte (Network, Node, 

Socket) address that the server used in its last accepted packet. 

LINX 5 LLC Packet Structure 


0 DSAP: EO 

1 SSAP: EO 

2 Control: 03 

3 IPX Data: 43 to 576 bytes of data 

DSAP: Destination Service Access Point. This is always EO for IPX and XNS 

protocols. 

SSAP: Source Service Access Point. This is always EO for IPX and XNS protocols. 

Control: This is 03 for UI (unnumbered information) packets. All LINX packets are 

UI. See 802.2 LLC Description for more info. Note that if the low order bits are 

xxxxxxx0 or xxxxxx01 then there is a second byte to the control field. 

LINX 5 Ethernet Packet Structure 

The LINX 5 supports the full set of Ethernet frame types. These are Ethernet II, 

IEEE 802.2, IEEE 802.3 with SNAP, and Novell 802.3. The following illustrates the 

Novell IEEE 802.3 compatible frames. These differ only slightly from other 

“Ethernet” frames. 

Each frame contains octets (bytes) which are received least significant bit first. 

When these are shown as hex, the least significant digits will be on the right. When 

a 16 bit or larger value is used, the most significant octet is received first. This is the 

opposite of the method used by the x86 family. 


Each frame consists of: 


-8 Preamble: 55 55 55 55 55 55 55 

-1 SFD: D5 

0 Destination: xx xx xx xx xx xx 

6 Source : xx xx xx xx xx xx 

12 Length : xx xx 

14 LLC Data : 46 to 579 bytes of data 

n FCS : xx xx xx xx 

Preamble : Hardware generated and checked 

SFD: Start Frame Delimiter, hardware generated and checked 

Destination address: 6 bytes MSB first. An address of FF FF FF FF FF FF is a 

broadcast address that will be received by all NICs that have broadcast accept 

enabled. 

I/G bit: The first byte (MSB) uses the least significant bit (bit 0) for 

Individual/Group multicast addressing. The LINX always sets this bit to 0 except 

during tests when it uses the broadcast address. 

U/L bit: Bit 1 is used for Universal/Local address administration. The LINX sets 

this bit to 1 for software addressing. NOTE: At some future time LINX may begin 

using IEEE assigned addresses burned into ROM. At that time the user will no 

longer be allowed to enter or modify the LINX address. 

I/G (bit 0) = 0 Individual Address 

I/G (bit 0) = I Group Address 

U/L (bit 1) = 0 Globally administered (IEEE) address 

U/L (bit 1) = 1 Locally administered address 

On the LINX, there are 2 System Menu parameters that are used to compose the 

Ethernet address. These are the “Terminal Number” and the “Ethernet Address” 

fields. The Terminal Number is a decimal value from 1 to 99. It is placed into the 

6 th byte of the address. The first 5 bytes of the address are derived from the hex 

Ethernet Address field. 

Source Address: 6 bytes MSB first. Same format as Destination. 

Length: the number of bytes in the LLC Data field. MSB first. 

FCS: Frame check sequence. A 32 bit CRC checked by hardware. 


Appendix A 

The Whole Packet 

-8 ENET -8 Preamble: 55 55 55 55 55 55 55 

-1 ENET -1 SFD: D5 

0 ENET 0 Destination: xx xx xx xx xx xx 

6 ENET 6 Source: xx xx xx xx xx xx 

12 ENET 12 Length: xx xx 

14 ENET 14 LLC Data: 46 to 287 bytes of data 

14 LLC 0 DSAP: E0 

15 LLC 1 SSAP: E0 

16 LLC 2 Control: 03 

17 LLC 3 IPX Data: 43 to 284 bytes of data 

17 IPX 0 CheckSum: FF FF 

19 IPX 2 Length: xx xx 

21 IPX 4 Transport Control: 00 

22 IPX 5 PacketType: 04 

23 IPX 6 Destination Network: xx xx xx xx 

27 IPX 10 Destination Node: xx xx xx xx xx xx 

33 IPX 16 Destination Socket: xx xx 

35 IPX 18 Source Network: 00 00 00 00 

39 IPX 22 Source Node: xx xx xx xx xx xx 

45 IPX 28 Source Socket: xx xx 

47 IPX 30 LNA Packet: 13 to 254 bytes 

47 LNA 0 DataSiza: xx Number of bytes of Data (may be 0) 

48 LNA 1 Master: xx Concentrator/Master 

49 LNA 2 Station: xx Terminal number that is responding 

50 LNA 3 Retries: xx Total retry count 

51 LNA 4 Sequence: xx Record sequence number 

52 LNA 5 Type: xx Transaction number or block type 

53 LNA 6 Data: xx 0 to 248 bytes of data 


53 APP The application data can be status messages 

54 APP such as ERROR, ON, OF, MO, ND. It can be network 

55 APP Directives such as S. If there are less than 

57 APP 7 bytes of data then this is padded with 0s. 

58 APP The application data is always followed by two 

59 APP termination bytes: 7E then 00. 

60 ENET n FCS: xx xx xx xx 


Net API Programmers Reference 

Guide 

Function List 

Include File: 

NetAvail 

NetFlush 

NetRead 

NetOpen 

NetClose 

NetErr 

NetErrText 

Defines.h 

NetAPI.h 

: TRUE when packet is available for reading 

: Discards all unread packets 

: Reads a pending packet 

: Opens the NET API and sets its parameters 

: Closes the API 

: Returns the last error code 

: Returns the last error code and text 

: Required include files and constants 

: Function declarations 

LINX V API Programmers Reference Guide Net API Programmers Reference Guide • 17

Overview 

This simple API (Applications Program Interface) is used to perform simple network 

communications. The NetOpen routine is optionally called to set the size and 

number of receive buffers, as well as the sockets used for send and receive. If it is 

omitted then defaults will be used. 

Reading should consist of calling NetAvail until TRUE. A call to NetRead will 

obtain the data and where it came from (NetAddress). Note that reading is always in 

progress and can occur in any order. The order with which records are fetched from 

NetRead may not correspond to the order in which they were sent. 

NetWrite will send a record to another computer. 

If any routine has an error, the text description of that error can be obtained with 

NetERRText. If you only need the non-zero error code then call NetErr. 

You MUST call NetClose before exiting your program. Failure to do so may leave 

network resources unavailable for the next time you run the program. 

Predefined Types 

The standard unsigned types are: 

BOOL unsigned int 

WORD unsigned int 

BYTE unsigned char 

DWORD unsigned long 

The Motorol Format (MSB First) swapped types are: 

XBYTE, XWORD, and XDWORD 

The Net Addresses are supplied in: 

Typedef struct { 

XDWORD Network, //Cabling system # of a network 

XBYTE Node [6]. // Actual card address 

XWORD Socket; // Socket number 

] NetAddress: 

Function: NetAvail ( ) 

Usage: This is called to find out if there is any pending receive blocks 

Returns: TRUE if a block is available for reading 

Proto: BOOl Net Avail (void) 

Function : NetWrite ( &NetAddress, &data, n) 

18 • Net API Programmers Reference Guide LINX V API Programmers Reference Guide

Function: NetFlush ( ) 

Usage: Clears (discards) any pending receive blocks. 

Proto: void NetFlush(void) 

Function: NetRead( &NetAddress, &data, n) 

Usage: If there is no block available for reading then this will wait until one is. Use 

NetAvail to check for block availability. The source address of the data is placed in 

NetAddress. The packet data is copied to the data buffer for a maximum of n bytes. 

It is null terminated by NetRead so n must be 1 less than the actual buffer size. If n 

is 0 then the buffer is assumed to be large. If n,0 then the packet will be ignored 

(flushed). 

Returns: # bytes read or 0 if an error occruured. 

Proto: int NetRead (NetAddress* s, BYTE*d, int nmax) 

Function: NetWrite (&NetAddress, &data, n) 

Usage: Writes a block (data) of n bytes to the network. 

In NetAddress: 

The Node must be set to the correct destination node. This is a six byte long LSB 

first value. 

Network must be set to 0 for the local network. This is a LSB first format unsigned 

long value. 

The Socket is not used (it defaults to the source socket). 

Returns: TRUE if the packet was sent successfully. 

Proto: BOOL NetWrite (NetAddress* a, BYTE*d, int n) 

Function: NetOpen (buffersize, count, ssocket, 

dsocket) 

Usage: Initializes the network facility. This is optionally called to allocate Receive 

buffers and Socket numbers. NetOpen will always return TRUE after the first 

successful allocation. Use 0 for any parameter that should default. 

Returns: TRUE if successful. 

Proto: BOOL NetOpen (WORD bufsize, WORD bufcnt, WORK ssocket, WORD 

dsocket) 

Function: NetClose ( ) 

Usage: Releases the sockets and buffers Must be called for normal termination. 

Proto: void NetClose (void) 

LINX V API Programmers Reference Guide Net API Programmers Reference Guide • 19

Function: NetErr ( ) 

Usage: Returns the last error code 

Proto: WORD NetErr (void) 

Function NetErrText (&string) 

Usage: Returns the last error code and its text description 

Proto: WORD NetErrTest (char*txt) 

20 • Net API Programmers Reference Guide LINX V API Programmers Reference Guide

LINX 5 DOS Utilities Users Guide 

Program List 

L5List.exe 

: List the LINX 5’s on the network 

L5Chat.exe : Direct interaction with LINX 5’s 

L5Load.exe : Download files to one or more LINX 5’s 

L5Go.exe 

: Start a loaded Basic application 

L5Abort.exe : Stop an executing Basic application 

Close.exe 

: Close an open socket 

Each DOS utility accepts switch of /? to get a list of command line parameters. 

L5List.exe : List the LINX 5’s on the network 

L5List/flags 

/D : show LINX Display 

/C : display all packets 

/R : display all received packets 

/T : display all transmit packets 

/V : show software version in units 

/S : show the server status 

/P : suppress headings 

LINX V API Programmers Reference Guide LINX 5 DOS Utilities Users Guide • 21

L5Chat.exe : Direct interaction with LINX 5’s 

L5Chat/flags 


/R : display all received packets 

/T : display all transmit packets 

/P : suppress headings 

/F : always chat with the first unit 

/S : suppress headings 

/X : always show the unit table 

/D : suppress display of file while sending 

Allows you to directly enter commands for a single LINX 5 terminal on the network 

and see the response. 

L5Load.exe : Download files to one or more LINX 

5’s 

L5Load filename/flags 

/Q : quiet mode 


/F : load only the first terminal 

/S : load a selected terminal 

/X : show the unit table 

/O : load the operating system 

/D : display file while sending 

/W : don’t wait a few seconds after loading 

/B : show End by SYSTEM messages 

Loads a file to one or more LINX 5 terminals. 

Environmental variables: 

L5OS = default operating system to load. 

L5LXE = default LXE basic file to load 

22 • LINX 5 DOS Utilities Users Guide LINX V API Programmers Reference Guide

L5Go.exe : Start a loaded Basic application 

L5Go/flags 



/F : run only the first terminal 

/S : run a selected terminal 


L5Abort.exe : Stop an executing Basic application 

L5Abort/flags 



/F : abort only the first terminal 

/S : abort a selected terminal 


/O : kill the operating system and reboot 

/W : don’t wait for reboot to complete 

Close.exe : Close an open socket 

If a program aborts during operation or if control-Break is pressed then an Ipx socket 

is left open. Use close to force it closed. 

LINX V API Programmers Reference Guide LINX 5 DOS Utilities Users Guide • 23

LINX 5 Network Activity Statistics 

Introduction 

Here we examine the network load presented by LINX 5 terminals in a number of 

different circumstances. Lets first examine the nature of Ethernet networks. By 

definition, traditional Ethernet networks have a data rate of 10 million bits per 

second. 

This means that around 1 million bytes (characters) can be sent on the network every 

second (actually this is 1.25 mb/s, but lets be conservative). Now an additional limit 

says that every network packet must be at least 64 bytes long. This means that 

around 15,000 minimum size packets can be sent every second. 

Since virtually every interaction consists of both a REQUEST packet and a 

RESPONSE packet, this gives us 7,500 INTERACTIONS per second as the absolute 

maximum number of actions that can occur on an Ethernet REGARDLESS of the 

type of computers being used. 

The MAXIMUM packet size is 1514 bytes (for ETHERNET). This is far more than 

the 100 byte maximum the LINX imposes. (Note the 1514 limit gives you a 660 

packets/sec max). Novell imposes a more limited length of 576 byte which is 1700 

packets/second. 

After factoring in the various network packet headers for the networks the LINX 

operates under, we find that ONLY 6 bytes are left for actual LINX application data 

in each packet that is sent or received of the MINIMUM size. 

Passive Loading 

Definition: The amount of traffic presented by LINX terminals when they are not in 

use by any LINX server 

Percentage: 0% 

Reason: Unless a SERVER presents either BROADCAST or SPECIFIC polls then 

NO LINX will respond or affect traffic. The LINX NEVER issues a broadcast 

packet. 

24 • LINX 5 Network Activity Statistics LINX V API Programmers Reference Guide

Inactive Loading 

Definition: A LINX Server program is running on one or more host computers on 

the network. No LINX 5 is being sent data, and no data needs to be sent to the LINX 

5’s. 

Percentage: 0.007% per LINX 5 terminal 

0.667% for 100 LINX 5 terminals 

6.677% for 1000 LINX 5 terminals 

Reason: Each LINX is polled by the server once every 30 seconds. In addition, 

every 30 seconds a BROADCAST server available message is sent to discover any 

LINXes that have just been added to the network. From out introduction we see that 

the percent of use is 100 * (n 1/7500 + 1/15000), where n is the number of LINX 

terminals on the net. 

Active Loading 

Definition: Here we assume that the terminals are used in some for of database 

activity with the host network system(s). Our worst case scenario is individual 

database lookups for each employee while clocking in or out. Note that we have 

already observed that the MINIMUM 64 byte network packet gives us 6 bytes of 

EMPLOYEE number data from the employee card without sending more than the 

minimum packet length. Now lets assume that to clock in an employee requires a 

full 100 data bytes from the data base. Now during peak activity, lets examine 

network loading… 

Percentage: 0.2% = 1 employee/sec with 1 LINX ** (See note) 

= 3600 employees per hour ** (See note) 

Percentage: 0.2% = 3 LINXes/employee/sec 

= 3600 employees per hour – NO PROBLEM 

Percentage: 0.6% = 10 LINXes/employee/sec * (See note) 

= 10000 employees per hour 

Reason(s) 

** It is unlikely that a LINX can actually handle 1 employee per second. 

Examination of actual applications shows that in even the simplest swipe badge and 

walk on systems, between 3 and 6 seconds should be allowed per scan. This is due 

to the empirical problem of moving people past a fixed station. In addition, host 

database systems may have problems with more than one or two accesses per 

second. 

* As a rule of thumb, we advise that if you have 1000 employees who must clock in 

or out in a 15 minute period then you will need 5 terminals. The faster you need to 

process each person, the more terminals you will need. 

LINX V API Programmers Reference Guide LINX 5 Network Activity Statistics • 25

Conclusion 

From the above, it is obvious that even a large LINX network does not represent a 

significant load on an Ethernet system. The fact that every 30 seconds, the LINX 

Server program issues a SERVER AVAILABLE message should not be a cause for 

concern. 

As a thought experiment, The number of LINXes needed to use 50% of the network 

bandwidth (assuming that every LINX needs to perform ONE transaction (request 

and response) with the host computer every second) is more than 3000 units ON A 

SINGLE NETWORK. This should be considered an unreasonably huge number. 

26 • LINX 5 Network Activity Statistics LINX V API Programmers Reference Guide

LINX V API Programmers Reference Guide LINX 5 Network Activity Statistics • 27

API Programmers Reference Guide - LINX Data Terminals

Create successful ePaper yourself

Delete template?

Save as template?