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) |
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 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 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:
o RFC 1155, Structure and Identification of Management Information for TCP/IP-based Internets
o RFC 1157, A Simple Network Management Protocol (SNMP)
o 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/Itanium systems, respectively.
!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
!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 the below table:
$ 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.
int SnmpExtensionInit (trap-alert-routine, time-zero-reference, trap-event, supported-view);
trap-alert-routine
Address of the routine the subagent should call when it is ready to send a trap.
trap-event
Currently unused.
time-zero-reference
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
Prefix of the MIB tree the subagent supports.
· TRUE – Subagent initialized successfully
· FALSE - Subagent initialization failed
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.
|
int SnmpExtentionInitEx(supported-view);
supported-view
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);
}
· TRUE – Returning first or next MIB subtree
· FALSE - All MIB subtrees were passed back
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.
int SnmpExtensionQuery (request-type, var-bind-list, error-status, error-index);
request-type
Identifies the type of request: GET, SET, or GET NEXT.
var-bind-list
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
Status of a failed operation.
error-index
The index of the variable in the variable binding list for which the operation failed.
· TRUE - Operation successfully completed
· FALSE - Operation could not be carried out by the subagent; use error-status and error-index to provide more information
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 DNS process wants to send trap information to all the communities that are interested then the DNS server must be running and the object IDs 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 object IDs 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.
|
int SnmpExtensionTrap (enterprise, generic-trap, specific-trap, time-stamp, var-bind-list);
enterprise
The prefix of the MIB for the enterprise sending the trap.
generic-trap
The generic enterprise trap ID.
specific-trap
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
The time at which the trap was generated.
var-bind-list
The list of name-value pairs. This list contains name and value of the MIB variable for which the trap is generated.
· TRUE - More traps to be generated
· FALSE - No more traps to be generated