NetWare Development on PowerPC

JAMIE OSBORNE

Apple and Novell recently announced a PowerPC version of NetWare. Under NetWare, network services such as file servers, print spoolers, and electronic mail dispatchers are written as NetWare loadable modules, or NLMs. By providing a software layer between the NLMs and the hardware they run on, NetWare makes more efficient use of the available hardware, improves portability, and allows programs to run on mixed networks tying together different platforms. This article shows you how to get started with NLM development.

Novell's NetWare has been around for years, and is considered by many to be the networking standard in the DOS/Windows world. NetWare servers have always been able to handle AppleTalk clients, too, but they have not been as prevalent in predominantly Macintosh environments. As a result, most Macintosh developers have never had the need or inclination to learn how to write software for NetWare servers. With Apple's NetWare for PowerPC^TM, you can now port your existing network products, or create new ones, to run on Apple Workgroup Servers under NetWare.

In this article, we'll take a brief tour of the NetWare environment and what it takes to write software for it. The article is intended primarily for developers of networking software, particularly running on networks using Apple Workgroup Servers or multiple platforms -- but you should also find it of interest if you're just curious about NetWare or want to know about the available options for writing networking software.

NetWare is anetwork operating system, a framework for providing network services. Instead of running application programs, NetWare runsNetWare loadable modules, or NLMs, which typically implement network-based services such as file storage, printing, and electronic mail. An NLM can be loaded either on demand or automatically, and uses the NetWare Operating System (NOS) to allocate memory, communicate with clients, and interact with the underlying hardware. Once loaded, an NLM becomes an integral part of the operating system, with no architectural "middlemen" to slow it down. Figure 1 shows an overview of the NetWare architecture.

The information in this article is based on Apple's NetWare for PowerPC, an implementation of Novell's NetWare 4.1. Earlier versions of NetWare are still in wide use, but NetWare 4.0 added some new features such as directory services and improved security. NetWare 4.1 is a more robust version of 4.0 and improves still further on these new features. Though earlier versions of NetWare client software can connect to NetWare 4.1 networks, they may not be able to use all the features of the available NLMs. If you want your NLMs to support all versions of NetWare clients, the NOS provides the necessary support libraries.*

Figure 1. The NetWare architecture

WHY NETWARE?

If you're a Macintosh developer, why should you make the leap to NetWare development? To make your product available to the greatest number of users. NetWare is used on more than 60% of all servers in the DOS-compatible world. Here are some of the reasons NetWare is so popular.

EFFICIENT RESOURCE ALLOCATION
In a typical Macintosh network installation, a single server machine provides file storage, printing service, a mail server, and maybe even a scheduling server or other network services. Any one of these services might deliver acceptable performance on its own; but when you try to put them all on the same "box," they must contend for limited resources such as processor time, memory, and disk access. The result is that they all suffer performance degradation: even on a blindingly fast machine, such resource contention can slow all of your network services to a crawl.

NetWare helps alleviate this problem in three ways:

• OS-level resource access. Unlike other operating systems (such as UNIX®), NetWare has no protection scheme to prevent a process from accessing memory outside its domain. Once loaded, NLMs become part of the operating system itself, with unrestricted access to memory and other hardware resources. NLMs run faster without the overhead associated with memory protection. The cost, of course, is that an unprotected NLM can bring the entire system down if it crashes.
• "Lightweight" threads. The NOS is multithreaded, with threads from NLMs existing alongside those belonging to the system itself. Because they operate at the system level, NLM threads carry very little overhead and can be spawned, executed, and switched very quickly.
• Nonpreemptive multitasking. NetWare is a nonpreemptive multitasking system: the burden of deciding when to switch threads is placed on the individual NLMs, rather than on the operating system itself. So long as all NLMs are "good citizens," they can work cooperatively to produce a more efficient system.

CENTRALIZED DIRECTORY SERVICES
One of the biggest headaches for many network administrators is maintaining user and group lists for multiple servers and services. A single user may have an account on two or three file servers, a mail server, and who-knows-what else. Keeping the different accounts for that one person up to date can be a significant chore.

