IPX and NetBIOS for OS/2

Programming IPX and NetBIOS is easier than you think

Barry Nance

If your organization is like the one I work in, in the past two years you've grown to have a mixture of DOS, DOS-and-Windows, and OS/2 machines in your office. Your file servers probably run Novell NetWare, IBM OS/2 LAN Server, or a combination of the two. I've found that writing software for such an organization can be interesting, to say the least.

When my team recently developed a SQL Server-based application that everyone on the LAN could access, I wrote the over-the-wire message-passing software for each of the three platforms. I also wrote the code that, through SQL Server's 16-bit programming interface, delivered SQL statements to the database manager and sent responses back to each workstation.

In a heterogeneous LAN envir onment, message packets don't carry an identifier of the operating system or environment running on each computer. Messages flow through the wire from PC to PC (most often from workstation to file server and back--the vast majority of LAN messages are file-server packets), and it's up to the sender and receiver to agree on the content and purpose of each message.

If you transmit a message packet from a computer that uses the EBCDIC character set, an ASCII-based receiver will have to translate the textual portions of the message from EBCDIC to ASCII. For nontext (i.e., binary) data fields, some computers store low-order bytes first, and some computers store high-order bytes first.

However, between computers that use the same character set and store binary data in the same format (e.g., DOS, DOS-and-Windows, and OS/2 on an Intel CPU), you can send and receive message packets without worrying about the operating systems the sender and receiver are using. The programming interface is the only differ ence from platform to platform. In a DOS environment, you invoke Interrupt 5Ch to access NetBIOS or Interrupt 7Ah to access IPX.

From within an OS/2 program, you call functions in a DLL, which comes with the requester (i.e., LAN Server or NetWare) that allows the workstation to access the file server. The NetBIOS function you'll use most often is NetBiosSubmit(). One of the data items in the NCB (Network Control Block) indicates which operation that NCB should perform. While NetBIOS uses NCBs, IPX uses ECBs (Event Control Blocks). NCBs and ECBs are data structures containing information about the message packet that you want to send (or that you expect to receive), including the address and length of the message buffer. IPX has separate functions for different operations: OpenSocket(), CloseSocket(), IpxRe-ceive(), and IpxSend().

Requests and Responses

For the new application my team created, SQL Server runs on an OS/2 2.1 PC. Workstations might run OS/2, DOS, or Windows. The workstation soft ware, written by the other team members, calls a low-level client module when the application needs to access the database. The client module transmits the request over the wire to the database-server PC.

At the database server, several operations take place. A computer program receives the request, delivers the SQL to SQL Server, binds the result to a data item in the program, and transmits the data item in a message packet back to the client workstation. The program in the database server, running concurrently alongside and interfacing with SQL Server, launches a different thread to handle each request.

As is true for most--if not all--relational DBMSes, SQL Server includes multiplatform enablers that the team could have used to make the workstation-to-server communications link. The SQL Server enabler is a DOS TSR program, called DBNMPIPE, which implements named pipes over NetBIOS. The enabler does essentially what my program modules do--redirect SQL statements across the LAN.

But the team wanted snappier performance than the enabler, based on named pipes, would provide. The team wanted the client software to take as little memory on DOS machines as possible. And the team wanted an over-the-wire delivery system for SQL statements that would work equally well through either NetBIOS or IPX.

Talking with NetBIOS and IPX

This last criterion became important when a second group of people, on a separate LAN, wanted to use the application. While the first group used NetBIOS to access LAN Server file servers, the second group used IPX to access NetWare servers. The second group also strongly resisted adding Novell's NetBIOS emulator on top of the IPX protocol stack they already had in place.

Replacing the NetBIOS calls with IPX calls was almost a one-for-one process. The changes to the low-level code were simple. The programming techniques for NetBIOS datagrams and IPX datagrams are similar, making it easy to send and receive over-the-wire messages in OS/2 programs using either pr otocol.

With the NetBIOS interface, the sender and receiver add their respective names to the NetBIOS name table using the NB_ADD_NAME_WAIT command. The name you arbitrarily choose to give each workstation can have a length of up to 15 printable characters. NetBIOS returns a name number to each participant in the NetBIOS dialogue.

