Compaq Compaq TCP/IP Services for OpenVMS Owner's manual

CompaqTCP/IPServicesfor
OpenVMS
SNMPProgrammingand
Reference
Order Number: AA–R04BC–TE
January 2001
Revision/Update Information: This manual supersedes the DIGITAL
TCP/IP Services for OpenVMS eSNMP
Programming and Reference, Version
5.0.
Software Version: Compaq TCP/IP Services for OpenVMS
Version 5.1
Operating Systems: OpenVMS Alpha Versions 7.1, 7.2-1
OpenVMS VAX Versions 7.1, 7.2
Compaq Computer Corporation
Houston, Texas

© 2001 Compaq Computer Corporation
COMPAQ, VAX, VMS, and the Compaq logo Registered in U.S. Patent and Trademark Office.
OpenVMS and Tru64 are trademarks of Compaq Information Technologies Group, L.P. in the United
States and other countries.
All other product names mentioned herein may be trademarks of their respective companies.
Confidential computer software. Valid license from Compaq required for possession, use, or copying.
Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software
Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government
under vendor’s standard commercial license.
Compaq shall not be liable for technical or editorial errors or omissions contained herein. The
information in this document is provided "as is" without warranty of any kind and is subject
to change without notice. The warranties for Compaq products are set forth in the express
limited warranty statements accompanying such products. Nothing herein should be construed as
constituting an additional warranty.
ZK6530
This document is available on CD-ROM.
This document was prepared using DECdocument, Version 3.3-1b.

Contents
Preface ............................................................ vii
1 Overview
1.1 SNMP Architecture . . ........................................ 1–1
1.2 Request Handling . . . ........................................ 1–2
1.3 TCP/IP Services Components for SNMP . . . ....................... 1–4
1.4 Writing an eSNMP Subagent . . . ................................ 1–5
1.5 The eSNMP API............................................. 1–6
1.5.1 The SNMP Utilities ....................................... 1–7
1.6 The MIB Compiler . . . ........................................ 1–7
1.7 SNMP Versions ............................................. 1–8
1.7.1 Using Existing (SNMP Version 1) MIB Modules . . ............... 1–8
1.8 For More Information ........................................ 1–9
2 MIBs Provided with TCP/IP Services
2.1 Overview of the Host Resources MIB ............................. 2–1
2.1.1 Defining Host Resources MIB Implemented Objects .............. 2–1
2.1.2 Restrictions to Host Resources MIB ........................... 2–3
2.2 Overview of MIB II . . ........................................ 2–5
2.2.1 MIB II Implemented Groups ................................ 2–6
2.2.2 Restrictions to MIB II Implementation . ....................... 2–6
3 Creating a Subagent Using the eSNMP API
3.1 Creating a MIB Specification . . . ................................ 3–1
3.2 The Structure of Management Information . ....................... 3–1
3.2.1 Assigning Object Identification Codes . . ....................... 3–2
3.2.2 MIB Subtrees ............................................ 3–2
3.3 Creating a MIB Source File .................................... 3–5
3.3.1 Writing the ASN.1 Input File................................ 3–5
3.3.2 Processing the Input File with the MIB Compiler . ............... 3–5
3.3.2.1 UNIX Utilities Supplied with TCP/IP Services ............... 3–7
3.3.2.2 Object Tables . ........................................ 3–7
3.3.2.3 The subtree_TBL.H Output File ........................... 3–7
3.3.2.4 The subtree_TBL.C Output Files . . . ....................... 3–9
3.4 Including the Routines and Building the Subagent . . . ............... 3–11
3.5 Including Extension Subagents in the Startup and Shutdown
Procedures . ................................................ 3–12
iii

