Syntax

int esnmp_init (int *socket, char *subagent_identifier ) ;

Arguments

socket

The address of the integer that receives the socket descriptor used by eSNMP.

subagent_identifier

The address of a null-terminated string that uniquely identifies this subagent (usually a program name).

Description

Call this routine during program initialization or to restart the eSNMP protocol. If you are restarting, the esnmp_initroutine clears all registrations so each subtree must be registered again.

You should attempt to create a unique subagent identifier, perhaps using the program name argv[0] and additional descriptive text. The master agent does not open communications with a subagent whose subagent identifier is already in use.

This routine does not block waiting for a response from the master agent. After calling the esnmp_init routine, call the esnmp_register routine for each subtree that is to be handled by the subagent.

Return Values

Example

#include <esnmp_h>
int socket;
status = esnmp_init(&socket, "gated");

Syntax

int esnmp_register ( subtree *subtree, int timeout, int priority );

Arguments

subtree

A pointer to a subtree structure corresponding to the subtree to be handled. The code emitted by the MIB compiler files (subtree_TBL.C and subtree_TBL.H) externally declare and initialize the subtree structures. Refer to Chapter 3, Creating a Subagent Using the eSNMP API for more information about these files.

timeout

The number of seconds the master agent should wait for responses when requesting data in this subtree. This value must be between 0 (zero) and 300. If the value is 0, the default timeout is 3 seconds.

VSI recommends that you use the default. For information about modifying the default subagent timeout value, refer to Section 6.2, “Modifying the Subagent Timeout”.

priority

The registration priority. The priority argument allows you to coordinate cooperating subagents to handle different configurations. The range is 1 to 255.

The entry with the largest number has the highest priority. The subagent that registers a subtree with the highest priority over a range of object identifiers gets all requests for that range of OIDs.

Subtrees registered with the same priority are considered duplicate, and the registration is rejected by the master agent.

Description

Call the initialization routine esnmp_init prior to calling the esnmp_register. Call the esnmp_register function for each subtree structure corresponding to each subtree to be handled. At any time, subtrees can be unregistered by calling esnmp_unregister and then be reregistered by calling the esnmp_register.

When restarting the eSNMP protocol by calling esnmp_init, all registrations are cleared. All subtrees must be reregistered.

A subtree is identified by the base MIB name and the corresponding OID number of the node that is the parent of all MIB variables contained in the subtree. For example: The MIB II tcp subtree has an OID of 1.3.6.1.2.1.6. All elements subordinate to this have the same first seven digits and are included in the subtree's object table. The subtree can also be a single MIB object (a leaf node) or even a specific instance.

By registering a subtree, the subagent indicates that it will process eSNMP requests for all MIB variables (or OIDs) within that subtree's range. Therefore, a subagent should register the most fully qualified (longest) subtree that still contains its instrumented MIB variables.

The master agent does not permit a subagent to register the same subtree more than once. However, subagents can register subtrees with ranges that overlap the OID ranges of subtrees previously registered, and subagents can also register subtrees registered by other subagents.

For example, TCP/IP Services supports MIB II. In the eSNMP environment, the os_mibs subagent registers the MIB II subtree ip (OID 1.3.6.1.2.1.4).

TCP/IP Services also provides the gated subagent, which registers the ipRouteEntry MIB subtree (OID1.3.6.1.2.1.4.21.1).

These MIBs are registered at priority 1. Any subagent that registers at a higher priority (greater than 1) overrides these registrations.

A request for IpRouteIfIndex (OID1.3.5.1.2.1.4.21.1.2) is passed to the gated subagent. Requests for other ip variables, such as ipNetToMediaIfIndex (OID 1.3.5.1.2.1.4.22.1.1) are passed to the os_mibs subagent. If the gated subagent terminates or unregisters the ipRouteEntry subtree, subsequent requests for ipRouteIfIndex will go to the os_mibs subagent. This occurs because the ip subtree, which includes all ipRouteEntry variables, is now the authoritative region of requests for ipRouteIfIndex.

Return Values

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 OPEN message */
#define REGISTRATION_PRIORITY 10  /* priority at which subtrees
                                     will register */

int status;

extern SUBTREE ipRouteEntry_subtree;

status = esnmp_register( &ipRouteEntry_subtree,
                         RESPONSE_TIMEOUT,
                         REGISTRATION_PRIORITY );
