Compaq TCP/IP Services for OpenVMS
SNMP Programming and Reference
Previous Contents Index

Note that the return value indicates only the initiation of the request. The actual status returned in the master agent's response will be returned in a subsequent call to the esnmp_poll routine in the state field.

Example


#include <esnmp.h> 
#define RESPONSE_TIMEOUT        0     /* use the default time set 
                                         in esnmp_init message */ 
#define REGISTRATION_PRIORITY   10    /* priority at which the MIB 
                                         subtree will register */ 
#define RANGE_SUBID             7     /* the identifier position in 
                                         oid->elements just after mib-2 */ 
#define RANGE_UPPER_BOUND       8     /* the identifier for egp, 
                                         under mib-2 */ 
int status 
extern SUBTREE ip_subtree; 
static ESNMP_REG esnmp_reg_for_ip2egp;  /* retain this structure for 
                                           a subsequent call to 
                                           esnmp_unregister2 */ 
/* 
 *  initialize the ESNMP_REG structure 
 */ 
memset(&esnmp_reg_for_ip2egp, 0, sizeof(ESNMP_REG)); 
esnmp_reg_for_ip2egp.subtree           = &ip_subtree; 
esnmp_reg_for_ip2egp.priority          = REGISTRATION_PRIORITY; 
esnmp_reg_for_ip2egp.timeout           = RESPONSE_TIMEOUT; 
esnmp_reg_for_ip2egp.range_subid       = RANGE_SUBID; 
esnmp_reg_for_ip2egp.range_upper_bound = RANGE_UPPER_BOUND; 
 
status = esnmp_register2( &esnmp_reg_for_ip2egp ); 
if (status != ESNMP_LIB_OK) { 
    printf("Could not queue the 'ipRouteEntry' \n"); 
    printf("subtree for registration\n"); 
}

esnmp_unregister2

Cancels registration of a MIB subtree previously established with the master agent. Use this routine only when the MIB subtree was registered using the esnmp_register2 routine.

Format

int esnmp_unregister2 ( ESNMP_REG *reg ) ;

Arguments

reg

A pointer to the ESNMP_REG structure that was used when the esnmp_register2 routine was called.

Description

This routine can be called by the application code to tell the eSNMP subagent to no longer process requests for variables in this MIB subtree. You can later reregister a MIB subtree, if needed, by calling the esnmp_register2 routine.

Return Values

ESNMP_LIB_OK The routine completed successfully.
ESNMP_LIB_BAD_REG The MIB subtree was not registered.
ESNMP_LIB_LOST_CONNECTION The request to unregister the MIB subtree could not be sent. You should restart the protocol.

Example


#include <esnmp.h> 
int status 
 
extern ESNMP_REG esnmp_reg_for_ip2egp; 
 
status = esnmp_unregister2( &esnmp_reg_for_ip2egp ); 
 
switch(status) { 
   case ESNMP_LIB_OK: 
   printf("The esnmp_unregister2 routine completed successfully.\n"); 
   break; 
 
   case ESNMP_LIB_BAD_REG: 
   printf("The MIB subtree was not registered.\n"); 
   break; 
 
   case ESNMP_LIB_LOST_CONNECTION: 
   printf("%s%s%s\n", "The request to unregister the ", 
                      "MIB subtree could not be sent.  ", 
                      "You should restart the protocol.\n"); 
   break; 
}

esnmp_capabilities

Adds a subagent's capabilities to the master agent's sysORTable . The sysORTable is a conceptual table that contains an agent's object resources, and is described in RFC 1907.

Format

void esnmp_capabilities ( OID *agent_cap_id,
char *agent_cap_descr ) ;

Arguments

agent_cap_id

A pointer to an object identifier that represents an authoritative agent capabilities identifier. This value is used for the sysORID object in the sysORTable for the managed node.

agent_cap_descr

A pointer to a null-terminated character string describing agent_cap_id . This value is used for the sysORDescr object in the sysORTable for the managed node.

Description

This routine is called at any point after initializing eSNMP by a call to the esnmp_init routine.

esnmp_uncapabilities

Removes a subagent's capabilities from the master agent's sysORTable .

Format

void esnmp_uncapabilities ( OID *agent_cap_id ) ;

Arguments

agent_cap_id

A pointer to an object identifier that represents an authoritative agent capabilities identifier. This value is used for the sysORID object in the sysORTable for the managed node.

Description

This routine is called if a subagent alters its capabilities dynamically. When a logical connection for a subagent is closed, the master agent automatically removes the related entries in sysORTable .

esnmp_poll

Processes a pending message that was sent by the master agent.

Format

int esnmp_poll ( )

Description

This routine is called after the select() call has indicated data is ready on the eSNMP socket. (This socket was returned from the call to the esnmp_init routine.)

If a received message indicates a problem, an entry is made to the SNMP log file and an error status is returned.

If the received message is a request for SNMP data, the object table is checked and the appropriate method routines are called, as defined by the developer of the subagent.

Return Values