4 Using the SNMP Utilities
4.1 Using the MIB Browser ....................................... 4–1
4.1.1 MIB Browser Parameters. . . ................................ 4–1
4.1.2 MIB Browser Flags ....................................... 4–2
4.1.3 MIB Browser Data Types . . . ................................ 4–5
4.1.4 Command Examples for snmp_request . ....................... 4–6
4.2 Using the Trap Sender and Trap Receiver Programs . . ............... 4–8
4.2.1 Entering Commands for the Trap Sender Program ............... 4–9
4.2.1.1 Trap Sender Parameters ................................ 4–9
4.2.1.2 Trap Sender Flags ..................................... 4–10
4.2.1.3 Trap Sender Examples . . ................................ 4–11
4.2.2 Entering Commands for the Trap Receiver Program .............. 4–12
4.2.2.1 Trap Receiver Flags .................................... 4–12
4.2.2.2 Setting Up an SNMP Trap Service. . ....................... 4–12
4.2.2.3 Trap Receiver Examples . ................................ 4–13
5 eSNMP API Routines
5.1 Interface Routines . . . ........................................ 5–1
esnmp_init . ................................................ 5–2
esnmp_register .............................................. 5–3
esnmp_unregister............................................ 5–6
esnmp_register2 ............................................. 5–7
esnmp_unregister2 . . . ........................................ 5–11
esnmp_capabilities . . . ........................................ 5–12
esnmp_uncapabilities . ........................................ 5–13
esnmp_poll . ................................................ 5–14
esnmp_are_you_there . ........................................ 5–15
esnmp_trap ................................................ 5–16
esnmp_term ................................................ 5–17
esnmp_sysuptime ............................................ 5–18
5.2 Method Routines ............................................ 5–19
*_get Routine ............................................... 5–20
*_set Routine ............................................... 5–22
5.2.1 Processing *_set Routines . . ................................ 5–24
5.2.2 Method Routine Applications Programming ..................... 5–26
5.2.3 Value Representation ...................................... 5–27
5.3 Support Routines . . . ........................................ 5–30
o_integer . . ................................................ 5–31
o_octet .................................................... 5–33
o_oid...................................................... 5–34
o_string . . . ................................................ 5–35
o_counter64 ................................................ 5–37
str2oid .................................................... 5–38
sprintoid. . . ................................................ 5–39
instance2oid ................................................ 5–40
oid2instance ................................................ 5–42
inst2ip .................................................... 5–44
cmp_oid . . . ................................................ 5–47
iv

cmp_oid_prefix .............................................. 5–48
clone_oid . . ................................................ 5–49
free_oid . . . ................................................ 5–50
clone_buf . . ................................................ 5–51
mem2oct. . . ................................................ 5–52
cmp_oct . . . ................................................ 5–53
clone_oct . . ................................................ 5–54
free_oct . . . ................................................ 5–55
free_varbind_data . . . ........................................ 5–56
set_debug_level ............................................. 5–57
is_debug_level .............................................. 5–58
ESNMP_LOG ............................................... 5–59
__print_varbind ............................................. 5–60
set_select_limit.............................................. 5–61
__set_progname ............................................. 5–62
__restore_progname . . ........................................ 5–63
__parse_progname . . . ........................................ 5–64
esnmp_cleanup .............................................. 5–65
6 Troubleshooting eSNMP Problems
6.1 Modifying the Subagent Error Limit ............................. 6–1
6.2 Modifying the Subagent Timeout ................................ 6–1
6.3 Log Files . . ................................................ 6–2
Index
Figures
1–1 SNMP Architecture ....................................... 1–2
1–2 eSNMP Data Flow ........................................ 1–3
3–1 MIB II in SMI Tree Structure ............................... 3–3
Tables
1TCP/IP Services Documentation ............................. viii
1–1 SNMP Component Files .................................... 1–4
1–2 Files for Building a Subagent ............................... 1–6
2–1 Host Resources MIB Objects ................................ 2–1
4–1 snmp_request Command Parameters . . . ....................... 4–1
4–2 Flags for the snmp_request Command . . ....................... 4–3
4–3 Data Types for the snmp_request and snmp_trapsnd Commands .... 4–5
4–4 Parameters for the snmp_trapsnd Command .................... 4–10
4–5 Flags for the snmp_trapsnd Command . ....................... 4–10
4–6 snmp_traprcv Command Flags............................... 4–12
5–1 Interface Routines ........................................ 5–1
v