if (status != ESNMP_LIB_OK) {
    printf ("Could not queue the 'ipRouteEntry' \n");
    printf ("subtree for registration\n");
}

Syntax

int esnmp_unregister ( SUBTREE *subtree ) ;

Arguments

subtree

A pointer to a subtree structure corresponding to the subtree to be handled. The code emitted by the MIB compiler files (subtree_TBL.C and subtree_TBL.H) externally declare and initialize the subtree structures. Refer to Chapter 3, Creating a Subagent Using the eSNMP API for more information about these files.

Description

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

Return Values

Example

#include <esnmp.h>
int status

extern SUBTREE ipRouteEntry_subtree;

status = esnmp_unregister (&ipRouteEntry_subtree);

switch (status) {
case ESNMP_LIB_OK:
  printf ("The esnmp_unregister routine completed successfully.\n");
  break;

case ESNMP_LIB_BAD_REG:
  printf ("The MIB subtree was not registered.\n");

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;
}

Syntax

int esnmp_register2 ( ESNMP_REG *reg ) ;

Arguments

reg

A pointer to an ESNMP_REG structure that contains the following fields:

Description

The initialization routine (esnmp_init) must be called prior to calling the esnmp_register2 routine. The esnmp_register2 function must be called for each subtree structure corresponding to each MIB subtree that it will be handling. At any time, MIB subtrees can be unregistered by calling esnmp_unregister2 and then can be reregistered by calling esnmp_register2.

When restarting the eSNMP protocol by calling esnmp_init, all MIB subtree registrations are cleared. All MIB subtrees must be reregistered.

A MIB subtree is identified by the base MIB variable name and its corresponding OID. This tuple represents the parent of all MIB variables that are contained in the MIB subtree; for example, the MIB II tcp subtree has an OID of 1.3.6.1.2.1.6. All elements subordinate to this (those that have the same first 7 identifiers) are included in the subtree's object table. A MIB subtree can also be a single MIB object (a leaf node) or even a specific instance.

By registering a MIB subtree, the subagent indicates that it will process SNMP requests for all MIB variables (or OIDs) within that MIB subtree's region. Therefore, a subagent should register the most fully qualified (longest) MIB subtree that still contains its instrumented MIB variables.

A subagent using the esnmp_register2 routine can register the same MIB subtree for the local node and for a cluster. To register the MIB subtree for both, you must call the esnmp_register2 routine twice: once with the ESNMP_REG_OPT_CLUSTER bit set in the options field and once with the ESNMP_REG_OPT_CLUSTER bit clear in the options field. Alternatively, you can register a MIB subtree for the cluster only or for the local node only, by setting or clearing the ESNMP_REG_OPT_CLUSTER bit, respectively, in the options field.

A subagent can also register MIB subtrees that overlap the OID range of MIB subtrees that it previously registered or the OID ranges of MIB subtrees registered by other subagents.

For example, consider the two subagents os_mibs and gated. The os_mibs subagent registers the ip MIB subtree (1.3.6.1.2.1.4), and the gated subagent registers the ipRouteEntry MIB subtree (1.3.6.1.2.1.4.21.1). Both of these registrations are made with the ESNMP_REG_OPT_CLUSTER bit set in the options field. Requests for ip MIB variables within ipRouteEntry, such as ipRouteIfIndex (1.3.6.1.2.1.4.21.1.2), are passed to the gated subagent. Requests for other ip variables, such as ipNetToMediaIfIndex (1.3.6.1.2.1.4.22.1.1), are passed to the os_mibs subagent. If the gated subagent terminates or unregisters the ipRouteEntry MIB subtree, subsequent requests for ipRouteIfIndex go to the os_mibs subagent. This occurs because the ip MIB subtree, which includes all ipRouteEntry MIB variables, is now the authoritative region of requests for ipRouteIfIndex.

Return Values

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 OPEN message */
#define REGISTRATION_PRIORITY 10  /* priority at which subtrees
                                     will register */

int status;

extern SUBTREE ipRouteEntry_subtree;

status = esnmp_register( &ipRouteEntry_subtree,
                         RESPONSE_TIMEOUT,
                         REGISTRATION_PRIORITY );
if (status != ESNMP_LIB_OK) {
    printf ("Could not queue the 'ipRouteEntry' \n");
    printf ("subtree for registration\n");
}

Syntax

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

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;
}

Syntax

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.

Syntax

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.

Syntax

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

Syntax

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

Syntax

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

Syntax

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

