DIGITAL TCP/IP Services for OpenVMS
eSNMP Programming and Reference
Previous Contents Index

esnmp_poll

Processes a pending message that 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 syslog file and an error status is returned.

If the received message is a request for eSNMP data, the object table is checked and the appropriate method routines are called.

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 An OPEN error occurred. A duplicate subagent identifier has already been received by the master agent.
ESNMP_LIB_NO_CONNECTION The master agents OPEN request failed. Restart the connection after a delay. See the log file.
ESNMP_LIB_CLOSE A CLOSE message was received. Restart the connection after a delay.
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

Sends ICMP ECHO_REQUEST packets (ping) to the master agent.

Format

int esnmp_are_you_there ()

Description

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

If no response is received within the timeout period, the application code restarts the eSNMP protocol by calling the esnmp_init routine. There are no timers maintained by the eSNMP library.

Return Values

ESNMP_LIB_OK The ICMP ECHO_REQUEST was sent.
ESNMP_LIB_LOST_CONNECTION The ICMP ECHO_REQUEST packet 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)

Arguments

generic_trap

A generic trap code.

specific_trap

A specific trap code.

enterprise

An enterprise OID string in dot notation.

vb

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

Description

This function can be called any time. If eSNMP has not initialized through the master agent, 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 eSNMP 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 eSNMP.

Format

void esnmp_term (void)

Description

Subagents should call this routine when terminating, so that the master agent can update its MIB registry more quickly.

Return Values

ESNMP_LIB_OK The esnmp_term 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 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. Passing a null timestamp returns the current value of sysUpTime.

This routine can be used as a TimeTicks data type (the time since the eSNMP master agent started) in units of 1/100 second. The time base is obtained from the master agent at OPEN time so calls to this function before that time will not be accurate.

Return Values

0 An error occurred because a gettimeofday failed. Otherwise, timestamp time is 1/100 second since the eSNMP protocol started.

Example


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

5.2 Support Routines

The support routines are optional but are provided as a convenience to developers writing method routines that handle specific management information base (MIB) elements. The support routines provided include the following:

o_integer

Loads an integer value into the VARBIND structure with the appropriate type.

Format

int o_integer (VARBIND *vb, OBJECT *obj, unsigned long value)

Arguments

*vb

A pointer to the VARBIND structure that is supposed to receive the data. This function does not allocate the VARBIND structure.

*obj

A pointer to the OBJECT structure for the MIB variable associated with the OID in the VARBIND structure.

value

The value to be inserted into the VARBIND structure.

The real type as defined in the object structure must be one of the following, otherwise an error is returned.

Note
If the real type is IpAddress, then eSNMP assumes that the 4-byte integer is in network byte order and packaged it into an octet string.

Return Values

ESNMP_MTHD_noError The routine completed successfully.
ESNMP_MTHD_genErr An error has occurred.

Example


 
include <esnmp.h> 
#include "ip_tbl.h"  <-- for ipNetToMediaEntry_type definition 
VARBIND     *vb       = method->varbind; 
OBJECT      *object   = method->object; 
ipNetToMediaEntry_type *data; 
 