Preface
The Compaq TCP/IP Services for OpenVMS product is the Compaq
implementation of the TCP/IP networking protocol suite and internet services
for OpenVMS Alpha and OpenVMS VAX systems.
A layered software product, TCP/IP Services provides a comprehensive suite
of functions and applications that support industry-standard protocols for
heterogeneous network communications and resource sharing.
This manual describes the features of the Simple Network Managment Protocol
(SNMP) provided with TCP/IP Services. It also describes the extensible SNMP
(eSNMP) application programming interface (API) and development environment.
See the Compaq TCP/IP Services for OpenVMS Installation and Configuration
manual for information about installing, configuring, and starting this product.
Intended Audience
This manual is for experienced OpenVMS and UNIX system managers and
assumes a working knowledge of TCP/IP networking, TCP/IP terminology, and
some familiarity with the TCP/IP Services product.
Document Structure
This manual contains the following chapters:
• Chapter 1 describes the implementation of eSNMP provided with Compaq
TCP/IP Services for OpenVMS.
• Chapter 2 describes the groups and objects implemented with the Host
Resources MIB and MIB II that are provided with the eSNMP software.
• Chapter 3 describes how to use the eSNMP API to create a MIB subagent to
manage entities or applications.
• Chapter 4 describes the trap sender, trap receiver, and MIB browser utilities
provided with TCP/IP Services.
• Chapter 5 provides reference information about the eSNMP API routines.
• Chapter 6 describes some troubleshooting aids provided with TCP/IP Services.
vii

Related Documents
Table 1 lists the documents available with this version of TCP/IP Services.
Table 1 TCP/IP Services Documentation
Manual Contents
DIGITAL TCP/IP Services for
OpenVMS Concepts and Planning This manual provides conceptual information about networking and the TCP/IP protocol including a description of the Compaq
implementation of the Berkeley Internet Name Domain (BIND)
service and the Network File System (NFS). It outlines general
planning issues to consider before configuring your system to use
the TCP/IP Services software.
This manual also describes the manuals in the documentation
set, provides a glossary of terms and acronyms for the TCP/IP
Services software product, and documents how to contact the
InterNIC Registration Service to register domains and access
Request for Comments (RFCs).
Compaq TCP/IP Services for OpenVMS
Release Notes This text file describes new features and changes to the software including installation, upgrade, configuration, and compatibility
information. These notes also describe new and existing software
problems and restrictions, and software and documentation
corrections.
Print this text file at the beginning of the installation procedure
and read it before you install TCP/IP Services.
Compaq TCP/IP Services for OpenVMS
Installation and Configuration This manual explains how to install and configure the TCP/IP Services layered application product.
DIGITAL TCP/IP Services for
OpenVMS User’s Guide This manual describes how to use the applications available with TCP/IP Services such as remote file operations, email, TELNET,
TN3270, and network printing. This manual explains how to use
these services to communicate with systems on private internets
or on the worldwide Internet.
Compaq TCP/IP Services for OpenVMS
Management This manual describes how to configure and manage the TCP/IP Services product.
Use this manual with the Compaq TCP/IP Services for
OpenVMS Management Command Reference manual.
Compaq TCP/IP Services for OpenVMS
Management Command Reference This manual describes the TCP/IP Services management commands.
Use this manual with the Compaq TCP/IP Services for
OpenVMS Management manual.
Compaq TCP/IP Services for OpenVMS
Management Commands Quick
Reference Card
This reference card lists the TCP/IP management commands by
component and describes the purpose of each command.
Compaq TCP/IP Services for OpenVMS
UNIX Commands Quick Reference Card This reference card contains inforomation about commonly performed network management tasks and their corresponding
TCP/IP management and Compaq Tru64 UNIX command
formats.
DIGITAL TCP/IP Services for
OpenVMS ONC RPC Programming This manual presents an overview of high-level programming using open network computing remote procedure calls (ONC
RPC). This manual also describes the RPC programming
interface and how to use the RPCGEN protocol compiler to
create applications. (continued on next page)
viii