Syntax

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

Example

#include <sys/time.h>
#include <esnmp.h>
struct timeval timestamp;

gettimeofday(&timestamp, NULL);
   .
   .
   .
o_integer(vb, object, esnmp_sysuptime(&timestamp));

Syntax

int mib-group_get ( METHOD *method ) ;

Arguments

method

A pointer to a METHOD structure that contains the following fields:

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

Syntax

int mib-group_set ( METHOD *method ) ;

Arguments

method

A pointer to a METHOD structure that contains the following fields:

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

Syntax

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.

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.

Return Values

Example

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

Syntax

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

Arguments

vb

A pointer to the VARBIND structure that is supposed to receive the data.

If the original value in the vb field is not null, this routine attempts to free it. So if you dynamically allocate memory or issue the malloc command to allocate your own VARBIND structure, 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.

value

The value to be inserted into the VARBIND structure.

Return Values

Example

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

Syntax

int o_oid ( VARBIND *vb,
          OBJECT *obj,
          OID *oid );

Arguments

vb

A pointer to the VARBIND structure that is supposed to receive the data.

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 to allocate your own VARBIND structure, 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. For more information about OID length and values, see Chapter 3, Creating a Subagent Using the eSNMP API.

The real type as defined in the object structure must be ESNMP_TYPE_OBJECT_IDENTIFIER.

Return Values

Example

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

Syntax

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.

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 to allocate your own VARBIND structure, 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 be inserted into the VARBIND structure as data.

len

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

Return Values

Example

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

Syntax

int o_counter64 ( VARBIND *vb,
                OBJECT *obj,
                uint64 value ); (for Alpha)
                uint64_vax value ; (for VAX))

Arguments

vb

A pointer to the VARBIND structure that is supposed to receive the data.

obj

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

value

The 8-byte value to be inserted into the VARBIND structure, passed as an array of two integers.

The real type as defined in the object structure must be ESNMP_TYPE_Counter64. Otherwise, an error is returned.

Example

See the example for the o_integer routine.

Return Values

Syntax

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

Arguments

oid

The value to be inserted as data into the VARBIND structure. For more information about OID length and values, see Chapter 3, Creating a Subagent Using the eSNMP API.

s

A null string or empty string returns an OID structure that has one element of zero.

Description

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

Return Values

Example

include <esnmp.h>
OID abc;
if (stroid (&abc, "1.2.5.4.3.6") == NULL
   DPRINTF((WARNING, "It did not work...\n");

Syntax

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 value points to 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));

Syntax

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

Arguments

new

A pointer to the 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 array may be created by oid2instance or constructed from key values as a result of a GetNext command (see Chapter 1, Overview).

This routine dynamically allocates the buffer and inserts its pointer into the OID structure passed in the call. The caller must explicitly free the 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 (that is, free_oid is called first), and then the new values are dynamically allocated and inserted. Be sure the initial value of the new OID is all zeros. If you do not want the initial value freed, make sure the new OID structure is all zeros.

Return Values

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);

Syntax

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

Arguments

oid

A pointer to 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 structure 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

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;

The N will be in instance[0] and the IP address will be in instance[2], instance[3], instance[4], and instance[5].

Syntax

int inst2ip ( unsigned int *instance,
            int *length,
            unsigned int *ipaddr,
            int *exact,
            int *carry );

Arguments

instance

A pointer to an array of unsigned int containing the instance numbers returned by the oid2instance routine to be converted to an IP address.

The range for elements is between zero and 255. Using the EXACT mode, the routine returns 1 if an element is out of range. Using the NEXT mode, a value greater than 255 causes that element to overflow. In this case, the value is set to 0 and the next most significant element is incremented; therefore, it returns a lexically equivalent value of the next possible ipaddr.

length

The number of elements in the instance array. Instances beyond the fourth are ignored. If the length is less than four, the missing values are assumed to be zero. A negative length results in an ipaddr value of zero. For an exact match (such as Get), there must be exactly four elements.

ipAddr

A pointer indicating where to return the IP address value. This routine is in network byte order (the most significant element is first).

exact

Can either be TRUE or FALSE.

TRUE means do an EXACT match. If any element is greater than 255 or if there are not exactly four elements, a value of 1 is returned. The carry argument is ignored.

FALSE means do a NEXT match. That is, the lexically next IP address is returned, if the carry value is set and the length is at least four. If there are fewer than four elements, this function assumes the missing values are zero. If any one element contains a value greater than 255, the value is zeroed and the next most significant element is incremented. Returns a 1 (one) only when there is a carry from the most significant (the first) value.