switch(arg) { 
case I_atIfIndex: 
return o_integer(vb, object, data->ipNetToMediaIfIndex);

o_octet

Loads an octet value into the VARBIND structure with the appropriate type.

Format

int o_octet (VARBIND *vb, OBJECT *obj, OCT *oct)

Arguments

*vb

A pointer to the VARBIND structure that is supposed to receive the data. This function does not allocate the VARBIND structure.

Note
If the original value in the VARBIND structure is not null, this routine attempts to free it. So if you dynamically allocate memory or issue the malloc command. Fill the structure with zeros before using it.

*obj

A pointer to the OBJECT structure for the MIB variable associated with the OID in the VARBIND structure.

*oct

The value to be inserted into the VARBIND structure.

The real type as defined in the object structure must be one of the following, otherwise an error is returned.

Return Values

ESNMP_MTHD_noError The routine completed successfully.
ESNMP_MTHD_genErr An error occurred.

Example


 
#include <esnmp.h> 
#include "ip_tbl.h"  <-- for ipNetToMediaEntry_type definition 
VARBIND     *vb       = method->varbind; 
OBJECT      *object   = method->object; 
ipNetToMediaEntry_type *data; 
 
switch(arg) { 
 case I_atPhysAddress: 
 return o_octet(vb, object, &data->ipNetToMediaPhysAddress);

o_oid

Loads an OID value into the VARBIND structure with the appropriate type.

Format

int o_integer (VARBIND *vb, OBJECT *obj, OID *oid)

Arguments

*vb

A pointer to the VARBIND structure that is supposed to receive the data. This function does not allocate the VARBIND structure.

Note
If the original value in the VARBIND structure is not null, this routine attempts to free it. So if you dynamically allocate memory or issue the malloc command. Fill the structure with zeros before using it.

*obj

A pointer to the OBJECT structure for the MIB variable associated with the OID in the VARBIND structure.

*oid

The value to be inserted into the VARBIND structure as data.

The real type as defined in the object structure must be one of the following, otherwise an error is returned.

Return Values

ESNMP_MTHD_noError The routine completed successfully.
ESNMP_MTHD_genErr An error occurred.

Example


 
#include <esnmp.h> 
#include "ip_tbl.h"  <-- for ipNetToMediaEntry_type definition 
VARBIND     *vb       = method->varbind; 
OBJECT      *object   = method->object; 
ipNetToMediaEntry_type *data; 
 
switch(arg) { 
 case I_atObjectID: 
  return o_oid(vb, object, &data->ipNetToMediaObjectID);

o_string

Loads a string value into the VARBIND structure with the appropriate type.

Format

int o_string (VARBIND *vb, OBJECT *obj, unsigned character *ptr, int *len)

Arguments

*vb

A pointer to the VARBIND structure that is supposed to receive the data. This function does not allocate the VARBIND structure.

Note
If the original value in the VARBIND structure is not null, this routine attempts to free it. So if you dynamically allocate memory or issue the malloc command. Fill the structure with zeros before using it.

*obj

A pointer to the OBJECT structure for the MIB variable associated with the OID in the VARBIND structure.

*ptr

The pointer to the buffer containing data to inserted into the VARBIND structure as data.

*len

The length of the data in buffer pointed to by ptr.

The real type as defined in the object structure must be one of the following, otherwise an error is returned.

Return Values

ESNMP_MTHD_noError The routine completed successfully.
ESNMP_MTHD_genErr An error occurred.

Example


 
#include <esnmp.h> 
#include "ip_tbl.h"  <-- for ipNetToMediaEntry_type definition 
VARBIND     *vb       = method->varbind; 
OBJECT      *object   = method->object; 
ipNetToMediaEntry_type *data; 
 
switch(arg) { 
 case I_atPhysAddress: 
   return o_string(vb, object, data->ipNetToMediaPhysAddress.ptr, 
                               data->ipNetToMediaPhysAddress.len);

str2oid

Converts a null-terminated string OID in dot notation to an OID structure.

Format

oid *str2oid (oid *oid, char *s)

Description

The routine dynamically allocates the buffer and inserts its pointer into the OID structure passed in. The caller is responsible to free this buffer. The OID can have a maximum of 128 elements.

Note
The str20id routine does not allocate an OID structure.

Return Values

null An error occurred or the pointer to the OID structure (its first argument) has been returned.

Example


 
include <esnmp.h> 
#define SOMETHING_BIG 1024 
OID abc; 
char buffer[SOMETHING_BIG]; 
: 
: assume abc gets initialized with some value 
: 
printf("dots=%s\n", sprintoid(buffer, &abc));

sprintoid

Converts an OID into a null-terminated string.

Format

char *sprintoid (char *buffer, oid *oid)

Description

An OID can have up to 128 elements. A full-sized OID can require a large buffer.

Return Values

The return values are its first argument.  

Example


 
#include <esnmp.h> 
#define SOMETHING_BIG 1024 
OID abc; 
char buffer[SOMETHING_BIG]; 
: 
: assume abc gets initialized with some value 
: 
printf("dots=%s\n", sprintoid(buffer, &abc));

instance2oid

Copies the object's base OID and appends a copy of the instance array to make a complete OID for a value.

Format

oid instance2oid (oid *new, obj *obj, unsigned int *instance, int *len)

Arguments

*new

A pointer to OID that is to receive the new OID value.

*obj

A pointer to the object table entry for the MIB variable being obtained. The first part of the new OID is the OID from this MIB object table entry.

*instance

A pointer to an array of instance values. These values are appended to the base OID obtained from the MIB object table entry to construct the new OID.

*len

The number of elements in the instance array.

Description

The instance is an array of integers and len is the number of elements. The instance array may be created by oid2instance or constructed from key values as a result of a get_next search.

This routine dynamically allocates the buffer and inserts its pointer into the OID structure passed in. It is the responsibility of the caller to free this buffer.

You should point to the OID structure receiving the new values and then call the instance2oid routine. Previous values in the OID structure are freed and the new values are dynamically allocated and inserted. Be sure the initail value of the new OID is all zeros. If you do not want the value freed, the instance2oid routine does not allocate an OID structure, only the array containing the elements.

Return Values

null An error occurred or the pointer to the OID structure (its first argument) has been returned.

Example


 
#include <esnmp.h> 
VARBIND *vb;      <-- filled in 
OBJECT  *object;  <-- filled in 
unsigned int instance[6]; 
 
-- Construct the outgoing OID in a GETNEXT          -- 
-- Instance is N.1.A.A.A.A where A's are IP address -- 
instance[0] = data->ipNetToMediaIfIndex; 
instance[1] = 1; 
for (i = 0; i < 4; i++) { 
instance[i+2]=((unsigned char *)(&data->ipNetToMediaNetAddress))[i]; 
} 
instance2oid(&vb->name, object, instance, 6);

oid2instance

Extracts the instance values from an OID and copies them to the specified array of integers. The routine then returns the number of elements in the array.

Format

int oid2instance (oid *oid, obj *obj, unsigned int *instance, int *max_len)

Arguments

*oid

An incoming OID containing an instance or part of an instance.

*obj

A pointer to the object table entry for the MIB variable.

*instance

A pointer to an array of unsigned integers where the index is placed.

*max_len

The number of elements in the instance array.

Description

The instance values are the elements of an OID beyond those that identify the MIB variable. These elements identify a specific instance of a MIB value.

If there are more elements in the OID than specified by the max_len parameter, the function copies the number of elements specified by max_len only and returns the total number of elements that would have been copied had there been space.

Return Values

LESS THAN ZERO An error occurred. This should not occur if the object was obtained by looking at this OID.
ZERO No instance elements.
GREATER THAN ZERO The number of index elements. This could be larger than the max_len parameter.

Example


 
#include <esnmp.h> 
OID         *incoming = &method->varbind->name; 
OBJECT      *object   = method->object; 
int         instLength; 
unsigned int instance[6]; 
 
-- in a GET operation -- 
-- Expected Instance is N.1.A.A.A.A where A's are IP address -- 
instLength = oid2instance(incoming, object, instance, 6); 
if (instLength != 6) 
    return ESNMP_MTHD_noSuchInstance;

Previous Next Contents Index