Table 1 (Cont.) TCP/IP Services Documentation
Manual Contents
Compaq TCP/IP Services for OpenVMS
Sockets API and System Services
Programming
This manual describes how to use the Sockets API and OpenVMS
system services to develop network applications.
Compaq TCP/IP Services for OpenVMS
SNMP Programming and Reference This manual describes the Simple Network Management Protocol (SNMP) and the SNMP application programming interface
(eSNMP). It describes the subagents provided with TCP/IP
Services, utilities provided for managing subagents, and how to
build your own subagents.
Compaq TCP/IP Services for OpenVMS
Tuning and Troubleshooting This manual provides information about how to isolate the causes of network problems and how to tune the TCP/IP Services
software for the best performance.
Compaq TCP/IP Services for OpenVMS
Guide to IPv6 This manual describes the IPv6 environment, the roles of systems in this environment, the types and function of the
different IPv6 addresses, and how to configure TCP/IP Services
to access the 6bone network.
For additional information about Compaq OpenVMS products and services, access
the Compaq website at the following location:
http://www.openvms.compaq.com/
For a comprehensive overview of the TCP/IP protocol suite. you might find the
book Internetworking with TCP/IP: Principles, Protocols, and Architecture,by
Douglas Comer, useful.
Reader’s Comments
Compaq welcomes your comments on this manual. Please send comments to
either of the following addresses:
Internet [email protected]
Mail Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698
How to Order Additional Documentation
Visit the following World Wide Web address for information about how to order
additional documentation:
http://www.openvms.compaq.com/
If you need help deciding which documentation best meets your needs, call
800-282-6672.
Conventions
The name TCP/IP Services means both:
• Compaq TCP/IP Services for OpenVMS Alpha
• Compaq TCP/IP Services for OpenVMS VAX
The name UNIX refers to the Compaq Tru64 UNIX operating system.
ix

The following conventions are used in this manual. In addition, please note that
all IP addresses are fictitious.
Ctrl/xA sequence such as Ctrl/xindicates that you must hold down
the key labeled Ctrl while you press another key or a pointing
device button.
PF1 xA sequence such as PF1 xindicates that you must first press
and release the key labeled PF1 and then press and release
another key or a pointing device button.
Return In examples, a key name enclosed in a box indicates that
you press a key on the keyboard. (In text, a key name is not
enclosed in a box.)
In the HTML version of this document, this convention appears
as brackets, rather than a box.
. . . A horizontal ellipsis in examples indicates one of the following
possibilities:
• Additional optional arguments in a statement have been
omitted.
• The preceding item or items can be repeated one or more
times.
• Additional parameters, values, or other information can be
entered.
.
.
.
A vertical ellipsis indicates the omission of items from a code
example or command format; the items are omitted because
they are not important to the topic being discussed.
( ) In command format descriptions, parentheses indicate that you
must enclose choices in parentheses if you specify more than
one.
[ ] In command format descriptions, brackets indicate optional
choices. You can choose one or more items or no items.
Do not type the brackets on the command line. However,
you must include the brackets in the syntax for OpenVMS
directory specifications and for a substring specification in an
assignment statement.
| In command format descriptions, vertical bars separate choices
within brackets or braces. Within brackets, the choices are
optional; within braces, at least one choice is required. Do not
type the vertical bars on the command line.
{ } In command format descriptions, braces indicate required
choices; you must choose at least one of the items listed. Do
not type the braces on the command line.
bold text This typeface represents the introduction of a new term. It
also represents the name of an argument, an attribute, or a
reason.
italic text Italic text indicates important information, complete titles
of manuals, or variables. Variables include information that
varies in system output (Internal error number), in command
lines (/PRODUCER=name), and in command parameters in
text (where dd represents the predefined code for the device
type).
UPPERCASE TEXT Uppercase text indicates a command, the name of a routine,
the name of a file, or the abbreviation for a system privilege.
x

