The NetWare API: Getting File Server Configuration Information, Part III
Articles and Tips: article
Senior Research Engineer
Developer Information
01 May 1997
The last in a series of articles on getting file server information. This installment offers programming notes for developers who want to use the File Server Environment functions to get all the available configuration data from each version of NetWare.
- Introduction
- Correction
- Version and Console Privilege Dependencies
- API Dependencies
- Example Program: FSCONFIG.EXE
Introduction
Parts I and II of this DevNote series documented some of the file server configuration data that you can get by calling NetWare's File Server Environment functions. Part I, in the January '97 issue, divided the large set of File Server Environment APIs into three groups, depending on how dynamic the data returned by the API is:
Server Configuration Data--things like how much memory is in the server, and what type of CPU it has, rarely change.
Configurable Parameters--like the server's SET console parameters, can be changed by the console operator, but are unlikely to change from one minute to the next.
Statistics--like the number of packets that a particular protocol stack has routed, change constantly.
This DevNote series focussed on the first two categories. I further divided the file server environment functions into 10 groups. Part I covered the following groups:
Physical Configuration
Set Commands
Communication Protocols
NLMs
Users
Part II covered the remaining 5 groups:
Component Versions
LAN/Router
File System
Disk
Media Manager
Finishing out the series, this DevNote provides some programming notes for those who want to use the File Server Environment functions to get all the available configuration data from each version of NetWare.
Correction
But first, a correction. In Part II (March '97, page 35), I said that the NWGetPhysicalDiskStats API is supported by NetWare 4. This is incorrect; only NetWare 2 supports this API. Thanks to an alert reader for pointing this out (you know who you are).
Version and Console Privilege Dependencies
Most of the File Server Environment APIs are NetWare version-dependent, and most require console privileges, so it is a good idea to find out what version of NetWare is running on the target file server and see whether you have console privileges before calling these APIs. The other alternative is to call the APIs without checking NetWare version or console privilege status, then handling the errors returned by the function. This method is less efficient, however.
Even a cursory look at the File Server Environment reveals redundancies and omissions. Some data items can be obtained by calling two or three different APIs. Many configuration data items that are available in NetWare 2 and 4 are not available in NetWare 3. The reason for this is primarily historical. When NetWare 3 was released, it was decided to provide access to this configuration data at a later time through an NLM.
This plan was scrapped when emphasis shifted to NetWare 4 development. If you really need to manage configuration of NetWare 3 servers, you could write an NLM that implements much of the functionality of the NetWare 2 configuration APIs via NCP extensions. A few third-party network management utility developers have done this.
Anyway, back to version-dependence. There are several APIs that give you the NetWare version number (which actually consists of a major version number, minor version number, and revision):
NWGetFileServerDescription NWCCGetConnInfo NWGetFileServerInformation NWGetFileServerVersion NWGetOSVersionInfo
NWGetFileServerVersion is considered obsolete. NWGetOSVersionInfo is only supported by NetWare 4; it returns a structure with version numbers and other configuration information. NWCCGetConnInfo is the recommended function for obtaining the NetWare version number, but I usually use NWGetFileServerInformation. The following code fragment shows how to use NWGetFileServerInformation to get the NetWare version number.
ccode = NWGetFileServerInformation(conn, serverName,
&majorVer, &minVer,&
&rev, &maxConns, &maxConnsUsed, &
&connsInUse, &numVolumes, &SFTLevel, &TTSLevel);&
if (ccode)
{
printf("NWGetFileServerInformation failed, ccode = %Xh\n", ccode);
exit(1);
}
else
{
printf(" Server name: %s\n", serverName);
printf(" NetWare version %u.%u, rev %u\n", majorVer, minVer, rev);
printf(" Maximum connections used: %u\n", maxConnsUsed);
printf(" Maximum volumes supported: %u\n", numVolumes);
printf(" SFT Level: %u\n", SFTLevel);
printf(" TTS Level: %u\n", TTSLevel);
}
The NWCheckConsolePrivileges API tells you whether you are logged in as a user with console privileges. Usage of this API is fairly straightforward.
ccode = NWCheckConsolePrivileges(conn);
if (ccode)
printf(" Not a console operator.\n");
else
{
printf(" Console operator.\n");
consolePriv = TRUE;
}
Once you have the NetWare version and your console privileges status, you can check these values before calling any of the File Server Environment APIs. In the example below, the NWGetNetworkSerialNumber requires console privileges, and is supported by NetWare 3 and 4.
if ((consolePriv) && ((majorVer == 3) || (majorVer == 4)))
{
ccode = NWGetNetworkSerialNumber(conn, &serialNum, &appNum);&
if (ccode)
printf("NWGetNetWorkSerialNumber failed, ccode = %Xh\n", ccode);
else
{
printf(" Serial number: %d\n", serialNum);
printf(" Application number: %d\n", appNum);
}
}
API Dependencies
Several of the File Server Environment APIs are like the NWGetNetworkSerialNumber function (above). They take a connection number parameter, and they return a few configuration parameters or a data structure. They do not require you to call another API before calling them. On the other hand, there are several APIs that depend on data that is only available by calling another File Server Environment function first. The APIs for getting information about NLMs loaded on the server are a good example. You call NWGetNLMLoadedList to get a list of NLM numbers.
You may need to call NWGetNLMLoadedList more than once to get all the NLM numbers. For each NLM number, you call NWGetNLMInfo to get the NLM's name, the name of the file containing the NLM executable, the NLM's copyright string, and a structure containing configuration information and memory usage statistics for the NLM. The procedure is shown below.
if ((majorVer == 4) && consolePriv)
{
nlm = 0;
do
{
ccode = NWGetNLMLoadedList(conn, nlm, &fseNLMLoadedList);&
if (ccode == 0x89ff)
break;
else if (ccode)
printf("NWGetNLMLoadedList failed, ccode = %Xh\n", ccode);
else
{
for (i=0; i<fseNLMLoadedList.NLMsInList; i++)<
{
printf(" NLM #%d\n",fseNLMLoadedList.NLMNums[i]);
ccode2 = NWGetNLMInfo(conn, fseNLMLoadedList.NLMNums[i], fileName,
NLMName, copyright, &fseNLMInfo);&
if (ccode2)
printf("NLGetNLMInfo failed, ccode = %Xh\n", ccode);
else
{
//file name
printf(" File name: %s\n", fileName);
//nlm name
printf(" NLM name: %s\n", NLMName);
//copyright string
printf(" Copyright: %s\n", copyright);
//ID number (always same as NLM number?)
printf(" ID number: %d\n",
fseNLMInfo.NLMInfo.identificationNum);
//NLM version
printf(" NLM version: %d.%d, revision %d\n",
fseNLMInfo.NLMInfo.majorVersion,
fseNLMInfo.NLMInfo.minorVersion,
fseNLMInfo.NLMInfo.revision);
}
}
}
nlm = fseNLMLoadedList.NLMNums[fseNLMLoadedList.NLMsInList];
}
while (fseNLMLoadedList.NLMsInList == FSE_NLM_NUMS_RETURNED_MAX);
}
The table below shows the dependencies between File Server Environment APIs.
|
File Server Environment API
|
Returns Parameter
|
Required by API
|
|
NWGetNLMLoadedList |
NLM numbers |
NWGetNLMInfo |
|
NWGetActiveProtocolStacks |
Protocol stack numbers |
NWGetProtocolStackConfigInfoNWGetProtocolStackCustomInfo |
|
NWGetActiveLANBoardList |
LAN board numbers |
NWGetLANConfigInfoNWGetProtocolStkNumsByLANBrdNum |
|
NWGetFSDriveMapTable |
Active disk channels |
NWGetDiskChannelStats |
|
NWGetLoadedMediaNumList |
Media numbers |
NWGetMediaNameByMediaNumNWGetProtocolStkNumsByMediaNum |
|
NWGetMediaMgrObjList |
Media Manager object IDs |
NWGetLoadedMediaNumListNWGetMediaMgrObjInfoNWGetMediaMgrObjChildrenList |
Example Program: FSCONFIG.EXE
To illustrate how to use the file server configuration APIs, I wrote a program called FSCONFIG.EXE. It's a primitive command-line program that dumps incredible quantities of data to the screen, but in the process it shows you how to use the File Server Environment APIs to get tons of information about how a particular file server is configured.
See below for a pseudocode outline for FSCONFIG.EXE (along with a few random observations).
FSCONFIG.EXE Algorithm
Verify that low-level NetWare interface initialized correctly (NWCallsInit).
Get connection ID of default file server (NWGetDefaultConnectionID). Old-fashioned connection-oriented paradigm, but it keeps the program simple.
See if logged-in user has console privileges (NWCheckConsolePrivileges).
See if logged-in user is SUPERVISOR or in MANAGER property of the SUPERVISOR object (NWIsManager).
Get file server NetWare version (NWGetFileServerInformation).
If we have console privileges, Get file server component version numbers (NWGetFileServerExtendedInfo, NWGetFileServerVersionInfo).
If console privileges and NetWare 3 or 4, Get network serial number (NWGetNetworkSerialNumber).
If NetWare 4, Get more file server component version numbers (NWGetOSVersionInfo). Partly redundant, but hey, this is an example program.
If NetWare 4, Get server physical configuration (NWGetCPUInfo).
If console privileges and NetWare 2, Get server physical configuration (NWGetFileServerMiscInfo).
If console privileges and NetWare 4, Get categories of server SET parameters (NWGetServerSetCategories).
If console privileges and NetWare 4, Get server SET parameter names, values, flags, and types (NWGetServerSetCommandsInfo). Would be better to categorize parameters, but that's too much work. Maybe in v1.1.
If console privileges and NetWare 4, Get ID numbers of NLMs loaded on the server (NWGetNLMLoadedList). Get information about each NLM (NWGetNLMInfo).
If console privileges and NetWare 4, Get ID numbers of server's protocol stacks (NWGetActiveProtocolStacks). Get config data for each protocol stack (NWGetProtocolStackConfigInfo). Get custom config data for each stack (NWGetProtocolStackCustomInfo).
If console privileges and NetWare 4, Get router configuration data (NWGetGeneralRouterAndSAPInfo).
If NetWare 4, Get ID numbers for LAN cards (NWGetActiveLANBoardList). Get configuration for each card (NWGetLANConfigInfo). Get protocol stacks bound to card (NWGetProtocolStkNumsByLANBrdNum).
If console privileges and NetWare 2, Get active disk channels (NWGetFSDriveMapTable). Get version and config for each disk channel (NWGetDiskChannelStats). Get config for disks on each disk channel (NWGetPhysicalDiskStats).
If console privileges and NetWare 4, Get ID numbers for loaded media (NWGetLoadedMediaNumList). Get name and config for media (NWGetMediaNameByMediaNum). Get protocol stacks bound to media (NWGetProtocolStkNumsByMediaNum).
If console privileges and NetWare 4, Get ID numbers for media manager objects (NWGetMediaMgrObjList). Get child objects of each object (NWGetMediaMgrObjChildrenList). Get config for each object and child (NWGetMediaMgrObjInfo).
Getting FSCONFIG.EXE
To get a copy of FSCONFIG.EXE, send an email message to novell_research@novell.com, with FSCONFIG.ZIP in the subject line. The program will also be available thorough our web site at http://developer.novell.com/
* 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.