ESNMP_LIB_OK The esnmp_poll routine completed successfully.
ESNMP_LIB_BAD_REG The master agent failed in a previous registration attempt. See the log file.
ESNMP_LIB_DUPLICATE A duplicate subagent identifier has already been received by the master agent.
ESNMP_LIB_NO_CONNECTION The master agent's OPEN request failed. Restart the connection after a delay. See the log file.
ESNMP_LIB_CLOSE A CLOSE message was received.
ESNMP_LIB_NOTOK An eSNMP protocol error occurred and the packet was discarded.
ESNMP_LIB_LOST_CONNECTION Communication with the master agent was lost. Restart the connection.

esnmp_are_you_there

Requests the master agent to report immediately that it is up and functioning.

Format

int esnmp_are_you_there ( ) ;

Description

The esnmp_are_you_there routine does not block waiting for a response. The routine is intended to cause the master agent to reply immediately. The response should be processed by calling the esnmp_poll routine.

If a response is not received within the timeout period, the application code should restart the eSNMP protocol by calling the esnmp_init routine. No timers are maintained by the eSNMP library.

Return Values

ESNMP_LIB_OK The request was sent.
ESNMP_LIB_LOST_CONNECTION The request cannot be sent because the master agent is down.

esnmp_trap

Sends a trap message to the master agent.

Format

int esnmp_trap ( int *generic_trap,
int specific_trap,
char *enterprise,
varbind *vb ) 2 ;

Arguments

generic_trap

A generic trap code. Set this argument value to 0 (zero) for SNMPv2 traps.

specific_trap

A specific trap code. Set this argument value to 0 (zero) for SNMPv2 traps.

enterprise

An enterprise OID string in dot notation. Set to the object identifier defined by the NOTIFICATION-TYPE macro in the defining MIB specification. This value is passed as the value of SnmpTrapOID.0 in the SNMPv2-Trap-PDU.

vb

A VARBIND list of data (a null pointer indicates no data).

Description

This function can be called any time. If the master agent is not running, traps are queued and sent when communication is possible.

The trap message is actually sent to the master agent after it responds to the esnmp_init routine. This occurs with every API call and for most esnmp_register routines. The quickest process to send traps to the master agent is to call the esnmp_init, esnmp_poll , and esnmp_trap routines.

The master agent formats the trap into an SNMP trap message and sends it to management stations based on its current configuration.

The master agent does not respond to the content of the trap. However, the master agent does return a value that indicates whether the trap was received successfully.

Return Values

ESNMP_LIB_OK The routine has completed successfully.
ESNMP_LIB_LOST_CONNECTION Could not send the trap message to master agent.
ESNMP_LIB_NOTOK Something failed and the message could not be generated.

esnmp_term

Sends a close message to the master agent and shuts down the subagent.

Format

void esnmp_term (void) ;

Description

Subagents must call this routine when terminating so that the master agent can update its MIB registry quickly and so that resources used by eSNMP on behalf of the subagent can be released.

Return Values

ESNMP_LIB_OK The esnmp_term routine always returns ESNMP_LIB_OK, even if the packet could not be sent.

esnmp_sysuptime

Converts UNIX system time obtained from gettimeofday into a value with the same time base as sysUpTime .

Format

unsigned int esnmp_sysuptime ( struct timeval *timestamp ) ;

Argument

timestamp

A pointer to struct timeval , which contains a value obtained from the gettimeofday system call. The structure is defined in include/sys/time.h .

A null pointer means return the current sysUpTime .

Description

This routine provides a mechanism to convert UNIX timestamps into eSNMP TimeTicks . The function returns the value that sysUpTime held when the passed timestamp was now .

This routine can be used as a TimeTicks data type (the time since the eSNMP master agent started) in hundredths of a second. The time base is obtained from the master agent in response to esnmp_init , so calls to this function before that time will not be accurate.

Return Values

0 An error occurred because a gettimeofday function failed. Otherwise, timestamp contains the time in hundredths of a second since the master agent started.

Example


 
#include <sys/time.h> 
#include <esnmp.h> 
struct timeval timestamp; 
 
gettimeofday(&timestamp, NULL); 
   .
   .
   .
o_integer(vb, object, esnmp_sysuptime(&timestamp));

5.2 Method Routines

SNMP requests may contain many encoded MIB variables. The libsnmp code executing in a subagent matches each VariableBinding with an object table entry. The object table's method routine is then called. Therefore, a method routine is called to service a single MIB variable. Since a single method routine can handle a number of MIB variables, the same method routine may be called several times during a single SNMP request.

The method routine calling interface contains the following functions:

*_get Routine

The *_get routine is a method routine for the specified MIB item, which is typically a MIB group (for example, system in MIB II) or a table entry (for example, ifEntry in MIB II).

Format

int mib-group_get ( METHOD *method ) ;

Arguments

method