Monospace text Monospace type indicates code examples and interactive screen
displays.
This typeface indicates UNIX system output or user input,
commands, options, files, directories, utilities, hosts, and users.
In the C programming language, this typeface identifies the
following elements: keywords, the names of independently
compiled external functions and files, syntax summaries, and
references to variables or identifiers introduced in an example.
- A hyphen at the end of a command format description,
command line, or code line indicates that the command or
statement continues on the following line.
numbers All numbers in text are assumed to be decimal unless
otherwise noted. Nondecimal radixes—binary, octal, or
hexadecimal—are explicitly indicated.
xi

1
Overview
The Simple Network Management Protocol (SNMP) is the de facto industry
standard for managing TCP/IP networks. The protocol defines the role of a
network management station (NMS) and the SNMP agent. SNMP allows remote
users on an NMS to monitor and manage network entities such as hosts, routers,
X terminals, and terminal servers.
TCP/IP Services provides support for SNMP Version 2, using the Extensible
Simple Network Management Protocol (eSNMP) architecture, under which a
single master agent can support any number of subagents. The TCP/IP Services
implementation of eSNMP includes a master agent, two subagents, an application
programming interface (API), tools used to build additional subagents, startup
and shutdown procedures, and text-based configuration files.
This chapter provides an overview of the Compaq implementation of eSNMP.
Topics include:
• eSNMP master agent and subagent architecture (Section 1.1)
• The procedure for handling SNMP requests (Section 1.2)
• The components of the TCP/IP Services software kit that implement SNMP
(Section 1.3)
• The files useful in developing your own subagent (Section 1.4)
• The eSNMP API (Section 1.5)
• The management information base (MIB) compiler (Section 1.6)
• The impact of running SNMP Version 1 subagents against the SNMP Version
2 implementation provided with TCP/IP Services (Section 1.7)
• Sources of additional information about implementing subagents (Section 1.8)
1.1 SNMP Architecture
Figure 1–1 illustrates the SNMP architecture.
Overview 1–1

Overview
1.1 SNMP Architecture
Figure 1–1 SNMP Architecture
Master Agent
SNMP/ASN.1
Library
eSNMPAPI
AgentX (TCP/IP V5.1)
Subagent 1 Subagent 2 Subagent n
TCP/IP Kernel
OpenVMS
VM-0704A-AI
The SNMP environment consists of the following elements:
• The master agent, a process that runs on the host and handles SNMP
requests from clients over the standard SNMP well-known port 161.
• One or more subagents, each of which provides access to the MIB data
specified in client requests. In the TCP/IP Services implementation, the
master agent contains two resident subagents, one that handles a subset of
MIB II variables, and another that handles the Host Resources MIB. These
MIBs are described in Chapter 2.
• The SNMP ASN.1 library, used by the master agent to interpret ASN.1
messages.
• The eSNMP API, the application programming interface that provides
routines for programming your own subagents. This API runs on the AgentX
routines, which are internal to the SNMP architecture.
• The TCP/IP kernel running on the OpenVMS operating system.
The master agent and subagents communicate by means of the AgentX
protocol, which is based on RFC 2741.
For information about configuring and managing the SNMP service, refer to the
Compaq TCP/IP Services for OpenVMS Management guide.
1.2 Request Handling
The eSNMP software manages network communication by having the master
agent listen for requests and then passes the requests to the appropriate
subagent.
Figure 1–2 illustrates communication between the master agent and subagents.
1–2 Overview

