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 MultiNet SNMP agent.
To be able to use your private Management Information Base (MIB) with MultiNet'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 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 set) |
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 Configuring MultiNet SNMP Agents chapter of the MultiNet for OpenVMS Installation and Administrator’s Guide for details on configuring the SNMP agent.
SNMP subagent developers should use the include file SNMP_COMMON.H. found in the MULTINET_COMMON_ROOT:[MULTINET.INCLUDE] directory. This file defines the data structures the API uses.
For details on MultiNet's SNMP agent, see Configuring MultiNet SNMP Agents in the MultiNet for OpenVMS Installation and Administrator’s Guide.
You require the following before using the SNMP extensible 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. The two examples below are for VAX systems and Alpha Systems, respectively.
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
!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.
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.
SNMP subagent developers can use a debug logical, MULTINET_SNMP_DEBUG, to set certain debug masks. Define the logical as follows and use the mask values in Debugging Mask Values :
$ DEFINE MULTINET_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.
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.
trap-event
|
OpenVMS usage: |
unsigned long |
|
type: |
longword (unsigned) |
|
access: |
write only |
|
mechanism: |
by reference |
Currently unused.
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).
supported-view
|
OpenVMS usage: |
object identifier |
|
type: |
AsnOBJID (see the SNMP_COMMON.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 MultiNet 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_COMMON.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);
}
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; |
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.
var-bind-list
|
OpenVMS usage: |
user defined |
|
type: |
RFC1157VarBindList (see the SNMP_COMMON.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.
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 (objids, 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! 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_COMMON.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_COMMON.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.