NetWare helps ease this burden by making centralized directory services available to all NLMs. NetWare users log directly into the network itself, not into a particular server. Using interfaces that NetWare provides, NLMs can access the directory services and use them for authentication. Thus a mail server and a file server, for example, can share the same user list instead of each maintaining its own. This centralized approach to directory services benefits everyone. NLM developers don't have to write the code to store, edit, and maintain their own user lists; network administrators only need to maintain a single centralized directory; and users don't have to remember half a dozen different passwords and authenticate themselves every time they move from one network service to another.

PORTABILITY
Networks are growing larger everywhere, as users discover that computers linked together, sharing services over a network, are far more useful than isolated workstations. While this growth presents many opportunities for developers of network services, it also presents the problem of diversity. The days are gone when a company's computers all ran the same operating system. Today, Macintosh computers, DOS-based PCs, and UNIX workstations must all coexist on the same network.

Porting a network service such as a mail server from one hardware platform to another can take a great deal of time and effort. Building your server as an NLM, however, gives it instant portability to any platform for which NetWare is implemented. NetWare's uniform API "virtualizes the hardware," so that NLMs don't have to interact directly with the platform they're running on. Since the interface to NetWare is the same from one platform to another, porting your NLM is a simple matter of recompiling.

THE RIGHT TOOLS FOR THE JOB

By now you should be convinced that NetWare has a lot of advantages to offer. The rest of this article details what it takes to build an NLM that will run on NetWare for PowerPC. Included on this issue's CD is sample code for a simple multithreaded NLM.

CHOOSING A DEVELOPMENT ENVIRONMENT

If you're already developing software for Power Macintosh computers, you probably have most of the tools you need to develop software for NetWare for PowerPC. In the next section, we'll see how to use these tools to do NetWare development in a Macintosh environment; but there are non- Macintosh options as well:

