Back

The LanMan Library for Clipper

The LanMan Library for Clipper is a set of functions for working with Microsoft Network system calls. It is an original work by Klas Engwall and placed in the public domain. Source code is included, so you can change anything you want to make it better suit your needs. The LIB files included in the distribution are compiled with Clipper 5.2e, so you may need to recompile the source code if your environment is different.

Download rev. 1.05 of the LanMan Library here

Götz Strehl again contributed a Clipper 5.3 compiled version of the LIB file
which can be downloaded here

Background


Starting with DOS 3.1 a few basic networking functions were included in DOS itself. The most important of those are "Redirect device" for redirecting a network device to a local printer port name or drive letter, "Cancel redirection" for cancelling such a redirection and "Get redirection list entry" which can be called repeatedly to get the whole list of redirected devices. Clipper wrappers for these functions and a few others are included in the library.

Later on, in the OS/2 era, additional DOS networking functions were added under the common name "LAN Manager Enhanced DOS". These are not included in the LanMan Library although the library name suggests that they are. If time permits and all goes well, some of them may however be added in the future. Please note the important word "may" :-)

Starting from revision 1.05, the library also has a function for retrieving MAC addresses using the NetBIOS Interface.

How is it done and how does it work?


The LanMan Library uses some of the 5Exx and 5Fxx DOS 3.1 networking services under INT 21h and also one function under the NetBIOS Interface interrupt 5Ch. For each function in the LanMan Library, the underlying DOS service number is mentioned in the docs for the function in question. Ralf Brown's Interrupt List has all the details, if you are interested in looking them up. In order to call those services the library relies entirely on the FT_Int86() function from the Nanforum Toolkit (written by Ted Means).

Functions included in the LanMan Library


DOS 3.1 Networking functions:
LM_Ferror() Get the DOS error code for a networking operation
LM_GetCompName()   Get the local computer name
LM_GetRedir()   Get the redirection list
LM_KillRedir()   Cancel a redirection
LM_LibVers()   Get the version of the LANMAN.LIB library file
LM_Redirect()   Redirect a network device
LM_SetPrString()   Set a network printer setup string
 
NetBIOS Interface:
LM_NbMacAddr() * Get the MAC address(es) of the network adapter(s)
 
Demo application:
LMdemo()   A complete demo application
 
The following functions are included in the Low Level Library, which is included in the LanMan Library starting with Rev 1.05. The revision number of the Low Level Library is also 1.05.
 
Low level functions:
LL_FreeMem() * Free a memory block allocated by LL_Str2Mem()
LL_I2Attr()   Convert numerical file attributes to character
LL_IsBitOn()   Check if a certain bit in an integer is on or off
LL_LibVers() * Get the version number of the Low Level Library
LL_Mem2Str()   Copy a string from memory to a char variable
LL_Offset() * Get the offset of a protected mode memory selector
LL_Segment() * Get the segment of a protected mode memory selector
LL_Str2Mem() * Copy a string to a static memory location

New functions since the previous version of each library are marked with an asterisk.

More info about the latest changes can be found on the Changes page.

What is needed in order to use the LanMan Library?


First of all you obviously need the library itself :-). And your normal Clipper development tools, of course. If you do not use Clipper 5.2 you will have to recompile the source code with your Clipper version. In that case you also need a library manager such as Microsoft's LIB.EXE unless you decide that you can live with linking the OBJ files separately into your applications. Or download Götz Strehl's Clipper 5.3 compiled version of the LIB file

If you want to reassemble the assembly functions you also need MASM, the Microsoft Macro Assembler. I use version 5.1, but older versions should also work. I have tried version 6.1, but it is quite different from the earlier versions and may need changes in the source code. OBJ files for the assembly functions are included separately in case you do not have MASM but still want to rebuild the library from scratch.

Starting with Rev 1.05 of the LanMan Library, several functions from the Low Level Library are called by LanMan Library functions. You must supply both library names (LANMAN.LIB and LL.LIB) in your link script! Rev 1.05 of the LanMan Library requires Rev 1.05 or higher of the Low Level Library.

If you are also a user of the LFN Library and have downloaded that library before March 17 2003 you should replace your old rev 1.00 LL.LIB file with the new 1.05 version of that file, which is included here.

You also need the Nanforum Toolkit and its companion CPMI library. If you do not have them already, you can download them from the Oasis. CPMI.LIB is included in the Nanfor ZIP file.

