# Compaq TCP/IP Services for OpenVMS
SNMP Programming and Reference

Previous | Contents | Index

## 4.2.2 Entering Commands for the Trap Receiver Program

The trap receiver program lets you listen for, receive, and display SNMP trap messages. Until interrupted, the program continues to listen on the specified port.

If you enter commands using the default port number or another privileged port number, you must run the program from a privileged account.

To run the trap receiver program, do the following:

1. Define a foreign command for the program:

       $ snmp_traprcv == "$SYS$SYSTEM:TCPIP$SNMP_TRAPRCV"

   Alternatively, you can run SYS$MANAGER:TCPIP$DEFINE_COMMANDS.COM to define all the foreign commands available with TCP/IP Services.
2. Enter a command using the following format:

       snmp_traprcv [-d] [-tcp] [-p port]

### 4.2.2.1 Trap Receiver Flags

Table 4-6 describes the `snmp_traprcv` flags.

Table 4-6 snmp_traprcv Command Flags
Flag | Description
--- | ---
`-d` | Displays a hexadecimal and formatted dump of the received packet.
`-p port` | Specifies the port number on the local host on which to listen for trap messages. The default is 162.
`-tcp` | Listens on the TCP port instead of the UDP (default) port. Reads only a single PDU on an established connection, which is similar to the behavior using UDP.

### 4.2.2.2 Setting Up an SNMP Trap Service

To set up an SNMP trap service for use with the trap receiver program, enter a management command in the following format:

    SET SERVICE SNMP-TRAP /PROTOCOL=UDP /USER_NAME=TCPIP$SNMP
    /PROCESS_NAME=TCPIP$SNMP-TRAP /FILE=TCPIP$SYSTEM:TCPIP$SNMP-TRAP.COM

In this command, port 170 is used as an alternative for port 162, and traps that are received on port 162 are ignored.

If you omit the /PROTOCOL qualifier or you use /PROTOCOL=TCP, the service uses the TCP transport. In this case, when you enter a command to run the trap receiver program, you must include the `-tcp` flag.

With the SNMP trap service in place, the trap receiver program queries the service for the port number instead of using the default port 162. If you specify a privileged port number (less than 1024) with the /PORT qualifier, make sure you install the trap receiver program with privileges, or run the program from an account that has SYSPRV privilege. Note that the port number must be greater than zero.

### 4.2.2.3 Trap Receiver Examples

1. The following example requests trap information on a system that does not have traps configured and does not have SYSPRV privilege or sufficient privilege.

       $ snmp_traprcv
       No snmp-trap service entry, using default port 162.
       bind - : permission denied

2. The example, supplied from a nonprivileged account, requests trap information in hexadecimal dump format on port 1026.

       $ snmp_traprcv -d -p 1026

       Message received from 127.0.0.1

       3082002A 02010004 06707562 6C6963A4   0..*.....public.
       1D060547 81AD4D01 40040000 00000201   ...G..M.@.......
       00020100 4304032D AED23082 0000       ....C..-..0...
       SNMPv1-Trap-PDU:

       community -  7075626C 6963                         public

       enterprise - 0.0
       agent address - 0.0.0.0
       trap type - Cold Start (0)
       timeticks - 53325522

# Chapter 5
eSNMP API Routines

This chapter provides reference information about the following types of application programming interface (API) routines in the eSNMP developer's kit:

- Interface routines ( Section 5.1)
- Method routines ( Section 5.2)
- Support routines ( Section 5.3)

# 5.1 Interface Routines

The interface routines are for developers writing the portion of the application programming interface (API) that handles the connection between the agent and the subagent. The interface routines are listed Table 5-1 and described in the following pages.

Table 5-1 Interface Routines
Routine | Function
--- | ---
`esnmp_init` | Initializes the subagent and initiates communication with the master agent.
`esnmp_register` | Requests local registration of a MIB subtree.
`esnmp_unregister` | Cancels local registration of a MIB subtree.
`esnmp_register2` | Requests cluster registration of a MIB subtree.
`esnmp_unregister2` | Cancels cluster registration of a MIB subtree.
`esnmp_capabilities` | Adds a subagent's capabilities to the master agent's `sysORTable` .
`esnmp_uncapabilities` | Removes a subagent's capabilities from the master agent's `sysORTable` .
`esnmp_poll` | Processes a pending request from the master agent.
`esnmp_are_you_there` | Requests a report from the master agent to indicate it is up and running.
`esnmp_trap` | Sends a trap message to the master agent.
`esnmp_term` | Sends a close message to the master agent.
`esnmp_sysuptime` | Converts UNIX system time into a value with the same time base as `sysUpTime` .

# esnmp_init

> Initializes the Extensible SNMP (eSNMP) subagent and initiates communication with the master agent.

## Format