carry

Adds to the IP address on a NEXT match. If you are trying to determine the next possible IP address, pass in a one. Otherwise, pass in a zero. A length of less than 4 cancels the carry.

Description

Use the EXACT mode for evaluating an instance for Get and Set operations. For GetNext and GetBulk operations, use the NEXT mode. When using NEXT mode, this routine assumes that the search for data will be performed using greater than or equal to matches.

Return Values

Examples

Syntax

int cmp_oid ( oid *q, oid *p );

Description

This routine does an element-by-element comparison, from the most significant element (element 0) to the least significant element. If all other elements are equal, the OID with the least number of elements is considered less.

Return Values

Syntax

int cmp_oid_prefix ( oid *q, oid *prefix );

Description

A prefix could be the OID on an object in the object table. The elements beyond the prefix are the instance information.

This routine does an element-by-element comparison, from the most significant element (element 0) to the least significant element. If all elements of the prefix OID match exactly with corresponding elements of the OID q structure, it is considered an even match if the OID q structure contains additional elements. The OID q structure is considered greater than the prefix if the first nonmatching element is larger. It is considered smaller if the first nonmatching element is less.

Return Values

Example

#include <esnmp.h>
OID *q;
OBJECT *object;
if (cmp_oid_prefix(q, &object->oid) == 0)
   printf("matches prefix\n");

Syntax

oid clone_oid ( oid *new, oid *oid );

Arguments

new

A pointer to the OID structure that is to receive the copy.

oid

A pointer to the OID structure where the data is to be obtained.

Description

This routine dynamically allocates the buffer and inserts its pointer into the OID structure received. The caller must explicitly free this buffer.

Point to the OID structure that is to receive the new OID values and call this routine. Any previous value in the new OID structure is freed (using the free_oid routine) and the new values are dynamically allocated and inserted. To preserve an existing OID structure, initialize the new OID structure with zeros.

If the old OID structure is null or contains a null pointer to its element buffer, a new OID of [0.0] is generated.

Return Values

Example

#include <esnmp.h>
OID oid1;
OID oid2;
:
: assume oid1 gets assigned a value
:
memset(&oid2, 0, sizeof(OID));
if (clone_oid(&oid2, &oid1) == NULL)
    DPRINTF((WARNING, "It did not work\n"));

Syntax

void free_oid ( oid *oid );

Description

This routine frees the buffer pointed to by the OID->elements field and zeros the field and the NELEM structure.

Example