A pointer to a METHOD structure that contains the following fields:
Field Name Description
action One of ESNMP_ACT_GET, ESNMP_ACT_GETNEXT, or ESNMP_ACT_GETBULK.
serial_num An integer number that is unique to this SNMP request. Each method routine called while servicing a single SNMP request receives the same value of serial_num. New SNMP requests are indicated by a new value of serial_num.
repeat_cnt Used for GetBulk only. This value indicates the current iteration number of a repeating VARBIND. This number increments from 1 to max_repetitions and is 0 (zero) for nonrepeating VARBIND structures.
max_repetitions The maximum number of repetitions to perform. Used for GetBulk only. This will be 0 (zero) for nonrepeating VARBIND structures. You can optimize subsequent processing by knowing the maximum number repeat calls will be made.
varbind A pointer to the VARBIND structure for which you must fill in the OID and data fields. Upon entry of the method routine, the method->varbind->name field is the OID that was requested.

Upon exit of the method routine, the method->varbind field contains the requested data, and the method->varbind->name field is updated to reflect the actual instance OID for the returned VARBIND structure.

The support routines ( o_integer , o_string , o_oid , and o_octet ) are generally used to load data. The libsnmp instance2oid routine is used to update the OID in the method->varbind->name field.

object A pointer to the object table entry for the MIB variable being referenced. The method->object->object_index field is this object's unique index within the object table (useful when one method routine services many objects).

The method->object->oid field is the OID defined for this object in the MIB. The instance requested is derived by comparing this OID with the OID in the request found in the method->varbind->name field. The oid2instance function is useful for this.

Description

These types of routines call whatever routine is specified for Get operations in the object table identified by the registered subtree.

This function is pointed to by some number of elements of the subagent object table. When a request arrives for an object, its method routine is called. The *_get method routine is called in response to a Get request.

Return Values

ESNMP_MTHD_noError The routine completed successfully.
ESNMP_MTHD_noSuchObject The requested object cannot be returned or does not exist.
ESNMP_MTHD_noSuchInstance The requested instance of an object cannot be returned or does not exist.
ESNMP_MTHD_genErr A general processing error.

*_set Routine

The *_set method routine for a specified MIB item, which is typically a MIB group (for example, system in MIB II) or a table entry (for example, ifEntry in MIB II).

Format

int mib-group_set ( METHOD *method ) ;

Arguments

method

A pointer to a METHOD structure that contains the following fields:
Field Name Description
action One of ESNMP_ACT_SET, ESNMP_ACT_UNDO, or ESNMP_ACT_CLEANUP.
serial_num An integer number that is unique to this SNMP request. Each method routine called while servicing a single SNMP request receives the same value as serial_num. New SNMP requests are indicated by a new value of serial_num.
varbind A pointer to the VARBIND structure that contains the MIB variable's supplied data value and name (OID). The instance information has already been extracted from the OID and placed in the method->row->instance field.
object A pointer to the object table entry for the MIB variable being referenced. The method->object->object-index field is this object's unique index within the object table (useful when one method routine services many objects).

The method->object->oid field is the OID defined for this object in the MIB.

flags A read-only integer bitmask set by the libesnmp routine. If set, the ESNMP_FIRST_IN_ROW bit indicates that this call is the first object to be set in the row. If set, the ESNMP_LAST_IN_ROW bit indicates that this call is the last object to be set in the row. Only METHOD structures with the ESNMP_LAST_IN_ROW bit set are passed to the method routines for commit, undo, and cleanup phases.
row A pointer to a ROW_CONTEXT structure (defined in the ESNMP.H header file). All Set requests to the method routine that refer to the same group and that have the same instance number will be presented with the same row structure. The method routines can accumulate information in the row structures during Set requests for use during the commit and undo phases. The accumulated data can be released by the method routines during the cleanup phase.

The ROW_CONTEXT structure contains the following fields:
instance An address of an array containing the instance OID for this conceptual row. The libesnmp routine builds this array by subtracting the object OID from the requested variable binding OID.
instance_len The size of the method->row->instance field.
context A pointer to be used privately by the method routine to reference data needed for processing this request.
save A pointer to be used privately by the method routine to reference data needed for undoing this request.
state An integer to be used privately by the method routine for holding any state information it requires.

Description

The libesnmp routines call whatever routine is specified for Set operations in the object table identified by the registered subtree.

This function is pointed to by some number of elements of the subagent object table. When a request arrives for an object, its method routine is called. The *_set method routine is called in response to a Set request.

Return Values

ESNMP_MTHD_noError The routine completed successfully.
ESNMP_MTHD_notWritable The requested object cannot be set or was not implemented.
ESNMP_MTHD_wrongType The data type for the requested value is the wrong type.
ESNMP_MTHD_wrongLength The requested value is the wrong length.
ESNMP_MTHD_wrongEncoding The requested value is represented incorrectly.
ESNMP_MTHD_wrongValue The requested value is out of range.
ESNMP_MTHD_noCreation The requested instance can never be created.
ESNMP_MTHD_inconsistentName The requested instance cannot currently be created.
ESNMP_MTHD_inconsistentValue The requested value is not consistent.
ESNMP_MTHD_resourceUnavailable A failure due to some resource constraint.
ESNMP_MTHD_genErr A general processing error.
ESNMP_MTHD_commitFailed The commit phase failed.
ESNMP_MTHD_undoFailed The undo phase failed.

Previous Next Contents Index