README.TXT for the NetPlus (tm) WinSNMP Developer Kit  provided by:

	American Computer & Electronics Corp
	Attn:  TMS Division
	209 Perry Parkway
	Gaithersburg MD  20877  USA
	Tel:  301-258-9850
	Fax:  301-921-0434
	E-mail:  Info@acec.com

Release 1.1.950407

Portions Copyright 1994 and 1995 by American Computer & Electronics Corp
Portions subject to License Agreement

Contents of this file:
    1.  Contents of the Distribution Diskette
    2.  Installation and use of the WinSNMP DLL
    3.  Monitoring tools
    4.  IMPORTANT DISCLAIMER REGARDING SAMPLE APPLICATIONS
    5.  The NP_GET sample application
    6.  The NP_POLL sample application
    7.  The NP_SET sample application
    8.  The NP_WALK sample application
    9.  The NP_TRAPS sample application
   10.  The NP_ALERT sample application
   11.  Additional files in the \NETPLUS\WINSNMP directory
   12.  Changes to WINSNMP.DOC
   13.  Recent fixes and known problems
   14.  WinSock Advisory Information

1.  Contents of the Distribution Diskette:

Files needed to run WinSNMP applications using the NetPlus
WinSNMP DLL are in the \NETPLUS\WINSNMP directory.  These files
include WINSNMP.DLL, NP_WSOCK.EXE, and NP_WSNMP.INI.  You will
also need the NP_UTIL.DLL file (from the \NETPLUS\TOOLS directory) 
to run the WinSNMP utility applications (NP_STATE.EXE and
NP_WSNMP.EXE) and all of the sample applications as delivered.

This directory also includes ancillary WinSNMP/Manager documentation
and development files (which are described in Section 11 below).

A resource monitoring utility, NP_STATE.EXE, is in the
\NETPLUS\TOOLS directory.  This utility is specific to our
WinSNMP DLL and will not work with any other vendor's WinSNMP
DLL.  This directory also contains NP_WSNMP.EXE, which is a
new utility to facilitate maintenance of your NP_WSNMP.INI
file.  NP_WSNMP.EXE is not yet complete and, therefore, is 
not yet a formally supported product, but it does perform
a useful function at this stage so we are distributing it
as a preview item and will welcome any feedback you care to
offer.

Please note that the applications in the \NETPLUS\TOOLS
directory require the NP_UTIL.DLL file, which is also
located in this directory.  Depending upon your personal
setup decisions, you might want to copy this DLL to your
Windows or Windows\System directory.

We also supply the CTL3DV2 runtime and development files in
this directory, just in case you do not already have them.
Please note that CTL3DV2.DLL *must* be istalled in your
Windows\System directory and must *not* be encountered by
Windows anywhere else in your current working directory or path.

Sample source code files for instructional purposes only is in
the following directories [SEE DISCLAIMER IN SECTION 4 BELOW]:

	\NETPLUS\SAMPLES\NP_ALERT
	\NETPLUS\SAMPLES\NP_GET
	\NETPLUS\SAMPLES\NP_POLL
	\NETPLUS\SAMPLES\NP_SET
	\NETPLUS\SAMPLES\NP_TRAPS
	\NETPLUS\SAMPLES\NP_WALK

2.  Installation and use of the WinSNMP DLL:

The following files from the \NETPLUS\WINSNMP directory are required
to use WinSNMP applications (such as the sample programs included)
with the NetPlus (tm) WinSNMP DLL:

	WINSNMP.DLL
	NP_WSOCK.EXE
	NP_WSNMP.INI

The first two files, along with the WINSOCK.DLL appropriate for your
TCP/IP stack, must be in your executable PATH.  Your TCP/IP stack
must support UDP via WinSock.

The NP_WSNMP.INI file *must* be in your *Windows* directory.
This file contains default values for some of the sample applications
and is also used as the "local database" for the WinSNMP.DLL when
operating in "SNMPAPI_TRANSLATED" mode.  Instructions for entries
are included in the "[Entities]", "[Contexts]", "[MIB Variables]", 
and "[Enterprises]" sections of the NP_WSNMP.INI file.  This is a
normal application initialization file and can, therefore, be
created and/or modified using a normal text editor (or with the
NP_WSNMP.EXE utility described later).