• If you have an IBM RS/6000 computer, you can use thecset compiler to develop your NetWare NLMs. (You'll need version 2.1.1 or later of the compiler, which can generate PowerPC code.) This is the method Apple used to port many of the NLMs that are part of NetWare itself.
• If you have a DOS-compatible machine, you may be able to use Novell's UnixWare in conjunction with the Cygnus C/C++ Compiler for PowerPC (a PowerPC version ofgcc). You should have at least an 80386 processor for this option, but an 80486 or Pentium is recommended.

If you already have the hardware and software, either of these non-Macintosh options can help you quickly begin producing high-quality code. But if you aren't already using an RS/6000 or a DOS- compatible system, you'll probably do better to go the Macintosh route. Purchasing an RS/6000 can be quite expensive, not to mention the additional cost of setup and maintenance. You can get DOS- compatible machines for much less, but not all of them are compatible with UnixWare. (Any certified UnixWare reseller should be able to help you determine whether UnixWare will run on your hardware.)

This article will focus exclusively on Macintosh development options. However, general information about NetWare's interfaces applies to any development platform you choose.

NETWARE DEVELOPMENT THE MACINTOSH WAY
MPW Pro (available from APDA) includes a PowerPC C/C++ compiler and linker that run as tools under Macintosh Programmer's Workshop (MPW). The compiler, PPCC, produces PowerPC object (.o) files, which you then pass to the PPCLink tool to produce an XCOFF (eXtended Common Object File Format) file.

Ordinarily, the next step would be to pass the XCOFF file, in turn, to the MakePEF tool, which turns it into a PEF (Preferred Executable Format) file ready to run as a Macintosh application. To build an NLM, however, you don't use MakePEF. Instead, you pass your object files to a special- purpose NLM linker that translates them into a finished NLM, using information about imports and exports taken from adefinition file you supply. (See the next section for more information on the structure and contents of the definition file.) You invoke the NLM linker with an MPW script, NLMLink. As shown in Figure 2, you pass it your definition file along with the usual PowerPC runtime library, PPCRuntime.o, and another library, Prelude.o (provided with the NetWare for PowerPC Software Development Kit), that allows NetWare to load your NLM. The NLMLink script can also accept a list of .o files as arguments, in which case it calls the standard PowerPC linker, PPCLink, for you.

To run and test your NLMs, you'll need the developer's version of NetWare for PowerPC from Novell. You can install it on any Power Macintosh computer.

THE DEFINITION FILE
In addition to your NLM's object (.o) files, you must provide the NLMLink tool with a definition (.def) file. This file, which is usually namedNLMName .def (whereNLMName is the name of your NLM), contains information that NLMLink needs in order to turn your linked object file into a finished NLM. Among other things, the definition file includes a list of all routines imported to and exported from your NLM. Listing 1 shows an example definition file, taken from the sample NLM on this issue's CD.

The keywords description, copyright, and version give the information that will be displayed on the NetWare console when the NLM is loaded.

Figure 2. Building an NLM with MPW

The keyword reentrant specifies that the NLM can be loaded multiple times on the console, but only one copy of the NLM will reside in memory, with all threads sharing that same copy of the code.

The keywords input and output tell the linker what file or files to read and what to name the file it produces.

The keywords start and exit identify routines to execute when the NLM is loaded and unloaded, respectively. The Prelude.o file that you pass to the NLMLink tool defines default start and exit routines, named _Prelude and _Stop, to set up your NLM's threads at load time and clean them up at unload. If your NLM is reentrant, you'll probably supply a start routine of your own to handle reentrant loading; if not, you can just omit thestartkeyword (to use the default start routine_Prelude). If you define your own start routine, make sure it calls _Prelude the first time your NLM is loaded.

The keyword import is followed by a list of the routines that your NLM needs to have available at run time. These routines usually come from the NetWare C Interface, but they could be exported by any other NLM running on the server. Any routine your code calls that is not part of your NLM must be listed here, or the NLMLink tool will report an error.

Finally, the keyword export is followed by a list of the routines that your NLM makes available for other NLMs on the server to call. You need not export any routines at all; however, if you want to give other NLMs access to any of your routines, you must list them here. (Our sample NLM doesn't actually export any routines, but we've included a fictitious one in the sample definition file, just for illustration.)

These are just some of the keywords you can use in a definition file. The NetWare for PowerPC Software Development Kit documentation describes all of the possible keywords and how to use them.

Listing 1. Example definition file

description "AppleTalk Demo NLM"
copyright "Apple Computer, Inc."
version 1, 1, 1
reentrant
input ATDemo.out
output ATDEMO.NLM
start HandleMultipleLoad
exit _Stop
import
    ATAtpClose
    ATAtpGet
    ATAtpOpen
    ATAtpSendRsp
    ATDdpNetinfo
    ATNbpParseEntity
    ATNbpRegister
    ATNbpRemove
    ATZipGetMyZone
    exit
    free
    GetFileServerName
    malloc
    printf
    strcat
    strlen
    strncat
    _StartNLM
    ImportSymbol
    _TerminateNLM
    _SetupArgv
    atexit
    __get_errno_ptr
    BeginThread
    ExitThread
    strcpy
export
    FooBar

A BRIEF TOUR OF THE NETWARE INTERFACE

The NetWare C Interface provides more than 1000 functions for interfacing with the NOS. It's a load-time interface, meaning that function calls are resolved at the time an NLM is loaded rather than at link time. Trying to document the entire NetWare interface here would be like trying to summarize all ofInside Macintosh. We can, however, look at some highlights. The NLMs that make up the NetWare C Interface include, among others, CLIB (C LIBrary), DSAPI (DirectoryServicesAPI), THREADS, NWSNUT (NetWare ScreeN UTility), and TLI (TransportLayer Interface). Together, these NLMs offer interfaces to the following NetWare services:

• high- and low-level I/O
• directory services
• file manipulation
• memory management
• threads
• communications protocols
• math functions
• human interface utilities

These services (which are described in more detail below) are actually only a few of thoseavailable through the NetWare C Interface. Currently, more than 40 different services(analogous to Macintosh Toolbox managers) are available to developers of NLMs. The NetWare for PowerPC Software Development Kit contains documentation on all of these services, as well as the latest development utilities and sample code.

INPUT/OUTPUT
NetWare provides APIs for both synchronous and asynchronous I/O.

DIRECTORY SERVICES
The Directory Services API provides access to the distributed directory services database on a NetWare 4.1 network. NetWare directory services offer functionality very similar to that of the Apple Open Collaboration Environment (AOCE) -- in fact, Apple and Novell are pursuing ways to integrate the two services. Typical calls include NWDSAuthenticate, NWDSCreateObject, and NWDSSearch.

FILE MANIPULATION
NetWare provides several sets of interfaces for file manipulation. Calls such as open, fopen, DFSOpen, and AFPOpenFileFork all open a disk file, but take different parameters and follow different I/O models. You decide which you need, depending on whether you want speed, convenience, or compatibility.

MEMORY MANAGEMENT
NetWare uses the standard C malloc/free model for memory management. NetWare doesn't use a virtual-memory scheme to increase a server's memory capacity beyond that of the available physical RAM, so you must be careful to allocate only as much memory as you actually intend to use. It's also a good idea to include code for handling low-memory conditions in a graceful way.

THREADS
NetWare is a nonpreemptive operating system, meaning that each NLM is responsible for voluntarily giving up control of the processor from time to time, to allow other NLMs to run. Every NLM has at least one thread of execution, known as themain thread, created when the NLM is initially loaded. The NLM can then optionally spawn as many additional threads as it needs. At any given time, exactly one thread is in active control of theprocessor; all others are temporarily suspended. The NOS maintains arun queue of such suspended threads awaiting execution.

The NetWare interface provides a set of routines for thread management, including BeginThread, Delay, EnterCritSec, and ThreadSwitch. The "good citizen" routines CYieldIfNeeded, CYieldWithDelay, and CYieldUntilIdle yield control of the processor to give other NLMs their turn at bat. In addition, many other system calls automatically block (suspend the execution of a thread) while waiting for some external occurrence such as the arrival of a packet on the network, so it isn't always necessary to relinquish the processor explicitly.

COMMUNICATIONS
NetWare's AppleTalk interface implements all of the protocols defined inInside AppleTalk, from the Datagram Delivery Protocol (DDP) to the AppleTalk Filing Protocol (AFP). NetWare also provides native interfaces to IPX/SPX and TCP/IP. For greater flexibility, you can use the NetWare Transport Layer Interface (TLI). Because TLI functions are independent of the underlying transport layer, they allow you to use a variety of protocols, such as AppleTalk, IPX/SPX, and TCP/IP, without having to write extra code.

MATH FUNCTIONS
The Math Services API provides common mathematical functions like min, sqrt, and cos. For maximum efficiency, the implementation on PowerPC servers uses the processor's built-in floating- point capabilities whenever possible.

HUMAN INTERFACE UTILITIES
Many NLMs present a human interface on the server machine, allowing an operator or administrator to perform needed server-management tasks. If you want your NLM to have a graphical (as opposed to a command-line) interface, you can use the NetWare NLM User Interface Services to create windows, menus, and dialog boxes on the server console. Although the interfaces aren't as sophisticated as those of the Macintosh Toolbox, they can help you provide a convenient human interface to your NLM.

A SIMPLE NLM

To illustrate how NLMs are written, we'll look at two examples. Both will run on any server running NetWare. You'll find the code for both examples on this issue's CD.

Our first sample NLM is the obligatory "Hello, world" example, which we'll name HELLO.NLM. The code is short enough that we can show it right here:

/* HELLO.NLM
    This NLM prints the traditional message "Hello, world."
    on the serve console. Type "Load Hello" on the server
    to see it run. 
*/
#include <stdio.h>
main()
    {
    printf("Hello, world.\n");
    }

Pretty painless, right? The reason for including this example is to show that writing an NLM doesn't require you to learn an entirely new programming method. Much of the programming you do when writing an NLM is the same as if you were writing an application for Macintosh or UNIX.

A MORE INTERESTING NLM

Now let's look at another sample NLM, named ATDEMO.NLM. When loaded on your server, ATDEMO watches for an incoming AppleTalk connection and provides the client with server statistics on request, such as the number of clients connected, directory listings, and so forth. (The CD also contains a small Macintosh client application that connects to the server and queries ATDEMO for this information. The client application is provided in "fat binary" form so that it can run in native mode on both PowerPC and 680x0 platforms. We won't examine its code in this article, but it's included on the CD in case you're interested.)

