# 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` ---respond to `Get` , `GetNext` , and `GetBulk` requests
- `*_set` ---respond to `Set` requests

# *_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