include <esnmp.h>
OID oid;
:
: assume oid was assigned a value (perhaps with clone_oid()
: and we are now finished with it.
:
free_oid(&oid);

Syntax

char clone_buf ( char *str, int *len );

Arguments

str

A pointer to the buffer to be duplicated.

len

The number of bytes to be copied.

Description

One extra byte is always allocated at the end and is filled with zeros. If the length is less than zero, the duplicate buffer length is set to zero. A buffer pointer is always returned, unless there is a malloc error.

Return Values

Example

#include <esnmp.h>
char *str = "something nice";
char *copy;
copy = clone_buf(str, strlen(str));

Syntax

oct *mem2oct ( oct *new, char *buffer, int *len );

Argument

new

A pointer to the oct structure receiving the data.

buffer

Pointer to the buffer to be converted.

len

Length of buffer to be converted.

Description

The mem2oct routine dynamically allocates the buffer and inserts its pointer into the oct structure. The caller must explicitly free this buffer.

This routine does not allocate an oct structure and does not free data previously pointed to in the oct structure before making the assignment.

Return Values

Example

#include <esnmp.h>
char buffer;
int len;
OCT abc;

...buffer and len are initialized to something...

memset(&abc, 0, sizeof(OCT));
if (mem2oct(&abc, buffer, len) == NULL)
    DPRINTF((WARNING, "It did not work...\n"));

Syntax

int cmp_oct ( oct *oct1, oct *oct2 );

Arguments

oct1

Pointer to the first octet string.

oct2

Pointer to the second octet string.

Description

The two octet strings are compared byte-by-byte to determine the length of the shortest octet string. If all bytes are equal, the lengths are compared. An octet with a null pointer is considered the same as a zero-length octet.

Return Values

Example

#include <esnmp.h>
OCT abc, efg;

...abc and efg are initialized to something...

if (cmp_oct(&abc, &efg) > 0)
    DPRINTF((WARNING, "octet abc is larger than efg...\n"));

Syntax

oct clone_oct ( oct *new, oct *old );

Arguments

new

A pointer to the oct structure receiving the data.

old

A pointer to the oct structure where the data is to be obtained.

Description

The clone_oct routine dynamically allocates the buffer, copies the data, and updates the oct structure with the buffer's address and length. The caller must free this buffer.

The previous value of the buffer on the new oct structure is freed prior to the new buffer being allocated. If you do not want the old value freed, initialize the new oct structure before cloning.

Return Values

Example

#include <esnmp.h>
OCT octet1;
OCT octet2;
:
: assume octet1 gets assigned a value
:
memset(&octet2, 0, sizeof(OCT));
if (clone_oct(&octet2, &octet1) == NULL)
    DPRINTF((WARNING, "It did not work\n"));

Syntax

void free_oct ( oct *oct );

Description

This routine frees the dynamically allocated buffer to which the oct structure points, and zeros the pointer and length on the oct structure. If the oct structure is already null, this routine does nothing.

If the buffer attached to the oct structure is already null, this routine sets the length field of the oct structure to zero.

Example

#include <esnmp.h>
OCT octet;
:
: assume octet was assigned a value (perhaps with mem2oct()
: and we are now finished with it.
:
free_oct(&octet);

Syntax

void free_varbind_data ( varbind *vb );

Description

This routine performs a free_oid (vb->name) operation. If indicated by the vb->type field, it then frees the vb->value data using either the free_oct or the free_oid routine.

Example

#include <esnmp.h>
VARBIND *vb;

vb = (VARBIND*)malloc(sizeof(VARBIND));
clone_oid(&vb->name, oid);
clone_oct(&vb->value.oct, data);
:
: some processing that uses vb occurs here
:
free_varbind_data(vb);
free(vb);

Syntax

void set_debug_level ( int stat, unsigned integer null );

Arguments

stat

The logging level. The following values can be set individually or in combination:

null

This parameter is not used by OpenVMS. It is supplied for compatibility with UNIX.

Description

The logging level will be ERROR, WARNING, or TRACE.

If you specify TRACE, all three types of errors are generated. If you specify ERROR, only error messages are generated. If you specify WARNING, both error and warning messages are generated.

To specify logging levels for the messages in your subagent, use the ESNMP_LOG routine.

Example

#include <esnmp.h>

if (strcmp("-t", argv[1] {
    set_debug_level(TRACE, NULL);
} else {
    set_debug_level(WARNING, NULL);
}

Additional Information

You can test the logging levels as follows:

Syntax

int is_debug_level ( int type );

Return Values

Example

#include <esnmp.h>

if (is_debug_level(TRACE))
    dump_packet()

Syntax

ESNMP_LOG ( level, format, ... );

Description

#define ESNMP_LOG(level, x) if (is_debug_level(level)) { \
         esnmp_log(level, esnmp_logs x, __LINE__, __FILE__);}

For more information about configuration options for logging and tracing, refer to the VSI TCP/IP Services for OpenVMS Management guide.

Example

#include <esnmp.h>
ESNMP_LOG( ERROR, ("Cannot open file %s\n", file));

Syntax

__print_varbind ( VARBIND *vb, int indent );

Arguments

vb

The pointer to the VARBIND structure to be displayed. If the vb pointer is NULL, no output is generated.

indent

The number of bytes of white space to place before each line of output.

Syntax

set_select_limit ( char *progname );

Arguments

progname

The subagent name. This argument is valid with DPI versions only. With AgentX, the argument is NULL because subagents do not get names.

Return Values

Syntax

__set_progname ( char *prog );

Arguments

prog

The program name as taken from argv[0], or some other identification for entity-calling logging routines.

Example

#include "esnmp.h"
__set_progname(argv[0]);

Syntax

__restore_progname ( );

Example

#include "esnmp.h"
__restore_progname();

Syntax

__parse_progname ( file-specification );

Arguments

file-specification

The full file specification for the subagent.

Example

#include "esnmp.h"
static char Progname[100];
sprintf (Progname, "%s%.8X", __parse_progname(prog), getpid());

Syntax

esnmp_cleanup ( );

Example

#include "esnmp.h"
int rc = ESNMP_LIB_OK;
rc = esnmp_cleanup();

Return Values