The "MyApp" entry in the [Entities] section is used by some
of the sample applications to form a place-holder srcEntity.  You
can edit the correpsonding string if you want it to match your
machine address (but it really does not matter at this time).  You
will probably need to add other entries for agents on your local
(and remote) network(s)...all of the agents included in the
distributed NP_WSNMP.INI file are (most likely) remote to you and
will require both routing and longer timeout values in most cases.

The NetPlus WinSNMP DLL requires *no* changes to any of your
system configuration files (CONFIG.SYS, AUTOEXEC.BAT, PROTOCOL.INI,
WIN.INI, or SYSTEM.INI).

NP_WSOCK.EXE is a "helper" application to the NetPlus WinSNMP
DLL which manages WinSock communications and termination hooks
on behalf of the WinSNMP DLL.  Please note that NP_WSOCK.EXE is
started and stopped automatically by the NetPlus WinSNMP DLL.
A user interface is provided to it so that it can be closed in
the (unlikely) event of an abnormal termination of the WinSNMP
DLL, but it should not normally be used at all.

Once you have copied these files to your PATH, you are ready to
run WinSNMP applications to perform SNMP network management
operations.  In most cases, you will need to know the IP addresses
of agents for the network elements you want to manage and one or
more community strings for each agent.  For trap receipt, you will
normally need to configure the agent--usually via an out-of-band
(i.e., non-SNMP) management interface.  This is standard fare for
SNMP and does not reflect any limitations or restrictions imposed
by the NetPlus WinSNMP DLL.

Errors detected by the WinSNMP DLL are reported back to the calling
application(s) as documented in the WinSNMP/Manager API Specification
(v1.1).  Additional WinSock-related errors which may be detected by
the "helper" application (NP_WSOCK.EXE) are written to a log file
named NP_WSOCK.LOG in the current working directory.


3.  Monitoring tools:

The Norton Utilities (v8.0) "SysWatch" tool was used to monitor
the impact of WinSNMP on a running system.  The results showed
that, even with multiple WinSNMP applications running, memory,
USER, and GDI resources usage was very low (i.e., less than 0.25MB).
If you have access to SysWatch, we encourage you to monitor the
performance of the NetPlus WinSNMP DLL with it and report any
anomalous behavior to your support representative.

The distribution diskette also includes a tool for monitoring
the internal health of the NetPlus (only) WinSNMP DLL:

	\NETPLUS\TOOLS\NP_STATE.EXE

NP_STATE.EXE monitors the dynamic usage of internal resources.
Once you have copied the necessary WinSNMP files to your PATH
(per the previous section), you can run NP_STATE.EXE to verify
that the WinSNMP DLL, "helper" application, and WinSock DLL all
load properly.  You may also run NP_STATE.EXE while running the
various demonstration applications (see the "Samples" section,
below) to get a feel for internal resource utilization patterns.

Options are included under the "File" menu option to keep the
NP_STATE window on top of all others and to save the NP_STATE
window size, position, and option settings for the next invocation.

4.  IMPORTANT DISCLAIMER REGARDING SAMPLE APPLICATIONS:

NOTE:  THE SAMPLE APPLICATIONS ARE PROVIDED ONLY FOR
INSTRUCTIONAL PURPOSES TO ILLUSTRATE SOME APPROACHES
TO WRITING NETWORK MANAGEMENT APPLICATIONS FOR WINDOWS
USING THE WINSNMP API.  THESE APPLICATIONS ARE NOT
DESIGNED TO PERFORM OPERATIONAL TASKS UNDER PRODUCTION
LOADS OR WITH REAL-WORLD REQUIREMENTS FOR ROBUSTNESS AND
RELIABILITY.