Overview
1.2 Request Handling
Figure 1–2 eSNMP Data Flow
VM-0705A-AI
Client
Trap
client Master Agent
Subagent 1
Subagent 2
Subagent 1
Client
Master Agent
Subagent n
NMS1
NMS2
Legend:
Host 1
Host 2
Network 161
161
705
Flow of trap notification
Flow of get/set request
Flow of "are_you_there" message
The process of communication for a request is illustrated with dashed lines and
includes the following steps:
1. The network management station (NMS) (sometimes called the client),
originates SNMP requests to obtain and set information.
Note
The client component is not provided with TCP/IP Services.
To provide access to MIBs and to test SNMP communication, TCP/IP
Services provides the following utilities:
• MIB browser
• Trap sender
• Trap receiver
These utilities are described in Chapter 4.
Overview 1–3

Overview
1.2 Request Handling
The network management station sends an SNMP request to the master
agent running on the host, using port 161. An SNMP request is made using
one of the following commands:
• Get
• GetNext
• GetBulk
• Set
Note
TCP/IP Services does not support the standard SNMP Inform command.
The request specifies the object identifer (OID) of the data to be accessed.
For information about formatting get and set requests, refer to Section 5.2.
Request formats are specified in RFC 1905.
2. The master agent sends the request to the subagent that registered the
subtree containing the OID.
The subagent receives communications from the master agent over the socket
that was assigned when the subagent registered the subtree.
3. The appropriate subagent processes the request.
4. The subagent sends the response message to the master agent using the port
that was assigned when the subagent registered the MIB.
When they are idle, subagents periodically send a message to port 705 to ensure
that the master agent is still running. In Figure 1–2, subagent 1 is sending the
esnmp_are_you_there message.
A
trap is generated by the subagent and sent to the client. In Figure 1–2,
subagent nis generating a trap for the trap client on NMS 2.
The trap and esnmp_are_you_there routines are described in Section 5.1.
1.3 TCP/IP Services Components for SNMP
Table 1–1 lists the components of SNMP and the command procedures for
managing SNMP that are supplied with TCP/IP Services.
Table 1–1 SNMP Component Files
File Location Function
TCPIP$ESNMP_SERVER.EXE SYS$SYSTEM Master agent image.
TCPIP$OS_MIBS.EXE SYS$SYSTEM MIB II subagent image.
TCPIP$HR_MIB.EXE SYS$SYSTEM Host Resources MIB
subagent image.
TCPIP$SNMP_REQUEST.EXE SYS$SYSTEM Simple MIB browser.
TCPIP$SNMP_TRAPSND.EXE SYS$SYSTEM Utility for sending trap
messages.
(continued on next page)
1–4 Overview

Overview
1.3 TCP/IP Services Components for SNMP
Table 1–1 (Cont.) SNMP Component Files
File Location Function
TCPIP$SNMP_TRAPRCV.EXE SYS$SYSTEM Utility for receiving trap
messages.
TCPIP$ESNMP_SHR.EXE SYS$SHARE Image file containing eSNMP
application programming
interface (API) routines.
TCPIP$SNMP_STARTUP.COM SYS$STARTUP Command procedure
that installs master and
subagent images and runs
TCPIP$SNMP_RUN.COM.
TCPIP$SNMP_SYSTARTUP.COM SYS$STARTUP Command procedure
initiated by TCPIP$SNMP_
STARTUP.COM. Provided for
site-specific customizations,
such as parameter settings.
TCPIP$SNMP_RUN.COM TCPIP$SYSTEM Command procedure that
starts the master agent and
subagents.
TCPIP$SNMP_SHUTDOWN.COM SYS$STARTUP Command procedure that
stops the master agent and
subagents.
TCPIP$SNMP_SYSHUTDOWN.COM SYS$STARTUP Command procedure
initiated by TCPIP$SNMP_
SHUTDOWN.COM.
Provided for site-specific
customization, such as
parameter settings.
TCPIP$EXTENSION_MIB_STARTUP.COM SYS$SYSDEVICE:[TCPIP$SNMP]
Command procedure
invoked by TCPIP$SNMP_
SYSTARTUP.COM to start
custom subagents.
TCPIP$EXTENSION_MIB_
SHUTDOWN.COM SYS$SYSDEVICE:[TCPIP$SNMP]
Command procedure
invoked by TCPIP$SNMP_
SYSHUTDOWN.COM to
stop custom subagents.
TCPIP$EXTENSION_MIB_RUN.COM SYS$SYSDEVICE:[TCPIP$SNMP]
Command procedure
invoked by TCPIP$SNMP_
SYSTARTUP.COM when the
service is enabled and starts
detached processes to run
subagents.
1.4 Writing an eSNMP Subagent
Table 1–2 lists the files that are available to help you develop MIBs and
subagents. Except where noted, the files are located in the directory pointed to by
TCPIP$SNMP_EXAMPLES.
Overview 1–5