ATDEMO demonstrates three important points about writing NLMs:

• how to make calls to the NetWare C Interface
• how to use the AppleTalk protocol in an NLM
• how to create and schedule threads for execution by the NOS

The code for the entire NLM is contained in a single file, ATDemo.c. It begins with a list of #include macros. Some of these, such as stdio.h and stdlib.h, are standard ANSI includes. Others, such as nwenvrn.h, nwthread.h, and nbp.h, are headers for the NOS. Remember that all routines you call from these header files, even the ANSI C routines, are linked at load time and implemented by the NLMs described earlier. Do not use the ANSI headers from your MPW CIncludes folder -- there may be subtle differences in the header files that could cause debugging nightmares later on.

Like all C programs, an NLM written in C must have a main routine. Macintosh applications typically have a structure based on a main event loop:

main()
    {
        /* Do preliminary setup and initialization. */
        ...
        
        do {
            ...
            WaitNextEvent(...);
            ...
        } while (1);
        
        /* Do final cleanup and exit. */
        ...
    }

The structure of an NLM is a bit different, because the server itself is doing the event processing. Instead of polling the system for events and processing them one at a time in our main thread, we block for action and spawn a separate thread to handle each incoming event. This removes the bottleneck associated with a single point of event processing, with each spawned thread doing its own work and blocking only for its own needs.