> 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_init` routine 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

> ESNMP_LIB_NO_CONNECTION | Could not initialize or communicate with the master agent. Try again after a delay.
> ESNMP_LIB_OK | The `esnmp_init` routine has completed successfully.
> ESNMP_LIB_NOTOK | Could not allocate memory for the subagent.

## Example

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

# esnmp_register

> Requests local registration of a single MIB subtree. This indicates to the master agent that the subagent instantiates MIB variables within the registered MIB subtree.

## Format

> 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 for more information about these files.

> Note All memory pointed to by the subtree fields must have permanent storage since it is referenced by `libesnmp` for the duration of the program. You should use the data declarations emitted by the MIBCOMP program.

> ### 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. Compaq recommends that you use the default. For information about modifying the default subagent timeout value, refer to Section 6.2.

> ### 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 (OID 1.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` (OID 1.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.

> SNMP_LIB_OK | The `esnmp_register` routine has completed successfully.
> ESNMP_LIB_BAD_REG | The `esnmp_init` routine has not been called, the timeout parameter is invalid, or the subtree has already been queued for registration.
> ESNMP_LIB_LOST_CONNECTION | The subagent has lost communications with the master agent.

## 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");
>     }

# esnmp_unregister

> Cancels registration of a MIB subtree previously registered with the master agent.

## Format

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

> SNMP_LIB_OK | The `esnmp_unregister` routine has 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 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;
>     }

# esnmp_register2

> Requests registration of a single MIB subtree. This indicates to the master agent that the subagent instantiates MIB variables within the registered MIB subtree. The `esnmp_register2` routine offers extensions to the `esnmp_register` routine.

## Format

> int esnmp_register2 ( ESNMP_REG *reg ) ;

## Arguments

> ### reg

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

> Field Name | Description
> --- | ---
> subtree | A pointer to a subtree structure corresponding to the MIB subtree to be handled. The subtree structures are externally declared and initialized in the code emitted by the MIBCOMP command ( subtree_TBL.C and subtree_TBL.H, where subtree is the name of the MIB subtree). This code is taken directly from the MIB document. All memory pointed to by this field must have permanent storage since it is referenced by `libesnmp` for the duration of the program. You should use the data declarations emitted by the MIBCOMP command.
> priority | The registration priority. The entry with the largest number has the highest priority. The range is 1 to 255. The subagent that has registered a MIB subtree with the highest priority over a range of object identifiers gets all requests for that range of OIDs. MIB subtrees that are registered with the same priority are considered duplicates, and the registration is rejected by the master agent. The priority field is a mechanism for cooperating subagents to handle different configurations.
> timeout | The number of seconds the master agent should wait for responses when requesting data in this MIB subtree. This value must be between zero and 300. If the value is zero, the default timeout (3 seconds) is used. You should use the default. For information about modifying the default timeout value, refer to Section 6.2.
> range_subid | An integer value that, when nonzero, together with the range_upper_bound field specifies a range instead of one of the MIB subtree's OID subidentifiers. The range_subid field specifies the OID subidentifier modified by the range_upper_bound field.
> range_upper_bound | An integer value that, with a nonzero range_subid field, specifies a range instead of one of the MIB subtree's OID subidentifiers. The range_upper_bound field provides the upper bound of the range and the range_subid field provides the lower bound of the range, which is the MIB subtree's OID subidentifier.
> options | An integer value that, when set to ESNMP_REG_OPT_CLUSTER, indicates that the registration is valid clusterwide. When the value is set to zero, it indicates that the registration is valid for the local node.
> state | One of the following integer values that provides the caller with asynchronous updates of the state of registration of this MIB subtree. After the return of the `esnmp_poll` routine, the caller can inspect this parameter.
> ESNMP_REG_STATE_PENDING | The registration is currently held locally while waiting for connection to the master agent.
> ESNMP_REG_STATE_SENT | The registration was sent to the master agent.
> ESNMP_REG_STATE_DONE | The registration was successfully acknowledged by the master agent.
> ESNMP_REG_STATE_REGDUP | The registration was rejected by the master agent because it was a duplicate.
> ESNMP_REG_STATE_REGNOCLU | The master agent does not support cluster registrations.
> ESNMP_REG_STATE_REJ | The master agent rejected the registration for other reasons.
> reserved | This field is reserved for exclusive use by the eSNMP library. The caller should not modify it.

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

> SNMP_LIB_OK | The `esnmp_register2` routine has completed successfully.
> ESNMP_LIB_BAD_REG | The `esnmp_init` routine has not been called, the `timeout` parameter is invalid, a registration slot is not available, or this MIB subtree has already been queued for registration. A message is also in the log file.
> ESNMP_LIB_LOST_CONNECTION | The subagent lost communication with the master agent.

Previous | Next | Contents | Index