Michael has been programming in the networking field for the last six years. He is currently working at IMARA Research in Toronto, doing device interfaces for desktop document/image-management software. He can be reached at MaS Network Software and Consulting, 65-2380 Bromsgrove Road, Mississauga, ON L5J 4E6, Canada or at mshiels@masnet.uucp or mshiels@tmsoftware.ca.
When programmers talk about MS-DOS, they are generally referring not to the C:\> prompt, but to the INT 21h programming interface. When you see a piece of code with an INT 21h call, you know the program is making a DOS call. For programmers, DOS is INT 21h and INT 21h is DOS.
But things aren't quite so simple. DOS has a function (INT 21h AH=25h) to install a handler for an interrupt, and one of the interrupts you can install a handler for is...INT 21h! Any DOS program can legitimately take over INT 21h and masquerade as DOS. If the program becomes sufficiently popular, the word "masquerade" is no longer accurate: The program makes its way into the de facto DOS specification. For example, Novell's Netware hooks INT 21h and inserts its own functions ahead of many of those supplied by Microsoft. If you're writing software for the DOS environment, it's important to be at least vaguely aware that any DOS calls your program makes will end up getting serviced, not by code written in Redmond, but by code written in Utah.
Sometimes INT 21h is patched or extended by a third-party vendor that happens to be another group within Microsoft. As Mike Shiels shows in this month's "Undocumented Corner," Microsoft LAN Manager extends INT 21h to provide functions such as DosCallNmPipe (INT 21h AX=5F37h) and NetRemoteCopy (INT 21h AX=5F4Ah). For example, if you were to disassemble NETAPI.DLL from Windows, you would see that many of the functions it provides are nothing more than wrappers around these strange INT 21h calls.
If you've seen the LAN Manager documentation, you should be surprised to see DosCallNmPipe and so on identified with INT 21h functions and subfunctions. The LAN Manager documentation just provides C-function prototypes. More and more, documentation tells you about high-level C or C++ calls, without telling you anything about the underlying low-level interface for which they are often just a thin wrapper. While high-level interfaces are very nice, this type of "leave-the-driving-to-us" documentation unfortunately forces the programmer to use whatever library the vendor supplies. Often these libraries are not suitable for inclusion in device drivers, TSRs, or other programs with special requirements.
Mike's article corrects this problem for LAN Manager on DOS and Windows, showing the actual low-level interface that Microsoft uses. Most of this interface involves INT 21h AH=5Fh and INT 2Fh AH=11h. This is consistent with the DOS interface: Several documented network-related functions use INT 21h AH=5Fh (for example, INT 21h AX=5F03h is the Make Network Connection function), and INT 2Fh AH=11h is a large collection of subfunctions known as the "network redirector" (see Undocumented DOS, Chapter 4). Any INT 21h AH=5Fh functions that DOS itself doesn't handle get passed through to INT 2Fh AX=111Eh, with AX on the stack.
Even though these functions use INT 21h and INT 2Fh and are undocumented, they do not appear in the book Undocumented DOS, written by myself with Ray Michels, Jim Kyle, Tim Paterson, David Maxey, and Ralf Brown. A question we constantly faced while writing this book was: What is part of DOS? It was tempting to consider DOS as anything that comes out of Redmond wearing an INT 21h or INT 2Fh interface. But this ignores the crucial role in the industry-standard de facto DOS "spec" of third-party vendors such as Novell, Qualitas, and Quarterdeck.
In the world of networks, Novell Netware is much more part of this de facto DOS spec than any networking software that Microsoft produces. LAN manager is so far behind Netware that rumor has it that the world's largest LAN Manager site (running OS/2, of course) is in Redmond! On the other hand, one of the lessons from the success of Windows 3.x is that Microsoft is very persistent. The API implemented by LAN Manager will survive and grow in importance, even if LAN Manager itself doesn't. Microsoft will probably just keep at it until its API becomes the standard in PC networking. A book I recently edited, Windows Network Programming: How to Survive in a World of Windows, DOS, and Networks (Addison-Wesley, 1993), by Ralph Davis, clarifies how all this LAN Manager stuff is being carried over into the next generation of Microsoft network software in Windows for Workgroups (WFW) and in Win32. Interestingly, according to Davis, much of WFW's support for LAN Manager is currently undocumented.
While this month's column is devoted to yet another interface that Microsoft has left undocumented, it should be noted that Microsoft's competitors are no better. If anything, Novell's documentation appears to be even more incomplete than Microsoft's: I have been hearing a lot recently from programmers who need to know about the structure of the file system on Novell servers, undocumented NLM calls, the Netware Core Protocol (NCP), undocumented interfaces to IPX used by Novell's NETX, and so on. Novell also appears to have never documented what INT 21h looks like when running under Netware.
That all sounds like good material for a future "Undocumented Corner." Now, does anyone want to write it? Please send me (CIS ID 76320,302 or andrew@ pharlap.com) your questions, comments, and ideas for future columns.
--Andrew Schulman
Ever wanted to interface to a network-independent, named-pipe interface? Ever wondered about the underlying interface for the Microsoft LAN Manager application programming interface (API)? In this "Undocumented Corner," we'll discuss the underlying interface currently used by Microsoft to implement the resident LAN Manager API, named pipes, and mailslot interfaces.
LAN Manager was introduced as Microsoft's entry into the growing local area network arena. It boasts all sorts of features, including a very extensive API to interact with the client/server network components. Along with the LAN Manager proprietary API, Microsoft introduced a network-independent API called Named Pipes for connection-oriented network programming, and a partner interface called Mailslots for doing connectionless (datagram) programming.
Microsoft's API is portable between all the existing LAN Manager platforms: DOS, Windows, and OS/2 1.x. The DOS API interface is implemented as a library that gets linked into your program, while the Windows and OS/2 1.x versions naturally use dynamic link libraries (DLLs) to implement shared API code.
Microsoft's latest entry into the LAN arena, Windows for Workgroups (WFW), supports the same LAN Manager API as LAN Manager for Windows. As a late breaking note, it appears that the interface described here may also be available as part of the LAN Manager 2.1a (or 2.2) support for IBM OS/2 2.x Virtual DOS Boxes. Windows NT will also have this API available as part of LAN Manager for NT. Portions of this API are supported in the IBM LAN Server product. With the proliferation of products incorporating these APIs, they will definitely be with us for quite a while!
The API works quite well if you are using Windows and/or OS/2. Since they use DLLs, the size of your code does not increase when you include the LAN Manager API. Once you compile some small utilities for DOS, however, you will discover a problem: Using Microsoft's DOSNET.LIB file from the LAN Manager Programmers Toolkit increases your program's size quite a bit when you are just calling a simple API function to get some basic workstation information. For example, a small C program with no LAN Manager API calls is typically just over 3K, but once a call to NetWkstaGetInfo is placed into the code, the program grows to over 20K. The library will add even more code to your program if you call more of the API functions.
These API function names are structured as Net?category?verb or Dos?verb? category; for example, NetUserAdd, NetGroupEnum, DosConnectNmPip, and DosDisconnectNmPipe. Most of the Net* functions are also structured such that the first parameter to the function is either a NULL pointer to signify execution of the API call on the local machine (for instance, NetUserAdd(NULL, ...)), or a server name in the uniform naming convention (UNC) form \\servername (for example, NetUserAdd("\\BIGSERVER", ... )), to signify remote execution of the API call on another machine (usually a server).
Here, we'll explore the undocumented interrupt 21h and interrupt 2Fh function calls that implement some of the LAN Manager API when it is called in local mode with a NULL pointer for the server name. This code is much smaller than the Microsoft code and won't impact the size of your program significantly. Table 1 (page 139) lists the functions in the LAN Manager API, and Table 2 (page 139) lists the functions from Table 1 that provide an INT 21h or INT 2Fh interface that can easily be called directly via the interrupt.
The LAN Manager for Windows NETAPI.DLL and PMSPL.DLL files are to a certain extent just wrappers around the undocumented, interrupt-based API. The components of the LAN Manager API that have no associated undocumented functions are implemented in the DLLs themselves. Inside the DLL, the undocumented functions are accessed as straight INT 21h calls when running under the now-defunct Real-mode Windows; under Standard and Enhanced 386 mode, the DOS Protected Mode Interface (DPMI) Simulate Real Mode Interrupt function (INT 31hAX=0300h) is used to make the LAN Manager INT 21h calls.
Microsoft chose to extend the INT 21h function 5Fh network interface to support the extended local API. Most of the functions use various register combinations to pass in parameters, but a few functions actually just pass in the address of the parameters on the stack, usually because there are too many parameters to safely (and sanely!) use registers. Other functions create a temporary buffer to store all the parameters and insert the address of this buffer into the registers before making the INT 21h call.
The undocumented LAN Manager API consists of two major groupings. The first is the "true" LAN Manager-specific API, which is implemented by LAN Manager (and probably most LAN Manager-based networks), and will probably be implemented in any future Microsoft networking software. The second group is the Named Pipe interface implemented by Microsoft LAN Manager, IBM Lan Server, Novell Netware, and Banyan Vines, as well as other LAN Manager-based networks such as DEC Pathworks. The Named Pipes interface is becoming an industry-standard interface (similar to Berkeley Software Distribution -- BSD -- sockets) for network-independent programming, being implemented not only by Microsoft but also by Novell and Banyan.
Of course, in dealing with an "undocumented" interface it is sensible to have some reservations. However, this API has not changed in any of the current releases of LAN Manager (2.0, 2.1, 2.1a, and 2.2). As noted earlier, it is also supported in WFW, so this interface is very unlikely to be drastically changed by Microsoft. But as with any undocumented interface, it could change at some point in the future, so be forewarned.
Source code and header files for Microsoft C 6.0 that implement this interface are available from MaS Network Software and Consulting and from DDJ (see "Availability," page 5).
The most interesting section of this undocumented API, and probably the most useful, is the Named Pipe API, which originated in Microsoft LAN Manager and has now been added to Novell Netware and Banyan Vines. This API implements a connection-oriented protocol, and is used in particular by the Microsoft SQL server to do all communications between the clients and the server. Named Pipe programming is much too complicated to go into in this article, but the Microsoft LAN Manager book in "References" covers Named Pipe programming very well. Just substitute the interrupt-based calls shown here for the C wrappers shown in the official Microsoft documentation. What we've done here, basically, is get rid of the C wrapper.
Programming for Named Pipes is comparable to programming for the Berkeley UNIX socket interface. The APIs are fairly straightforward and easy to use. In contrast, NetBIOS, probably the biggest standard for PC networking, requires structures to be filled in for each function to be executed (Call, Listen, Send, Receive, and so on), which makes it more complicated.
In addition to Microsoft SQL Server (see next section), a very useful program that uses Named Pipes is the OS2YOU program by M Wahlgren Software Development in Sweden (OS2YOU*.ZIP on most BBSs). This program uses Named Pipes to talk between a DOS workstation and an OS/2 workstation, to allow the DOS workstation to run interactive, full-screen OS/2 programs on the OS/2 workstation. With this program, you can run full-screen LAN Manager NET ADMIN while running DOS, which is otherwise not currently possible with LAN Manager.
LAN Manager's Named Pipe protocol is implemented as part of the workstation service for the LAN Manager workstation. It uses the Server Message Block (SMB) protocol defined by Microsoft and documented in the X/Open manual on SMB (see "References"). This protocol is also supported in various UNIX LAN Manager ports, DEC Pathworks, and other LAN Manager-based products.
SMBs were originally documented in some joint Intel/Microsoft documents in early 1987. These documents define the packet headers for file-sharing and print-sharing communications. Since then Microsoft has enhanced the protocol for LAN Manager 1.x and 2.x extensions (see the 3COM section on CompuServe). These extensions include Named Pipes, Mailslots, and the Remote Procedure Call (RPC) API (see below).
Access to Named Pipes from Windows is provided by NETAPI.DLL. Under LAN Manager for Windows, this DLL also implements the rest of the proprietary LAN Manager API. WFW has essentially the same DLL as would a LAN Manager Windows client. Novell and Banyan each implement their own NETAPI.DLL since they do not want the rest of the proprietary LAN Manager API. It is unfortunate that these different files all have the same name.
The biggest user of the Named Pipe protocol is Microsoft's SQL Server. Novell and Banyan probably implemented Named Pipe modules for their own networks just in order to run SQL Server. Microsoft SQL Server is based upon the Sybase SQL engine and uses the Sybase DBLIBRARY interface at the client end. This interface allows a client program for Sybase products to talk to any of the databases they offer using different lower-level interfaces to implement the DBLIBARY interface.
A Microsoft SQL Server or Sybase SQL Server Client program will interface to either a DBNMPIPE.EXE TSR for normal DOS programs or the DBNMP3.DLL for Windows programs. The DBNMPIPE.EXE TSR calls the undocumented INT 21h Named Pipe functions directly to interface between the INT 62h Sybase interface for DOS and the underlying network interface for Named Pipes. DBNMP3.DLL calls the NETAPI.DLL functions directly to interface between the W3DBLIB.DLL Sybase interface and the underlying network interface for Named Pipes. The NETAPI.DLL will then turn around and call the INT 21h Named Pipe functions.
Netware's Named Pipes protocol is implemented using Novell's Sequenced Packet Exchange (SPX) and Internetwork Packet Exchange (IPX) protocols and is loaded as an optional TSR called DOSNP.EXE. DOSNP hooks into the INT 21h chain and watches for any file-related INT 21h calls, to catch the open/read/write/close of the pipe. It does not support the DosReadAsynchNmPipe or DosWriteAsynchNmPipe calls that are part of an INT 2Fh interface. As far as I can tell, Novell has implemented all the basic calls that would be used by the DBNMPIPE.EXE program necessary to get Microsoft SQL Server running. INT 2Fh functions are a high-performance improvement, since they do not block the machine while waiting to complete, but they are not universally implemented. Novell also does not support the NetHandleGetInfo or NetHandleSetInfo functions.
The Novell Netware Windows NETAPI.DLL just calls the DOSNP.EXE TSR to do each function call. Similar to LAN Manager's NETAPI.DLL, it uses DPMI to execute real-mode INT 21h from protected mode. Care must be taken in environments where LAN Manager and Novell coexist, since each one provides a NETAPI.DLL, and Windows will only allow one to be loaded. There seems to be no way to allow the coexistence of Named Pipes under two different networks.
Novell Netware implements most of the standard Named Pipe calls as well as NetServerEnum, which is part of the LAN Manager 1.x API. This function is used to show a list of available servers. NetServerEnum is actually a LAN Manager 1.x function call obsoleted by NetServerEnum2 in LAN Manager 2.x, but Novell needed to implement this function to allow Microsoft SQL Server programs to find a list of database servers.
The third biggest section of this undocumented API is for Mailslots, which provide connectionless (datagram) communications. NetBIOS connectionless datagrams are used to implement the Mailslot protocol. This API has functions for making a Mailslot and for reading from, writing to, and deleting a Mailslot. Mailslots are used internally in the MESSENGER service to send and receive messages.
Servers also announce their presence on the network periodically using Mailslots, but the WORKSTATION service already has this Mailslot open so it is not possible to access it at this level. The LocalServerEnum and LocalServerEnum2 functions return information gathered from these periodic server Mailslot broadcasts.
This API is implemented in Microsoft LAN Manager and LAN Manager-based networks, but no one else, such as Novell or Banyan, bothered to implement this interface when they implemented the Named Pipe interface. WFW does implement this interface, so it will still be a factor in the network programming world.
Mailslots have the same advantage over direct NetBIOS programming as the Named Pipes interface: simplicity! The interface is based entirely on function calls with no complicated structures to fill in for each operation.
Finally, we come to the various functions available in the LAN Manager native API, which I describe below using new Local* names I have assigned to each Net or Dos function.
For example, LocalMessageBufferSend (INT 21h AX=5F40h) is the local version of the LAN Manager NetMessageBufferSend function. One nice feature of LAN Manager is its built-in messaging facility. With the undocumented API entry, you can now send a message directly to a single user, to a group of people in a certain domain name, or to everyone as a broadcast. This is a useful addition to programs that need to notify someone of a conflict or error. No need to spawn the very large "NET.EXE MESSAGE" command just to send simple messages around.
LocalServiceEnum (INT 21h AX=5F41h) can tell which network services are running and what state they are currently in. It can be used to tell users if they will be able to receive incoming messages at their machines, since the MESSENGER service is necessary to receive any messages. LocalServiceControl (INT 21h AX=5F42h) can be used to temporarily pause the disk or printer redirector so that local resources can be accessed. This is similar to the documented DOS Get and Set Redirection Mode (INT 21h AX=5F00h and AX=5F01h) functions, in that it allows you to pause and unpause network redirections of drives and printers.
Once you have a remote printer connected to an LPT? port you may forget where your print job will eventually be printed. With LocalPrintJobGetId (INT 21h AX=5F43h), you can get the server name, queue name, and job ID number to report to the user any time after you open the LPT? port and before you close the job to start it printing. These strings can be displayed to remind the user where they need to go to pick up their output.
With the amount of information people are trying to move around on a LAN, bulk file moving and/or copying can end up being quite slow, since the data ends up moving across the network at least twice, even when the actual source and destination are both on the same server. Now with the LocalRemoteMove (INT 21h AX=5F4Bh) and LocalRemoteCopy (INT 21h AX=5F4Ah) functions (note the strange naming!), files can be quickly moved and copied without the data ever having to leave the server. This will greatly reduce the strain on the network when large files have to be moved between locations on a server.
If applications need to do any audit logging with information such as the user's workstation name and/or the logged-in user name, it is now quite easy with LocalWkstaGetInfo (INT 21h AX=5F44h). This function can return three different sets of information, depending on how much detail the programmer is interested in. LocalWkstaSetInfo (INT 21h AX=5F45h) can be used to change various system parameters for the current network session.
With LocalServerEnum (INT 21h AX=5F4Ch) and LocalServerEnum2 (INT 21h AX=5F53h), it is now possible to display lists of available servers for users to choose from when connecting resources or choosing servers to talk to via Named Pipes. The enumeration will also provide information about the types of servers available. This information is handy if you want to list the available SQL Servers or Print servers.
All these functions add new possibilities for programs when they know they are executing on a LAN Manager network. Default user names can be based on the network computer name, messages can be sent, and servers can be listed for the user's convenience.
I've been unable to find out any details on the implementation of Named Pipes in Banyan Vines or DEC Pathworks. I know that Microsoft SQL Server can run on these platforms, so it must support the undocumented Named Pipe interface. I just don't know which network protocol it us s to implement the Named Pipe protocol.
This interface is not documented completely, since the implementation of some functions is unknown to me at this time. DosRawReadNmPipe and DosRawWriteNmPipe are not documented in any books or literature that I can find, so the undocumented functions are described but the details of the function parameters are unknown.
For a more detailed explanation of the LAN Manager API, Named Pipes, and Mailslots, I recommend the two Microsoft Press books noted in the references. Table 1 has a list of the LAN Manager API functions and some notes on specific version support and the limitations associated with each function when used under MS-DOS. As you can see from the table, a lot of the functions are only applicable when executed on another machine, usually a server.
Brown, Ralf and Jim Kyle. PC Interrupts. Reading, MA: Addison-Wesley, 1991.
Davis, Ralph. Windows Network Programming. Reading, MA: Addison-Wesley, 1993.
Developers' Specification: Protocols for X/Open PC Interworking: SMB. U.K.: X/Open Company Ltd., 1991.
Dunsmuir, Martin. "OS/2 to UNIX LAN," in Stephen Kochan and Patrick Wood, eds. UNIX Networking. Indianapolis, IN: Hayden, 1989.
Microsoft LAN Manager Programmer's Reference (from LAN Manager 1.0), 1988.
Microsoft LAN Manager Programmer's Reference. Redmond, WA: Microsoft Press, 1990.
Microsoft Networks/OpenNET, File. Sharing Protocol, Intel Part No. 138446.
Ryan, Ralph. Microsoft LAN Manager, A Programmer's Guide. Redmond, WA: Microsoft Press, 1990.
Copyright © 1993, Dr. Dobb's Journal