The name number is a reference point for both sides as the receiver issues NB_RECEIVE_DATAGRAM_WAIT commands and the sender issues NB_SEND_DATAGRAM_WAIT commands. Both sides can send and receive messages; you decide how the dialogue between the participants flows. At the end of the dialogue, both sides delete their names from the NetBIOS name table.

The IPX programming interface parallels that of NetBIOS for sending and receiving datagrams. Both sides open a socket at the beginning of the conversation between the workstations. At the end, both sides close their respective sockets. Through an open socket, one side or the other can send or receive message packets with their respective program statements.

Message Passing

The IBM and Novell technical references provide more detail on the NetBIOS and IPX programming interfaces. That detail, however, is easy to understand if you have a basic understanding of the functions you use to send and receive message packets. One of the few difficulties you might run into involves pointers (i.e., addresses) that you pass to the NetBIOS and IPX DLLs. NetBIOS.OS2 and IPXCALLS.DLL are 16-bit DLLs that expect 16-bit pointers. The following prototype shows one way to tell the IBM C/C++ tools compiler to emit the proper 16-bit code for the NetBiosSubmit() function:

extern unsigned short NetBiosSubmit(short, short, void *);

#pragma linkage (NetBiosSubmit, far16 pascal)

To take advantage of the parallelism between NetBIOS and IPX datagrams, I built two DLLs. I used the same name (NBIPX.DLL) for each DLL file and the same function names within each DLL (OpenLAN(), CloseLAN(), SendMsg(), and ReceiveMsg()). In one DLL, I coded to the NetBIOS interface. In the other one, I coded to the IPX interface.

The main program insulated itself from NetBIOS and IPX by invoking the functions in the NBIPX DLL. This meant that, on a given LAN, I didn't have to distribute a different executable file for NetBIOS and IPX. I could simply install either the NetBIOS or IPX version of NBIPX, depending on which protocol that particular LAN uses. The main program is the same for both protocols. For my specific application, I achieved the same level of generality that named pipes would have offered, without sacrificing the performance and memory usage that several layers of Novell or IBM system software would have cost me.

Hidden Awareness

I managed to hide the differences between the NetBIOS and IPX APIs from my program, but I had to be constantly aware of the limitations that using datagrams imposes. The transport protocol does not guarantee the delivery of datagrams (datagrams are connectionless), which meant that each mes sage packet had to contain a sequence number. The receiver verifies each packet to ensure that no packets in a logical group of packets are dropped.

I also designed the dialogue to allow the client workstation to expect an acknowledgment for each work request packet sent to the database server. The workstation reissues a request if it doesn't get a response within a short time. I used staggered retry intervals of 1/2 second, 1 second, 5 seconds, and 20 seconds.

Finally, I designed the format of each packet to not exceed the size limitation of datagrams. NetBIOS datagrams can be up to 512 bytes, while IPX packets can be up to 546 bytes. Stepping up from datagrams to a connection-oriented protocol, unfortunately, wasn't a solution to the small-packet problem.

NetBIOS session services, which are connection-oriented and offer guaranteed delivery, can send and receive 64 KB at a time and aren't difficult to use. But Novell's session services, provided by the SPX protocol, can send and receive only 534 bytes at a time. (IPX and SPX can sometimes use larger packets, up to 4202 bytes, depending on the brand of network adapter and software driver in a PC. But Novell's software development kits for both DOS and OS/2 recommend sticking to the lower size limit.)

Nothing to Fear

Using either NetBIOS or IPX in an OS/2 environment is easier than you might think. Both protocols are especially good at letting workstations send work requests to software running on unattended PCs on the LAN. Sharing files on a file server, through the file-redirection functions inherent in the network operating system, is sometimes the wrong way to design a LAN-aware application, particularly if the application uses the file server to store queues of work requests.

Named pipes are easy to use, of course, but the extra layers of system software may slow down your application. Going to the "bare metal" of NetBIOS or IPX will give you better performance and a new perspective on how LANs work. With a little extra e ffort, you can even insulate your program from the differences between NetBIOS and IPX.

---

Barry Nance, a BYTE contributing editor and a programmer for the past 20 years, is the author of Using OS/2 2.1 (Que, 1993), Introduction to Networking (Que, 1992), and Network Programming in C (Que, 1990). He is the exchange editor for the IBM Exchange on BIX. He can be reached on the Internet or BIX at barryn@bix.com .