NEITHER AMERICAN COMPUTER AND ELECTRONICS CORPORATION
NOR ITS DISTRIBUTORS WHO MIGHT PROVIDE THESE SAMPLE
APPLICATIONS TO USERS MAKE ANY CLAIMS OF USABILITY OR
OFFER ANY WARRANTIES OR GUARANTEES OF ANY KIND WITH
REGARD TO THE USE OF THESE SAMPLES APPLICATIONS IN
ANY WAY WHATSOEVER.

USERS ARE FREE TO EXTRACT, MODIFY, AND RE-USE THE
SOURCE CODE PROVIDED IN THE SAMPLE APPLICATIONS AT
THEIR OWN DISCRETION AND AT THEIR OWN RISK.  REMEMBER,
THIS SAMPLE CODE WAS DEVELOPED STRICTLY FOR TESTING
AND DEMONSTRATION PURPOSES.

All sample applications are provided with all project files
necessary to build them in the MSVC++ v1.5.01 Integrated
Development Environment (IDE).  You must have MSVC++ v1.0 or
later to rebuild these applications "as is".  You might be
able to use some other IDE, but will probably have to make
some adjustments to the project files depending upon your
choice of IDE.

Note, again, that the sample applications are intended as
programming illustrations, not as operational tools.  Some
have only hard-coded agent address and community strings in
them; you can either edit these variables to correspond to
agents you have access to or modify the programs to accept
user, command-line, or environmental inputs.

The NP_WSNMP.HLP file is a general help file for all of
the sample applications, the NetPlus tools that we provide
on the diskette, and the NP_WSNMP.INI local database file.
It is accessible from the Help/Contents menu option of any
of those applciations.

5.  The NP_GET sample application:

