## TCPware V5.7 Programmer's Guide

- Introduction
- Requirements
- Linking the Extension Agent Image
- Installing the Extension Agent Image
- Sample Code and Data Structures
- Debugging Code
- Subroutine Reference

Chapter 10

SNMP Extendible Agent API Routines

# Introduction

This chapter is for application programmers. It describes the Application Programming Interface (API) routines required for an application program to export private Management Information Bases (MIBs) using the TCPware SNMP agent.

To be able to use your private Management Information Base (MIB) with TCPware's SNMP agent, develop a shareable image that exports the following application programming interface routines, in addition to routines you may need to access the MIB variables:

SnmpExtensionInit | Called by the SNMPD agent after startup to initialize the MIB subagent
SnmpExtensionInitEx | Registers multiple subtrees with the subagent (called by the SNMPD agent at startup only if implemented)
SnmpExtensionQuery | Completes the MIB subagent query (called by the SNMPD agent to handle a get, getnext, or set request)
SnmpExtensionTrap | Sends an enterprise-specific trap (called by the SNMPD agent when the subagent alerts the agent that a trap needs to be sent)

Note! The routine names used in this API are taken from the Microsoft SNMP Extension Agent for Windows NT.

The SNMP shareable images need to be configured for the SNMP agent to interact with them.

See the Configuration chapter of the Installation & Configuration Guide for details on configuring the SNMP agent.

SNMP subagent developers should use the include file SNMP_COMMON.H found in the TCPWARE_INCLUDE directory. This file defines the data structures the API uses.

For details on TCPware's SNMP agent, see Chapter 10, in the Management Guide.

# Requirements

You require the following before using the SNMP extendible agent API routines:

• Working knowledge of SNMP; specifically the following RFCs:

– RFC 1155, Structure and Identification of Management Information for TCP/IP-based Internets

– RFC 1157, A Simple Network Management Protocol (SNMP)

– RFC 1213, Management Information Base for Network Management of TCP/IP-based internets: MIB-II

• Working knowledge of OpenVMS shareable images

# Linking the Extension Agent Image

To link the Extension Agent Image you need to create an option file:

VAX

!Note: Exclude SnmpExtensionInitEx if it is not needed.
!See the definition of this routine.
!
UNIVERSAL=SnmpExtensionInit, -
SnmpExtensionQuery, -
SnmpExtensionTrap, -
SnmpExtensionInitEx
SYS$SHARE:VAXCRTL/SHARE
!
!List your object/library files here

Alpha and I64

!Note: Exclude SnmpExtensionInitEx if it is not needed.
!See the definition of this routine.
!
SYMBOL_VECTOR=( SnmpExtensionInit=PROCEDURE, -
SnmpExtensionQuery=PROCEDURE, -
SnmpExtensionTrap=PROCEDURE, -
SnmpExtensionInitEx=PROCEDURE)
!
!List your object/library files here

Your link statement should then look like this:

$ LINK /SHARE=image-name option-file/OPT

image-name is the name of the shareable image you want to build, and option-file is the option file mentioned above.

# Installing the Extension Agent Image

You should copy the shareable image you build for your SNMP subagent to the SYS$SHARE directory.

CAUTION! Since the shareable image is loaded into the same process address space as the SNMPD server, an access violation by the subagent shareable image can crash the server application. Ensure the integrity of your shareable image by testing it thoroughly. Shareable image errors can also corrupt the server's memory space or may result in memory or resource leaks.

# Sample Code and Data Structures

Sample code is provided in the SYS$COMMON:[TCPWARE.EXAMPLES] directory in the files SNMP_SUBAGENT.C and SNMP_SUBAGENT.H.

SNMP_SUBAGENT.H also defines the following data structures found in the subroutines:

• AsnOBJID

RFC1157VarBindList

# Debugging Code

SNMP subagent developers can use a debug logical, TCPWARE_SNMP_DEBUG to set certain debug masks. Define the logical as follows and use the mask values in Table 10-1:

$ DEFINE SYSTEM TCPWARE_SNMP_DEBUG mask

Table 10-1 Debugging Mask Values (Continued)

Mask Value | Description
0010 | Raw SNMP input
0020 | Raw SNMP output
0040 | ASN.1 encoded message input
0080 | ASN.1 encoded message output
1000 | SNMP Subagent Developer debug mask (prints events and statuses)

# Subroutine Reference

The following pages include the subroutine descriptions.

SnmpExtensionInit

Initializes the SNMP subagent and registers the subagent in the SNMPD agent. The subagent calls this routine at startup.

Format

status = SnmpExtensionInit (trap-alert-routine, time-zero-reference, trap-event, supported-view)

Return Values

TRUE | Subagent initialized successfully
FALSE | Subagent initialization failed

Arguments

trap-alert-routine

OpenVMS usage: | address
type: | integer
access: | read only
mechanism: | by value

Address of the routine the subagent should call when it is ready to send a trap.

time-zero-reference

OpenVMS usage: | unsigned long
type: | longword (unsigned)
access: | read only
mechanism: | by value

Time reference the SNMP agent provides, in hundredths of a second. Use C routines time() and difftime() to calculate MIB uptime (in hundredths of a second).

trap-event

OpenVMS usage: | unused
type: | longword (unsigned)
access: | write only
mechanism: | by reference

This parameter is reserved for future use.

supported-view