So in order to use the LanMan Library, these are the four libraries that you must add to your link script: LANMAN, LL, NANFOR and CPMI

If you need a Win32 Norton Guide viewer I can recommend Dave Pearson's WEG which you can download from his web site.

For recompiling the library source code, including the demo application, you also need the FTINT86.CH header file which comes with the Nanforum Toolkit and the LMLIB.CH header file which is included in the LanMan Library distribution.

It is recommended that you use #defines from LMLIB.CH in your own applications when making calls to LanMan Library functions.

Printer connection strategies


In the old single tasking days it was a simple matter to decide how and when to redirect a printer and what to do with those redirections at the termination of the application. The first version of this library, which I wrote back in the 1980s using assembly language and a programming reference manual from D-Link, picked up a list of all redirected printers at program startup. During the life of the instance of the application, a number of printers were connected and disconnected as the need arose, and the original redirections were then restored immediately before program termination. So a "NET USE" command after program termination would show exactly the same redirection list as before program start.

However, when the users started running my applications under Windows, things got a little more complicated. The problem was of course that it became impossible to determine what the "original" redirection list really was. If several instances of my application (or several different applications) were started and terminated in random order on the same computer they would not be able to agree between themselves which redirection list had been current before the first of them started.

This problem will probably never be "properly" solved, but I have found that the following strategy causes the least grief:

1) Don't bother with trying to restore the original environment. You may end up restoring the wrong redirections anyway. Just leave the printer connections as they are when you quit.

2) Don't change redirections immediately before program termination. It may cause Win9x (and Win9x only, AFAIK) to hang the DOS box.

3) Before deciding to redirect printers at all inside your application, you have to determine if it is a wise thing to do considering how printers are set up in general on your users' computers. Are other applications using printers by LPT names, and if so, is the whole range of LPT ports involved? If there is a significant risk of LPT clashes, could you limit your printer use to only one port, for example LPT3 in order not to disturb other applications running on the computer? (Technically the answer is yes. You can connect any number of printers to the same local printer port name, one at a time, provided that you disconnect them again when you need to connect the next printer).

4) Give the user a possibility to change the printer port assignments (the LPT port name) to avoid clashes with other applications.

5) Set up the printer redirection for each print job at the last moment. If you do it at program startup, another application or another instance of the same application may pull the rug away from under your feet before you are ready to actually print.

6) Consider the risk that a user starts printing from two different applications or application instances at the same time and that those two print jobs will disconnect each other's printers. In my experience, that risk is of limited size, especially if you set up your printer redirections immediately before printing is started.

Considering the size of the list of recommendations above, it may sound like you would be better off avoiding this matter entirely and instead set up the printer redirections separately before your application is started. But I have users who run up to four or five instances of the same application and regularly use four or five different printers in each instance. Since I removed the old restore-on-termination code from the days of single tasking operating systems I have had no reports of printing failures that could be suspected to have anything to do with the redirection strategy. So I believe that, if handled with a little care, the redirection functions can be a useful addition to the average networked Clipper application.

Suggestions, bug reports etc


If you have any problems with the current version or any suggestions for making the library better, do not hesitate to tell me about them, either on comp.lang.clipper or via email at the address below.

However, do not expect me to fix things overnight. This is free software, and you have the source code in the distribution. So if you are in a hurry to get something fixed, feel free to do it yourself for your own needs. But please let me know what you did so I can fix it in the next release for everyone's benefit.

Disclaimer


Although I have checked everything thoroughly on my systems, I cannot guarantee that the library functions will work correctly under all circumstances. I will not take any responsibility for damage or loss of data incured whilst using the software. You use it entirely at your own risk. By using the software you agree to these terms.

Enjoy,
Klas

 

Links:


LMLIB.ZIP Download the LanMan Library
LANMAN53.LIB Götz Strehl's Clipper 5.3 compiled library file (You still need the other parts of LMLIB.ZIP)
NFLIB305.ZIP Download the Nanforum Toolkit (from the Oasis)
WEG Download Dave Pearson's Norton Guide reader for Win32 (from Dave's website)
In case you want to talk to me about the LanMan Library
(no general Clipper support questions please)
Back Go back to the Engwall InfoTech Clipper Pages main page

This document was last revised on 2007-10-01