The NetWare API: Managing the Server from a Client
Articles and Tips: article
Senior Research Engineer
Developer Information
01 Aug 1997
Tells how a number of network administration tasks can now be performed from a workstation. These include loading or unloading NLMs, mounting volumes, executing NCF scripts, setting server SET parameters, and adding name spaces to NetWare volumes.
- Introduction
- Loading and Unloading NLMs
- Mounting and Dismounting Volumes
- Executing NCF files
- Setting Server SET Parameters
- Adding Name Spaces to Volumes
- Getting Server Management Example Code
Introduction
With the release of NetWare v4.1, Novell added several APIs that enable network administrators to do several tasks at a client workstation that previously could only be performed at the file server console (or via Rconsole). These APIs comprise a new category called Server Management. You can use them to create utilities that:
Load or Unload NLMs.
Mount volumes.
Execute NCF scripts.
Set server SET parameters.
Add name spaces to NetWare volumes.
The Server Management APIs are fairly closely connected to the File Server Environment functions, which I discussed in a three-part series of DevNotes called "The NetWare API: Getting File Server Configuration Information" that appeared in the January, March, and May '97 issues. The example program that went with this DevNote series, FSCONFIG, illustrates how to get information that will help you work with the Server Management functions. For example, FSCONFIG gets a list of NLMs that are loaded on a target server. This information can be useful before calling the Server Management functions that load and unload NLMs. To get a copy of FSCONFIG, send an email message to novell_research@novell.com, with "FSCONFIG.ZIP" in the subject line.
The Server Management APIs are fairly easy to use, and all operate in a similar manner, so we'll take a detailed look at a simple example program that loads and unloads NLMs, then talk about the unique aspects of the other Server Management APIs. If you want to see some example code that shows how to use the other Server Management APIs, stay tuned and I'll tell you how to get it.
Loading and Unloading NLMs
Two Server Management APIs, NWSMLoadNLM and NWSMUnloadNLM, enable you to load and unload NLMs from a client workstation. NWSMLoadNLM requires only two parameters, a connection handle for the file server you want to load the NLM on, and the command line (minus the "LOAD" command) to pass to the server:
N_EXTERN_LIBRARY NWCCODE NWSMLoadNLM (NWCONN_HANDLE connHandle, pnstr8 loadCommand);
You must have console privileges before calling this function (or any other Server Management function).
The REMOTE NLM is an example of an NLM that accepts command line parameters. It allows you to specify a password when the NLM is loaded at the file server console. To load REMOTE using NWSMLoadNLM, get a connection handle to the appropriate file server, set loadCommand to "REMOTE password" then call NWSMLoadNLM. For the function call to succeed, REMOTE.NLM must be in the SYS:SYSTEM directory, somewhere in the server's search path, or you must specify the path where REMOTE.NLM is located.
To unload an NLM, all you need is a connection handle for the appropriate file server, and the name of the NLM to be unloaded:
N_EXTERN_LIBRARY NWCCODE NWSMUnloadNLM
(NWCONN_HANDLE connHandle,
pnstr8 NLMName);
You'll probably want to know which NLMs are loaded before you try to unload one. I described how to do this in, "The NetWare API: Getting File Server Configuration Information, Part I" in the January '97 issue. To find out if an NLM is loaded, you first call NWGetNLMLoadedList to get a list of numbers that refer to NLMs that are currently loaded on the server, then call NWGetNLMInfo for each NLM reference number to get the name of each NLM.
The FSCONFIG example program that I mentioned at the beginning of this DevNote shows how to use NWGetNLMLoadedList and NWGetNLMInfoto get the names of NLMs loaded on a file server.
Example Program: LOADNLM.C
Okay, let's look at an example program that uses NWSMLoadNLM and NWSMUnloadNLM to load or unload an NLM. This is a brain-dead DOS-style program that loads an NLM on a specified file server.
The command-line syntax for the program looks like:
LOADNLM <serverName< <NLMname< [/U]<
/U to unload the specified NLM
The program prompts the user to enter any command-line parameters to be passed to the specified NLM. The complete source code for the program is given below, with a few comments thrown in. It starts with a few declarations:
#include <stdio.h<<
#include <stdlib.h<<
#include <string.h<<
#include <conio.h<<
#include <nwcalls.h<<
#include <nwclxcon.h<<
#include <nwsm.h<<
void Usage(void);
int main(int argc, char *argv[])
{
NWCCODE ccode;
nstr8 nlmCommand[482];
nstr8 buffer[480] = {(char)480};
pnstr8 params;
NWCONN_HANDLE conn;
nstr8 serverName[64];
nuint8 majorVer, minVer, rev, SFTLevel, TTSLevel;
nuint16 maxConnsUsed, maxConns, connsInUse, numVolumes;
nuint8 unload = FALSE;
nuint8 retValue = 1;
Call NWCallsInit to initialize data structures used by other NWCalls functions.
ccode = NWCallsInit(NULL, NULL);
if (ccode)
{
printf("Unable to initialize NetWare library, ccode = %04Xh\n", ccode);
return 1;
}
Parse the command line. There should be a server name and an NLM name. There may also be a "/U" option if the user wants to unload the NLM.
if (argc == 2)
{
if (strcmp(argv[1], "/?") == 0)
{
Usage();
return 0;
}
}
else if ((argc != 3) && (argc !=4))
{
printf("Incorrect number of arguments\n");
Usage();
return 1;
}
else
{
strcpy(serverName, strupr(argv[1]));
strcpy(nlmCommand, strupr(argv[2]));
if (argc == 4)
{
if (stricmp(argv[3], "/u") == 0)
unload = TRUE;
else
{
printf("Invalid argument: %s\n", argv[3]);
Usage();
return 1;
}
}
}
Open an unlicensed connection to the specified server.
ccode = NWCCOpenConnByName(0, serverName, NWCC_NAME_FORMAT_BIND,
NWCC_OPEN_UNLICENSED, (nuint)NULL, &cconn);&
if (ccode)
{
printf("Unable to open a connection to %s, ccode = %04Xh\n",
serverName, ccode);
return 1;
}
License the connection we just opened.
ccode = NWCCLicenseConn(conn);
if (ccode)
{
printf("Unable to license connection to %s, ccode = %04Xh\n",
serverName, ccode);
ccode = NWCCCloseConn(conn);
return 1;
}
Check the server version. NWSMLoadNLM and NWSMUnloadNLMonly work on NetWare 4 (or IntranetWare 4.11+).
ccode = NWGetFileServerInformation(conn, serverName, &majorVer, &minVer, &rev,&
&maxConns, &maxConnsUsed, &connsInUse,&
&numVolumes, &SFTLevel, &TTSLevel);&
if (ccode)
{
printf("Unable to get file server version for %s, ccode = %04Xh\n",
serverName, ccode);
return 1;
}
if (majorVer < 4)
{
printf("Must be NetWare v4 or greater.\n");
return 1;
}
Check console privileges. You must have console privileges to call any of the Server Management APIs.
ccode = NWCheckConsolePrivileges(conn);
if (ccode)
{
printf("You are not a console operator on %s\n", serverName);
return 1;
}
Get command-line parameters to pass to the NLM.
if (!unload)
{
printf("Parameters to pass to %s: ", nlmCommand);
params = cgets(buffer);
if (buffer[1] > 0)
{
strcat(nlmCommand, " ");
strcat(nlmCommand, params);
}
}
Load or unload the NLM.
if (unload)
{
ccode = NWSMUnloadNLM(conn, nlmCommand);
if (ccode)
{
printf("Unable to unload %s, ccode = %04Xh\n", nlmCommand, ccode);
retValue = 1;
}
else
{
printf("Unloaded %s from server %s\n", nlmCommand, serverName);
retValue = 0;
}
}
else
{
ccode = NWSMLoadNLM(conn, nlmCommand);
if (ccode)
{
printf("Unable to load %s, ccode = %04Xh\n", nlmCommand, ccode);
retValue = 1;
}
else
{
printf("Loaded %s on server %s\n", nlmCommand, serverName);
retValue = 0;
}
}
Unlicense and close the connection.
ccode = NWCCUnlicenseConn(conn); ccode = NWCCCloseConn(conn); return retValue; }
A function to display LOADNLM's command-line syntax.
void Usage(void)
{
printf("Usage: LOADNLM <serverName< <NLMname< [/U]\n");<
printf(" /U to unload the specified NLM\n");
}
The rest of the Server Management APIs are about as simple to use as NWSMLoadNLM and NWSMUnloadNLM. I'll just list a few points that are unique to each API.
Mounting and Dismounting Volumes
The APIs for mounting and dismounting volumes are NWSMMountVolume, NWSMDismountVolumeByName, and NWSMDismountVolumeByNumber. As with NWSMLoadNLM, these functions require a connection handle to the file server on which the function is to operate. NWSMMountVolume also requires the name of the volume to be mounted. If successful at mounting the volume, NWSMMountVolume returns the volume number the file server assigned to the volume:
N_EXTERN_LIBRARY NWCCODE NWSMMountVolume (NWCONN_HANDLE connHandle, pnstr8 volumeName, pnuint32 volumeNumber);
Your program can save this volume number to pass to NWSMDismountVolumeByNumber, if it should become necessary to dismount the volume:
N_EXTERN_LIBRARY NWCCODE NWSMDismountVolumeByNumber (NWCONN_HANDLE connHandle, nuint16 volumeNumber);
NWSMDismountVolumeByName enables you to dismount a volume when you know the volume's name, rather than its number:
N_EXTERN_LIBRARY NWCCODE NWSMDismountVolumeByName (NWCONN_HANDLE connHandle, pnstr8 volumeName);
The FSCONFIG example program that I mentioned at the beginning of this DevNote shows how to use NWGetVolumeName and NWGetVolumeInfoByLevel to get the names and configuration information for all volumes loaded on a server.
Executing NCF files
NWSMExecuteNCFFile executes NCF script files, and is probably the simplest function in the Server Management category. It takes two parameters, a file server connection handle, and the name of the NCF file to be executed:
N_EXTERN_LIBRARY NWCCODE NWSMExecuteNCFFile (NWCONN_HANDLE connHandle, pnstr8 NCFFileName);
The NCFFileName parameter is a null-terminated string that may include a volume and directory path. If a path is not specified, the server looks for the NCF file in SYS:SYSTEM and any other directories in its search path.
Setting Server SET Parameters
There are two functions that set server SET parameters, one for integer parameters and one for string parameters:
N_EXTERN_LIBRARY NWCCODE NWSMSetDynamicCmdIntValue (NWCONN_HANDLE connHandle, pnstr8 setCommandName, nuint32 cmdValue); N_EXTERN_LIBRARY NWCCODE NWSMSetDynamicCmdStrValue (NWCONN_HANDLE connHandle, pnstr8 setCommandName, pnstr8 cmdValue);
The parameters that display an ON/OFF value are actually integer parameters, with OFF = 0 and ON = 1.
To get the names and current values of server SET parameters, use NWGetServerSetCommandsInfo. The FSCONFIG example program shows how to call NWGetServerSetCommandsInfo.
Adding Name Spaces to Volumes
Adding a name space to a volume is not something you should do routinely. It increases the amount of disk space used by the file system for file and directory names and attributes and places greater demands on server memory to cache directory information. And once the disk space has been allocated for the new name space, it's very difficult to remove the name space and recover the allocated disk space. Still, there are times when you really want to add a name space to a volume. To do so, you call NWSMAddNSToVolume.
NWSMAddNSToVolume requires a file server connection handle, the number of the volume to which the name space is to be loaded, and a value representing which name space is to be added:
N_EXTERN_LIBRARY NWCCODE NWSMAddNSToVolume (NWCONN_HANDLE connHandle, nuint16 volNumber, nuint8 namspc);
The volume must be mounted, and the name space (.NAM) module must be loaded. For example, if you want to add the MAC name space to volume V2, you could call NWSMMountVolume to mount V2, then call NWSMLoadNLM to load MAC.NAM, then call NWSMAddNSToVolume to add the MAC name space to V2.
The FSCONFIG example program I mentioned at the beginning of this DevNote shows how to get a list of name spaces that have been added to a specified volume.
The following constants are declared in NWNAMSPC.H, representing each of the non-DOS name spaces you can add to a volume:
NW_NS_MAC NW_NS_NFS NW_NS_FTAM NW_NS_OS2
You must call NWSMAddNSToVolume for each name space you want to add to a volume. You cannot AND or OR values together. The OS2 name space provides the long file names used by Windows 95 and NT.
Getting Server Management Example Code
I've written some simple example programs that illustrate how to call each of the Server Management functions. They're bare-bones examples, written in C with minimal error handling, and a DOS-style command-line interface. But you may want to take a look at them before using the Server Management API, particularly if you're new to NetWare programming.
* Originally published in Novell AppNotes
Disclaimer
The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.