Overview
1.4 Writing an eSNMP Subagent
Table 1–2 Files for Building a Subagent
File Description
ESNMP.H Header file used to create a subagent. Located in
TCPIP$ESNMP.
GAWK.EXE Interpreter for MIB converter.
MIB-CONVERTER.AWK A UNIX based
awk shell script that takes a MIB
definition in ASN.1 notation and converts it to an
.MY file.
RFC1213.MY MIB II definitions.
RFC1231.MY IEEE 802.5 Token Ring MIB definitions.
RFC1285.MY FDDI MIB definitions.
RFC1442.MY SNMP Version 2 Structure of Management
Information (SMI) definitions.
SNMP-SMI.MY SNMP Version 2 SMI definitions from RFC 1902
(replaces RFC 1442).
SNMP-TC.MY SNMP Version 2 SMI definitions from RFC 1903
(replaces RFC 1443).
V2-TC.MY SNMP Version 2 SMI definitions from RFC 1903
(superset of those in SNMP-TC.MY).
TCPIP$BUILD_CHESS.COM Command file that builds the sample chess
subagent.
TCPIP$CHESS_SUBAGENT.OPT Options file for use in building the sample chess
subagent.
*.C and *.H Source code for chess example. Contains detailed
documentation that explains how the code
functions.
TCPIP$CHESS_SUBAGENT.EXE Functioning chess example image.
TCPIP$ESNMP.OLB Object library file containing routines used to
create a subagent. Located in the directory
pointed to by TCPIP$SNMP.
TCPIP$ESNMP_SHR.EXE Shareable image containing routines used to
create a subagent. Located in the directory
pointed to by SYS$SHARE.
UCX$ESNMP_SHR.EXE Copy of TCPIP$ESNMP_SHR.EXE, provided for
compatibility with existing customer subagents
linked under TCP/IP Services V4.x. Located in
the directory pointed to by SYS$SHARE.
TCPIP$MIBCOMP.EXE
TCPIP$MOSY.EXE
TCPIP$SNMPI.EXE
Images associated with the MIB compiler.
Located in SYS$SYSTEM.
For information about building a subagent on an OpenVMS system, see
Chapter 3.
1.5 The eSNMP API
The Compaq TCP/IP Services for OpenVMS implementation of the eSNMP
architecture includes an API that provides programmers with many eSNMP
routines they would otherwise have to develop themselves.
The eSNMP API includes interface routines, method routines, and support
routines.
1–6 Overview

