LAN Programming
Applies to: v10
Novell/IPX programming is DOS-era. v10 still ships
IPX.H, but nothing in the sources states that the IPX channel support described here works in v10: unverified.
Socket Numbers from Novell
The sixteen socket numbers 80BB through 80C2 and 86D0 through 86D7 (hexadecimal) are registered with Novell by Galacticomm for use in Worldgroup software. Novell assigns “well-known” socket numbers for released software out of the range 8000 to FFFF. Alternatively, socket numbers 4000 through 7FFF are available for dynamic or experimental usage. Socket numbers 0000 through 3FFF are reserved by Novell, and may be used in accordance with Novell’s instructions (e.g. such as for socket 0452, Service Advertising Protocol).
A value of zero for the socket parameter of btusdf() means pick an available dynamic socket number (4000 to 7FFF). In this case, the actual socket number assigned is available in the global integer lansop (page 27).
Byte Order
You will encounter a socket number with reversed byte order when you are dealing with the IPX headers yourself on IPX Virtual channels in raw-packet mode (page 195).
Warning: The length, dstsoc (destination socket), and srcsoc (source socket) fields of an IPX header contain values stored with the most-significant-byte in the lower address. This is foreign to Intel processors, so you need to remember to swap the bytes of these fields.
The following macro might be helpful for this (and is included in IPX.H):
#define hilo(i) (((unsigned)(i)>>8)¦((unsigned char)(i)<<8))This simply swaps the two bytes of a 16-bit int or unsigned variable.
Multiple Channels on the Same Local Socket
You can define several channels or several channel groups on the same local socket number if you follow a few rules.
Do not define IPX channels (Direct or Virtual) on the same local socket number as SPX channels.
If you define more than one channel group on the same local socket number, the groups must use consecutive channels.
You can define multiple channel groups on the same local socket number as long as the groups are defined over consecutive channel numbers, and groups defined on a given socket are either all IPX, or all SPX — don’t mix and match IPX and SPX on a single socket. You can however, mix IPX Direct Circuits with IPX Virtual Circuits on the same local socket.
Do not connect IPX channels to SPX channels. You can, however, connect an IPX Direct Circuit with an IPX Virtual Circuit.
Do not connect multiple IPX channels between two nodes (computers) using the same local socket number on both ends.
You can have several SPX connections on one network/node/socket talking one-to-one with several SPX connections on another network/node/socket. You cannot do this with IPX, however. The only way IPX has of distinguishing what channel an incoming IPX packet is for is the local socket (of course) and the network/node/socket that the packet originated from. SPX has connection ID’s to distinguish who’s talking to who, and there can be several on one socket. To have multiple IPX connections between two nodes using GSBL, either the local end, the remote end, or both, must use separate sockets.
LAN Channel State-Machines
IPX Direct Circuit Call
Terminating:
bturst(chan); (direct circuit address is subsequently undefined)
Incoming or outgoing:
btucmd(chan,"W000000010000C0A810184007M");
IPX direct channels are always in the “communicating” state.
IPX Virtual Circuit Call
Terminating:
bturst(chan); (channel reverts to raw-packet mode)
Incoming:
btutrg(chan,30); (prep for incoming 30-byte IPX header)
btusts(chan) == 4
btuict(...); returns a 30-byte IPX header (page 196), and inside it, the source network/node/socket contains the 12-byte node address in binary
btucmd(chan,"W<24-digit node address in ASCII hex>M");
Outgoing:
btucmd(chan,"W000000010000C0A810184007M");
States:
raw-packet mode
communicating
SPX Call
Terminating when in session:
btucmd(chan,"T");
wait for btusts(chan) == 36 (You should timeout this wait, in case a status 36 never comes for some reason)
bturst(chan); (optional)Terminating otherwise:
bturst(chan);
Incoming:
btucmd(chan,"L");
wait for btusts(chan) == 34
Outgoing:
btucmd(chan,"W000000010000C0A810184007M");
wait for btusts(chan) == 35
States:
idle
waiting for incoming call
waiting for outgoing call
connection established
terminating
The SPX Channel State-Machine
Each SPX channel is always in one of these five states:
Idle
Listening
Outdialing
Connected
Terminating
Here’s a chronological diagram of how two applications based upon the GSBL might communicate over SPX channels:
| Calling party | Listening Party |
| btucmd(chan,"L"); | |
| btucmd(chan,"W000000010000C0A810184007M"); | |
| status 35 | status 34 |
| : | : |
| : | : |
| : | : |
| btucmd(chan,"T"); | |
| status 36 | status 31 |
Note: once the link is established, it is symmetrical; either channel can terminate it. In the above diagram this means, for example, that the listening party might decide to terminate the connection with btucmd(chan,"T"). It would soon get a status 36, and the calling party would get a status 31.
If either party abruptly aborts the connection with bturst(), the other party will eventually get a status 39. The aborting party will get no special status code.
Idle SPX Channel
All SPX channels become idle immediately after any of the following:
Definition by btusdf() (only allowed once per program load)Reset by bturst() (may be done at any time)Status 31: connection explicitly terminated by the remote partyStatus 39: watchdog termination, meaning the other party has just disappeared, or some other transmit or connection error (see page 141)When a channel is idle, and only when a channel is idle, you can issue dial-out or listen commands.
Listening SPX Channel
After issuing the listen command (e.g. btucmd(chan,"L")), the channel is in the listening state, and ready to receive an incoming call from another network party (using SPX). Status 34 indicates when such a call has come in and been completed. In that case, the channel moves to the connected state.
The listening state has no timeout, and a channel may remain in the listening state indefinitely. To give up waiting for an incoming call, and return a channel to the idle state, call bturst().
Outdialing SPX Channel
After issuing the dial-out command (e.g. btucmd(chan,"W...M")), the channel is in the outdialing state, and trying to make connection with the network address specified in the dial-out command. Status 35 indicates when the call has gone through and the channel is in the connected state.
The dial-out command may timeout, in which case a status 39 indicates that the call is aborted and the channel is reverting to the idle state. To give up waiting for an outgoing call to complete, and return a channel to the idle state, call bturst().
Connected SPX Channel
After an SPX channel has established a connection with another party on the network, you can transmit to the party (btuxmt(), btuxct()) and receive from it (btuinp(), btuict(), btuica()). Now most of the hardware specifics vanish, and the channel acts much like any other channel on the GSBL.
SPX connections that have been completed (via status 34 or 35) can end in one of four ways:
Explicitly, by issuing the T command and then waiting for status 36Remotely, by receiving a status 31 (other side terminated — see page 139)Abortively, by resetting the channel (bturst())Unexpectedly, by receiving a status 39 (watchdog abort)Terminating SPX Channel
When you issue the terminate command (e.g. btucmd(chan,"T")), the channel moves to the terminating state. This is the polite way to end a connection, because the SPX system tries to make sure the other party knows the connection is ending. To end a connection quickly, with no muss and no fuss, just call bturst(), and the channel moves immediately to the idle state.
After issuing the terminate command on a channel that is in the connected state, the channel moves to the terminating state. Pretty soon, a status 36 indicates that the other party has acknowledged the termination and the connection has ended gracefully. The channel returns to the idle state.
On the other hand, a status 39 indicates that the termination notice was not acknowledged, and we can’t be sure what the other party thinks. After a status 39, the channel ends up in the idle state.
IPX Virtual Circuits in Raw Packet Mode
___________ / / 0| chksum | (set by IPX)
| | |___________|
| | 2| length | Total number of bytes, incl header
| | |___________| Range 30-576, WARNING: MSB FIRST!
| | 4| trnspt | (set by IPX)
| | 5| paktyp | Packet type, 4=IPX packets
| | 6| |
| | | dstnet | Destination network, 4 binary | | | bytes, | right-justified, and zero-
| | |___________| filled
| | 10| |
| | | |
| | | dstnod | Destination node, 6 binary bytes,
| | | | right-justified, and zero-filled
| 30 | |
| bytes |___________| | | 16| dstsoc | Destination socket | | |___________| WARNING: MOST SIGNIFICANT BYTE FIRST! | | 18| |
30 | | srcnet | Source network, 4 binary bytes, to | | | right-justified, and zero-filled 576 | |___________|
bytes | 22| |
| | | |
| | | srcnod | Source node, 6 binary bytes,
| | | | right-justified, and zero-filled
| | | |
| | |___________|
| | 28| srcsoc | Source socket
| \ |___________| WARNING: MOST SIGNIFICANT BYTE FIRST!
| 30| |
| | |
| | |
| | datbuf | Data buffer, containing 0 to 546
| | | bytes
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
\ |___________|
Figure 6-1: IPX Virtual Raw Packet Format
Before transmitting a raw IPX packet, (that is, before transmitting a packet on an IPX Virtual channel in raw-packet mode), you must set the following fields of the packet:
length Length of entire packet, including header, range 30 to 576 WARNING: most significant byte first
paktyp Packet type (4 for IPX)
dstnet Destination network
dstnod Destination node
dstsoc Destination socket
WARNING: most significant byte first
datbuf Data buffer, 0 to 546 bytes
The following fields are automatically set by IPX:
chksum Checksum
trnspt Transport control
srcnet Source network
srcnod Source node
srcsoc Source socket
Incomplete Packets Under Raw-Packet Mode
WARNING: You can only transmit complete packets in raw-packet mode. Fill the length field (in hi-lo byte order) with the total number of bytes in the packet, including the IPX header. The GSBL will use this field to determine packet boundaries. If you return to btuscn() in your main loop with a partial packet in the output buffer, the packet may be lost.
Also, if you don’t make sure that the length byte contains the actual packet length, or if you otherwise mess up packet alignment, then total trash could be transmitted via IPX, possibly clobbering your file server.
You could use this property (that partial raw packets will be lost) to detect when a packet transmitted in raw-packet mode has actually been totally and completely transmitted.
First, let’s look at the problem: it is not enough just to poll at btuoba() (or to enable and then wait for status 5) to know when transmitting is done — the GSBL may be done with a packet, but the low level Netware IPX interface may not have completed the associated “Send Event Control Block”. So you could diligently make sure the output buffer was empty, and then innocently call bturst() thereby cancelling the data before it went out! You need to make sure IPX has finished transmitting the packet.
If after transmitting a raw packet, you “transmit” a single nul (as in btuxct(chan,1,"\0")) and then wait for btuoba() to indicate an empty buffer (when it returns output buffer size minus 1), the raw packet preceding the nul will have been completely transmitted, and the nul will be discarded.
struct {
struct ipx ipx;
char data[NBYTES];
} ipxpkt;
/* Fill up ipxpkt somehow. */
btuxct(chan,sizeof(ipxpkt),&ipxpkt);
btuxct(chan,1,"\0");
while (btuoba(chan) < OSIZE-1) {
btuscn();
}
bturst(chan);This code is an excerpt only (btusiz(), btuitz(), btusdf(), btuend() calls are all essential but they are not shown above). And the while-loop should really have a timeout. And you would rarely call btuscn() only inside a loop like that. But this should give you an idea of what’s involved in this little trick to detect total completion of raw packet transmission.
IPX Raw-Packet Transmit Example
For example, let’s say you wanted to transmit the alphabet on an IPX Virtual channel in raw-packet mode to socket 4007 hex on node 2 of network 1. Assume you are using local socket 5008 hex. Here is code that would do this:
#define hilo(i) (((unsigned)(i)>>8)|((unsigned char)(i)<<8))
struct ipxhdr { /* an IPX header contains... */
int chksum; /* checksum */
int length; /* 30-576: header PLUS rest of packet (hi-lo) */
char trnspt; /* IPX sets to 0 */
char paktyp; /* 0=unknown 4=IPX 5=SPX */
char *stnet[4]; /* destination network*/
char dstnod[6]; /* destination node */
int dstsoc; /* destination socket (hi-lo)*/
char srcnet[4]; /* source network */
char srcnod[6]; /* source node */
int srcsoc; /* source socket (hi-lo)*/
};
#define IPXMAX 546 /* max length of data field of IPX packet */
struct ipxpak { /* an IPX packet contains*/
struct ipxhdr hdr; /* IPX header */
char datbuf[IPXMAX]; /* 0 to 546 data bytes */
}
struct ipxpak xmtpak;
char net[]={0,0,0,1};
char nod[]={0,0,0,0,0,2};
char alphabet[]="ABCDEFGHIJKLMNOPQRSTUVWXYZ";
int chan=0;
char *malloc();
main()
{
btuitz(malloc(btusiz(1,256,2048)));
btusdf(chan,1,6,0x5008,2);
xmtpak.hdr.length=hilo(26); /* xmtpak.hdr.length=0x1A00 */
xmtpak.hdr.paktyp=4;
movmem(net,xmtpak.hdr.dstnet,6);
movmem(nod,xmtpak.hdr.dstnod,4);
xmtpak.hdr.dstsoc=hilo(0x4007); /* xmtpak.hdr.dstsoc=0x0740 */
movmem(alphabet,xmtpak.datbuf,26);
btuxct(chan,&xmtpak,sizeof(struct ipxhdr)+26);
while(btuoba(chan) < 2047) {
btuscn();
}
btuend();
}Note: this program is shown as a coding example and is almost useless otherwise, especially in its limited versatility and in its failure to check for erroneous return codes.
The calls to btusiz(), malloc(), and btuitz() prepare for one channel with a 2048-byte output buffer and a 256-byte input buffer.
The call to btusdf() defines one IPX Virtual channel using socket 5008 hex, with 2 ECBs. Note that the specification of the socket number here uses natural (Intel) byte order.
Galacticomm Terminal Configuration (GTC) Protocol
GTC enables one GSBL-based program to tell another that it is willing to preprocess the other’s ASCII input.
For example, a terminal program based on GSBL function calls can tell an online service program based on GSBL that the terminal will buffer line input before sending it to the online service.
In this section we’ll talk about the “terminal” and the “server” as the GSBL program volunteering to preprocess input and the GSBL program that relinquishes input preprocessing, respectively. Other applications could make use of this feature, but the terminal/server situation is why GTC was developed, and makes for a clear example.
In this case, each of the programs (terminal and server) consists of a copy of the GSBL and an application program that uses it.
The usurpation of the server’s input handling is detected and allowed by the server GSBL and is transparent to the server application program. GTC service starts with the terminal program sending a “greeting message” to the server GSBL. After that, the server GSBL will notify the terminal GSBL as to the current input mode. The terminal GSBL passes all such GTC information, in the form of status codes, to the terminal application program for processing.
For enhanced compatibility, a GTC-compatible server will not require a GTC-supporting terminal program. It is up to the terminal to request GTC before the server starts depending on it. At the same time, if a non-GTC server ignores the terminal’s initial greeting message, the terminal GSBL will not generate GTC status codes.
If you don’t want the main program to have to deal with GTC, then just don’t ever send the “greeting message” (don’t call btucmd(chan,"G")).
A new greeting must be issued after a channel reset from either the server or the terminal side.
Several varieties of input are supported, so that features like editor input word-wrap, teleconference chat, and password input operate transparently — that is, just as they would calling over a non-LAN GSBL channel. The special case of suppressed output during line input (as is used so well in the teleconference) can be handled at the option of the terminal program: (1) suppress the output while entering a line; or (2) go ahead and display the output, but “move” the input line down to the new prompt.
The GTC protocol for IPX packets is based on:
IPX header with packet type 0 (unknown packet)
For SPX packets:
SPX header with data stream type F0 hex
Data fields:
Greeting message:
(empty data buffer)
The terminal sends this to the server (the G command) to volunteer to preprocess the server’s ASCII input. The server GSBL takes note that it is communicating with a GTC-compatible program.
Input mode message:
“GTCI” (‘I’ means input configuration)
1 byte inmode input mode (see below)
1 byte maxinl maximum input line length (0=unlimited)
These messages are transmitted from the server to the terminal to tell the terminal how to treat the server’s input (that the terminal is gathering, for example, from an operator at the keyboard, or from a disk file).
Input modes (decimal)
40 Locked out
41 Binary
42 ASCII line mode without echo
43 ASCII line mode with echo (limit line length)
44 ASCII line mode with echo and word-wrap (limit line length)
These input modes are also the status codes that will eventually appear to the terminal application program when it calls btusts(). When the status code is 43 or 44, another status byte follows immediately, which is the input line length, where 0 is unlimited. See starting on page 137 for more details on these status codes.
ctrl+S Pause with GTC
Also we recommend that a terminal program locally process the ctrl+S pause of server output. This function cannot be handled by the server due to packetization: by the time the server would get a ctrl+S, it may have already shipped out several huge packets.