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) |
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:
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:
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 Integrity
!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 from the below table:
$ 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(int trap-alert-routine, unsigned long time-zero-reference, unsigned long *trap-event, AsnOBJID *supported-view)
This routine returns TRUE if the subagent was successfully initialized; FALSE if initialization failed.
trap-alert-routine
Address of the routine the subagent should call when it is ready to send a trap.
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).
trap-event
This parameter is reserved for future use.
supported-view
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(AsnOBJID *supported-view);
Returns TRUE if returning the first or next MIB subtree, FALSE if all of the MIB subtrees have been passed back.
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);
}
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 (unsigned char *request-type, RFC1157VarBindList var-bind-list, int error-status, int error-index);
Returns TRUE if the operation successfully complete, FALSE if the operation could not be carried out by the subagent; use error-status and error-index to provide more information.
request-type
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
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. (The VarBindList structure is defined in RFC 1157 - see SNMP_SUBAGENT.H.)
error-status
Status of a failed operation. See SNMP_COMMON.H for error value names.
error-index
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 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(AsnOBJID *enterprise, int generic-trap, int *specific-trap, int *time-stamp, RFC1157VarBindList var-bind-list);
Returns TRUE if there are more traps to be generated; FALSE if there are no more traps to be generated.
enterprise
The prefix of the MIB for the enterprise sending the trap. (See the SNMP_SUBAGENT.H file.)
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.