Overview
1.5 The eSNMP API
Interface routines handle the basic subagent operations, such as:
• Subagent initialization and termination
• Registration
• Polling of the master agent
• Trap sending
• UNIX system time conversion
• Adding and removing subagent capabilities registered with the master agent
The support routines allow the subagent to manipulate the data in the response
to the request, and include the following:
• Basic protocol data unit (PDU) handling
• Authentication handling
• Octet string handling
• Variable binding (
VARBIND ) handling
• Object identifier (OID) handling
• Buffer handling
Chapter 5 describes the API routines in more detail.
To create a subagent, the programmer must provide modules to implement the
method routines, as described in Chapter 3.
1.5.1 The SNMP Utilities
To provide quick access to information in the MIBs, and to test SNMP operation,
TCP/IP Services provides the following utilities:
• TCPIP$SNMP_REQUEST.EXE, a MIB browser that allows you to retrieve
and update objects from the MIBs.
• TCPIP$SNMP_TRPSND.EXE, a trap sender that generates traps (messages
that require no response).
• TCPIP$SNMP_TRPRCV.EXE, a trap receiver (or ‘‘listener’’) that is used to
detect trap messages.
For information about using the SNMP utilities, see Chapter 4.
1.6 The MIB Compiler
The MIB compiler processes the statements in an ASN.1 file and generates
modules that are used by the developer to create subagent routines. For every
ASN.1 input file that is processed using the MIB compiler, two output files, a
subtree_TBL.H file and a subtree_TBL.C file, are generated, where subtree is the
name from the original MIB definition file (for example, chess). The output files
are described in more detail in Chapter 3.
The subtree_TBL.H file is a header file that contains the following:
• A declaration of the subtree structure
• Index definitions for each MIB variable in the subtree
• Enumeration definitions for MIB variables with enumerated values
• MIB group data structure definitions
Overview 1–7

Overview
1.6 The MIB Compiler
• Method routine function prototypes
The subtree_TBL.C file is an object file that contains the following:
• An array of integers representing the OIDs for each MIB variable
• An array of OBJECT structures
• An initialized SUBTREE structure
1.7 SNMP Versions
The extensible SNMP software supports SNMP Version 2, based on RFCs 1901
through 1908, including:
• The SNMP Version 2 structure of management information for SNMP Version
2 (SMI Version 2) and textual conventions.
• The eSNMP library API (SNMP Version 2), variable binding exceptions, and
error codes.
• SNMP Version 1 and SNMP Version 2 requests. Both versions are handled
by the master agent. SNMP Version 2 specific information from the subagent
is mapped, when necessary, to SNMP Version 1 adherent data (according
to RFC 2089). For example, if a management application makes a request
using SNMP Version 1 PDUs, the master agent replies using SNMP Version
1 PDUs, mapping any SNMP Version 2 SMI items received from subagents.
In most cases, subagents created with a previous version of the eSNMP
API do not require any code changes and do not have to be recompiled. The
circumstances under which recoding or recompiling are required are described
in Section 1.7.1.
1.7.1 Using Existing (SNMP Version 1) MIB Modules
Existing SNMP Version 1 MIB subagent executable files should be compatible
with the current SNMP Version 2 master agent without the need to recompile
and relink, with the following exceptions:
• Any program that relies on TCP/IP Services Version 4.1 or 4.2 kernel data
structures or access functions may run but may not return valid data. Such
programs should be rewritten.
• Programs linked against UCX$ACCESS_SHR.EXE, UCX$IPC_SHR.EXE, or
other older shareable images (except for UCX$ESNMP_SHR.EXE, which is
described in the next list item) may not run even when relinked. You may
need to either rewrite or both rewrite and recompile such programs. Note
that the Chess example image (UCX$CHESS_SUBAGENT.EXE) has been
updated and renamed TCPIP$CHESS_SUBAGENT.EXE.
• For programs linked against certain versions of UCX$ESNMP_SHR.EXE:
– Images associated with the following versions of TCP/IP Services will run
correctly without the need to relink them:
Version 4.1 ECO 9 and later
Version 4.2 ECO 1 and later
The installation of TCP/IP Services provides a backward-compatible
version of UCX$ESNMP_SHR.EXE in the SYS$SHARE directory. Do not
delete this image.
1–8 Overview