The structure of ATDEMO looks like this:

main()
    {
        /* Do preliminary setup and initialization. */
        ...
        
        do {
            ATAtpGet(...);
            ...
            BeginThread(...);
        } while (1);

        /* Do final cleanup and exit. */
        ...
    }

At first glance, our NLM seems to spend all its time in a busy do-while loop. In fact, this is not the case. ATAtpGet is a NOS function that waits to receive an ATP (AppleTalk Transaction Protocol) packet. Like many other functions in the NetWare C Interface, ATAtpGet is a blocking function: it suspends execution of the calling thread while waiting for an ATP packet to arrive, allowing the NOS to run other scheduled threads in the meantime. The thread calling the blocking function gets placed at the end of the run queue; eventually it will work its way back to the front of the queue and resume execution from the point of the suspension. (If our NLM didn't call such a blocking function, we could instead call ThreadSwitchWithDelay at the end of our do-while loop, to relinquish control of the processor explicitly and allow other threads to run.)

When the server eventually receives an ATP packet addressed to our NLM, it reactivates our main thread, causing control to return from the ATAtpGet call and resume with the next instruction. Our NLM next calls the NOS function BeginThread to create a new thread to respond to the packet. The actual code issues this call by means of a subsidiary function, SpinNewSession:

int SpinNewSession(...)
    {
        int completionCode;
    
        completionCode = BeginThread(HandleClientSession, ...);
        return completionCode;      
    }

BeginThread takes a function pointer as its main parameter, creates a new thread to execute the function, and adds the thread to the NOS's run queue. When the time comes to run this thread, the NOS will call the specified function (in this case, an ATDEMO function named HandleClientSession). Thus, instead of a single thread of execution that handles all communications with all clients, we have a main thread that waits for new clients to initiate communications and spins off a subsidiary thread for each such client connection.

Like our main function, HandleClientSession also has ado-whileloop that uses ATAtpGet as the main blocking function:

void HandleClientSession(...)
    {
        /* Allocate data structures and open a connection. */
        ...
        
        ATAtpSendRsp(...);
        
        do {
            ATAtpGet(...);
            quitRequest = HandleRequest(...);
            if (quitRequest) {
                ATAtpClose(...);
                ExitThread();
            }
        } while (1);
    }

ATAtpGet will continue getting packets from the client until the client notifies the server to break the connection. Each time HandleClientSession receives a packet, it calls another ATDEMO function, HandleRequest, to examine the content of the message and determine what specific information the client is requesting. When HandleRequest reports that the client has asked to break the connection, HandleClientSession calls the NOS function ATAtpClose to close the connection and then destroys the thread with the NOS function ExitThread.

NETWARE DEVELOPMENT TIPS

Here are some key points to keep in mind when writing an NLM or porting an existing program to NetWare.

• Don't rule out a NetWare version of your software just because it's not "real Macintosh." Apple's future plans for client/server solutions feature NetWare as a core OS.
• Try to make your NLM platform-independent, if possible. If you avoid the platform-specific features of NetWare for PowerPC, you'll be able to port your NLM to NetWare running on other platforms, including DOS-compatible machines, with little effort.
• Remember that your NLM runs on a server that handles many different clients. Try to make it compatible with clients of any type.
• If your NLM is intended to run on multiple platforms or support multiple transport protocols, use the NetWare Transport Layer Interface (TLI) rather than native protocols. This will save you time and effort when porting to another platform.
• Be careful when developing NLMs with a Macintosh development environment. You're writing an application that has no Macintosh Toolbox underneath: use only the headers and libraries that come with the NetWare for PowerPC Software Development Kit.
• Test your NLM carefully and extensively. While in development, an NLM can be run in isolation, where it can't damage anything but itself. Once it's ready for prime time, it will be loaded as part of the NOS; then if it crashes, it may bring the entire server down with it.
• NetWare is a nonpreemptive multitasking operating system. Be sure to design your threads of execution so that they relinquish the processor frequently, to give other NLMs their fair share of processor time.
• Because NetWare servers have no virtual memory, they're limited to the physical memory available in the computer. Don't be a memory pig!
• Be sure to take advantage of the numerous developer programs and information available from Apple and Novell.

Once you've finished developing and testing your NLM, you'll probably want to get it certified by Novell before you release it to the world. Following the guidelines above will help make that process as speedy and painless as possible.

WHAT NEXT?

This article should give you enough basic information to get started with NetWare and NLMs. Novell recommends that anyone interested in setting up a NetWare system hire a trained specialist called a Certified NetWare Engineer, or CNE, to help with the installation. Many NetWare developers also attend training classes to learn how to port their existing software or develop new NLMs. If you don't want to go to the time and expense of a training course, a couple of good books can go a long way to help you learn what you need to know. See the list at the end of this article for some suggestions.

Before embarking on serious development, you'll definitely want to get Novell's NetWare for PowerPC Software Development Kit (which should be available soon if not by the time you read this). In it you'll find a complete set of software and documentation to assist you in developing your own NLMs. For more information, call Novell at 1-800-NETWARE (1-800-638-9273). For information from Apple on NetWare developer programs, call Apple's Developer Support Center at (408)974-4897 or send a message to AppleLink DEVSUPPORT. In today's networking environment, more and more products, especially client/server programs, are being written for multiple platforms. NetWare gives you a convenient way to develop portable network software without having to rewrite all your code separately for each new platform. Whether you're porting an existing network application or writing a new one, you can benefit greatly by doing it in NetWare.

RECOMMENDED READING

Here are some suggestions for further reading on the subject of NetWare and NLMs:

• Novell's Guide to NetWare 4.0 NLM Programming (Novell Press, 1993).
• "Writing Your Own NetWare Loadable Modules," PC Magazine Volume 12 Issue 20 (November 23, 1993), pages 355-364.
• "Concurrent Programming With the Thread Manager" by Eric Anderson and Brad Post, develop Issue 17. Information on multithreaded programming.

JAMIE OSBORNE (AppleLink JWO) In the short space of a year, Jamie Osborne has gone from doing three-dimensional user interfaces to working on exception-handling routines for a PowerPC Memory Manager to programming NetWare NLMs. When he's not sitting in front of a computer (which, according to his fiancée, is "only when he's sleeping, and maybe not even then"), he keeps busy writing television scripts for Paramount to reject. He hasn't quite figured out what hereally wants to do with his life, but he's reasonably certain it involves long days lounging about in a large house in the hills of New Hampshire.*

Thanks to our technical reviewers Rob Hawley, Bob Heldt, Rich Kubota, Michael McDaniel, and Clara McKenzie. *

If you found this article interesting and would like to see more in-depth NetWare articles in the future, send a note to AppleLink NWDEV.*