This application requires the user to input an agent address
(actually, chose from a list of such agents from the "local
database" in the [Entities] section of the NP_WSNMP.INI file),
community string, and target MIB variable object identifier.
It then performs an SNMP "get" operation and displays the
results if and when a response is received from the agent.

6.  The NP_POLL sample application:

The NP_POLL application illustrates polling of a single agent
for a set of MIB variables.  It is very similar to NP_GET,
except for the addition of a user-specifiable timer loop.

7.  The NP_SET sample application:

This application illustrates the SNMP set operation, using
the [MIB Variables] section of the NP_WSNMP.INI file.

8.  The NP_WALK sample application:

This application illustrates elementary MIB browsing techniques.

9.  The NP_TRAPS sample application:

This application asks the WinSNMP DLL to forward all received
traps to it.  The DLL reformats them as SNMPv2 trap PDUs and
the application displays all relevant received information.

10.  The NP_ALERT sample application:

This application can be used to emit SNMPv1 traps for receipt
by the NP_TRAPS sample application or any SNMP manager with
a compatible administrative configuration.  It uses both the
[Defaults] and [PBX Alarms] sections of the NP_WSNMP.INI file.

11.  Additional files in the \NETPLUS\WINSNMP directory:

	WINSNMP.DOC - this is the v1.1 WinSNMP API specification
				  in MS-Word for Windows (v6.0a) format.

	WINSNMP.H   - this is the "include" file for WinSNMP
				  applications.

	WINSNMP.DEF - useful to applications developers only
				  for showing the ordinal values of the
				  functions exported by the WinSNMP DLL.

	WINSNMP.HLP - this is a WINHELP.EXE compatible version
				  of the WINSNMP.DOC file.

12.  Changes to WINSNMP.DOC:

Since "going to print", so to speak, the WinSNMP industry
working group has adopted one change to the WinSNMP/Manager
API specification (v1.1); namely:

	SnmpSendMsg() and SnmpRecvMsg() both return either
	SNMPAPI_SUCCESS or SNMPAPI_FAILURE, not the RequestID
	as the specification states.  Applications may
	retrieve or confirm the RequestID from a PDU handle
	at any time with the SnmpGetPduData() function.
	Applications may request that the WinSNMP DLL assign
	a generated RequestID value by passing '0' in the
	RequestID parameter of the SnmpCreatePdu() function.
	Applications can force a '0' valued RequestID by
	passing '0' in the RequestID parameter of the
	SnmpSetPduData() function.

13.  Recent fixes and known problems:

A. Some of the sample applications pass NULL pointers for some of
the arguments to the SnmpRecvMsg() function.  These applications
do not care about the return values of these arguments.  The
NetPlus WinSNMP.DLL--per the IETF maxim of "Be generous in what
you accept..."--handles this condition properly.  Other WinSNMP
DLLs might not.  Since handling NULL pointers is not a requirement
defined in the WinSNMP/Manager API for SnmpRecvMsg(), you are
encouraged NOT to use NULL pointers in this context in your
applications to minimize portability problems among multiple
WinSNMP DLLs.  Over time, we will change the SnmpRecvMsg() calls
in our sample applications to not use NULL pointers for output
parameters that we do not care about.

B. In testing the NetPlus WinSNMP DLL with other released
commercial WinSNMP *applications*, we have found it necessary
to relax some of the rather strenuous error checking we were
doing to ensure maximum conformance with the WinSNMP/Manager
API specification.  We are working with those application
developers to reach an accommodation that will be publicly
discussed on the WinSNMP list.  In the meantime, the only
negative impact on developers using the NetPlus WinSNMP DLL
is that some (generally innocuous) programming "mistakes"
will be accepted.

C.  Note that in our "local database" (NP_WSNMP.INI), we
specify entity timeout values in milliseconds.  This allows
for greater efficiency and sharper granularity in certain
internal operations.  The WinSNMP routines which involve
timeout values (e.g., Snmp[Get|Set]Timeout) use centiseconds.

D.  Please note that when you call SnmpGetPduData with an
output hVbl address specified (and assuming the hPdu involved
has an hVbl already attached to it), you receive a handle to
a "new" hVbl which refers to a *copy* of the varbindlist
already attached to the hPdu.  This, of course, works fine
for the primary use of SnmpGetPduData--which is following an
SnmpRecvMsg to dereference the received PDU.  It also works
fine for any other case, as long as you are aware that you
have received a *copy*...i.e., just as though you had made
an SnmpDuplicateVbl call instead.

14.  WinSock Advisory Information

A.  We and/or our customers have tested our WinSNMP DLL and
sample applications with the following WinSock DLLs:

	- Distinct
	- Frontier
	- FTP Software (PC/TCP 2.3 and OnNet v1.0 (PC/TCP 3.0))
	- Microsoft TCP/IP-32
	- NetManage (all but v4.00; earlier and later are OK)
	- Novell LWP (use latest version--4.2--or later)
	- Spry
	- Trumpet
	- WRQ Reflection

B.  Any WinSock-related problems that we can detect at run-time will
be recorded in the NP_WSOCK.LOG file on the current working directory
of the WinSNMP application encountering the error.

C.  The major problem users of the NetPlus WinSNMP SDK have
reported is the following WinSock error:

   [11004 - WSANO_DATA] Valid name, no data record of requested type.

This occurs--if it does--when starting up the NP_WSOCK.EXE helper
application (which is loaded automatically by the NetPlus WinSNMP DLL).
This is a fairly well-known error condition encountered by WinSock
applications and signifies that the user's stack and/or WinSock is/are
mis-configured with respect to host name resolution.  The problem could
be in a faulty DNS setting or a missing hosts file or mis-directed
environment variable.

This is not a WinSNMP-related error and must be resolved in the user's
stack/WinSock configuration.  Fortunately, the resolution is almost
always extremely easy.  Nonetheless, we have enhanced our error log
(NP_WSOCK.LOG) to give complete WinSock error message text and we
have changed from using the WSAAsyncGetHostByName() function to the
synchronous gethostbyname() function to help identify and isolate
this error condition more effectively.

D.  Versions of the Novell LWP prior to v4.2 reported an error #20050
when the Novell program NOVASYNC.EXE was not in the user's path.  This
was simply an incorrect error number; it should have been:

   [10050 - WSAENETDOWN] Network is down.

NOVASYNC.EXE provides the asynchronous services for Novell's WinSock
and must be accessible for our WinSNMP to work with Novell LWP.