OpenVMS usage: | object identifier
type: | AsnOBJID (see the SNMP_SUBAGENT.H file)
access: | write only
mechanism: | by reference

Prefix of the MIB tree the subagent supports.

SnmpExtensionInitEx

Registers multiple MIB subtrees with agent.

This routine is called multiple times, once for each MIB subtree that needs to be registered. If the routine passes back the first or next MIB subtree, return with TRUE. If all the MIB subtrees were passed back, return with FALSE.

Note! Only implement this routine if you have multiple MIB subtrees in your extendible agent. The TCPware SNMP agent executes this routine if it exists and overwrites MIB information set by SnmpExtensionInit.

Format

status = SnmpExtentionInitEx (supported-view)

Return Values

TRUE | Returning first or next MIB subtree
FALSE | All MIB subtrees were passed back

Arguments

supported-view

OpenVMS usage: | object identifier
type: | AsnOBJID (see the SNMP_SUBAGENT.H file)
access: | write only
mechanism: | by reference

Prefix of the MIB tree the subagent supports.

Example

int SnmpExtensionInitEx (AsnOBJID *supportedView)
{
int view1[] = {1, 3, 6, 1, 4, 1, 12, 2, 1 };
int view2[] = {1, 3, 6, 1, 4, 1, 12, 2, 2 };
int view3[] = {1, 3, 6, 1, 4, 1, 12, 2, 5 };
static int whichView = 0;
switch ( whichView++) {
case 0:
supportedView->idLength = 9;
memcpy (supportedView->ids, view1, 9* sizeof (int));
break;
case 1:
supportedView->idLength = 9;
memcpy (supportedView->ids, view2, 9* sizeof (int));
break;
case 2:
supportedView->idLength = 9;
memcpy (supportedView->ids, view3, 9* sizeof (int));
break;
default:
return (0);
}
return (1);
}

SnmpExtensionQuery

Queries the SNMP subagent to get or set a variable in the MIB tree served by the subagent. This routine is called by the SNMPD agent to handle a get, getnext, or set request.

Format

status = SnmpExtensionQuery (request-type, var-bind-list, error-status, error-index)

Return Values

TRUE | Operation successfully completed
FALSE | Operation could not be carried out by the subagent; use error-status and error-index to provide more information

Arguments

request-type

OpenVMS usage: | byte
type: | unsigned char
access: | read only
mechanism: | by value

Identifies the type of request GET, SET, or GET NEXT. These values are defined in TCPWARE_ROOT:[TCPWARE.INCLUDE]SNMP_COMMON.H

var-bind-list

OpenVMS usage: | user defined
type: | RFC1157VarBindList (see the SNMP_SUBAGENT.H file)
access: | read-write
mechanism: | by value

The list of name-value pairs used in the request. For a GET request the value is filled by the subagent and for a SET request, the value is be used to change the current variable value in the subagent.

error-status

OpenVMS usage: | integer
type: | integer
access: | write only
mechanism: | by reference

Status of a failed operation. See SNMP_COMMON.H for error value names.

error-index

OpenVMS usage: | integer
type: | integer
access: | write only
mechanism: | by reference

The index of the variable in the variable binding list for which the operation failed.

SnmpExtensionTrap

Sends a trap from the subagent. If the subagent wants to send a trap, it must first call the trap-alert-routine (see the SnmpExtensionInit routine). The trap-alert-routine should be called with two parameters (oid ids, oid idlength). For example:

If the Process Software’s DNS process wants to send trap information to all the communities that are interested then the DNS server must be running and the objectids passed are 1, 3, 6, 1, 4, 1, 105, 1, 2, 1, 1, 1, 3, 1, and the length of 14.

• 1,3,6,1,4,1 is the default prefix

• 105 is the enterprise id for Process Software

• 1,2,1,1,1 are the Mib object ids for the DNS process

• 3,1 are the objectids for DNSUpTrap

The SNMP agent trap-alert-routine creates a table of all received trap mibs. For each of these entries, the agent then calls the subagent's SnmpExtensionTrap routine when it is ready to send the trap. Note that the SNMP agent calls the subagent from inside the trap-alert-routine.

Format

status = SnmpExtensionTrap (enterprise, generic-trap, specific-trap, time-stamp, var-bind-list)

Return Values

TRUE | More traps to be generated
FALSE | No more traps to be generated

Arguments

enterprise

OpenVMS usage: | array of object identifiers
type: | AsnOBJID (see the SNMP_SUBAGENT.H file)
access: | write only
mechanism: | by reference

The prefix of the MIB for the enterprise sending the trap.

generic-trap

OpenVMS usage: | integer
type: | integer
access: | write only
mechanism: | by reference

The generic enterprise trap id(6).

specific-trap

OpenVMS usage: | integer
type: | integer
access: | write only
mechanism: | by reference

The enterprise-specific trap number.

Note! Since an enterprise can have many traps, the combination of enterprise id, generic trap, and specific trap should give a unique identification for a trap.

time-stamp

OpenVMS usage: | integer
type: | integer (timeticks)
access: | write only
mechanism: | by reference

The time at which the trap was generated.

var-bind-list

OpenVMS usage: | user defined
type: | RFC1157VarBindList (see the SNMP_SUBAGENT.H file)
access: | read-write
mechanism: | by value

The list of name-value pairs. This list contains name and value of the MIB variable for which the trap is generated.