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.
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
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.
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 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
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 Debugging Mask Values :
$ DEFINE SYSTEM TCPWARE_SNMP_DEBUG mask
|
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) |
The following pages include the subroutine descriptions.
Initializes the SNMP subagent and registers the subagent in the SNMPD agent. The subagent calls this routine at startup.
status = SnmpExtensionInit (trap-alert-routine, time-zero-reference, trap-event, supported-view)
|
TRUE |
Subagent initialized successfully |
|
FALSE |
Subagent initialization failed |
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.
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.
status = SnmpExtentionInitEx (supported-view)
|
TRUE |
Returning first or next MIB subtree |
|
FALSE |
All MIB subtrees were passed back |
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.
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);
}
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.
status = SnmpExtensionQuery (request-type, var-bind-list, error-status, error-index)
|
TRUE |
Operation successfully completed |
|
FALSE |
Operation could not be carried out by the subagent; use error-status and error-index to provide more information |
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.
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.
status = SnmpExtensionTrap (enterprise, generic-trap, specific-trap, time-stamp, var-bind-list)
|
TRUE |
More traps to be generated |
|
FALSE |
No more traps to be generated |
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.