Chapter 3. Tools and Functions

This chapter describes the tools and application programming interfaces (APIs) included in the Agent Development Kit. It includes the following sections:

Introduction

The Agent Development Kit provides a library of functions that comprise an application programming interface (API) and a set of utilities for building and testing agents or subagents. The Agent Development Kit tools and functions enable you to:

These tools and functions are listed in the following table.

Agent Tools Agent Functions

build_agent
imibgenall
imibprint
instsrv
snmpget
snmpgetnext
snmptest
snmptrap
snmptrapd
snmpwalk

csam_get_keyword
csam_set_keyword
csam_trap_add_var_bind
csam_trap_create
csam_trap_send
bea_sendtrap
bea_snmptrap

MIB Variable Definition Files

When a MIB variable is used with an Agent Development Kit utility, the utility attempts to convert the variable to a numeric OID by searching first in a file named mib.txt in the current directory, and then in a file specified in the environment variable BEA_SM_SNMP_MIBFILE, and finally in the /etc/mib.txt file. These files should use ASN.1 notation and use the OBJECT TYPE macro defined in RFC 1155 (Structure of Management Information).

The $RELEASE_ROOT/agent_src/agentlib/mib.txt file describes the RFC 1213 (MIB-II) and the BEA private MIB objects.

SNMP Request Format

Agent Development Kit utilities use SNMP requests to query SNMP agents for information about managed objects. Refer to RFC 1157 (SNMP) for more information about the format of SNMP requests. For information about locating RFCs on the Internet, refer to Appendix A, "SNMP Information," in the Agent Integrator Reference Manual.

Agent Tools

The Agent Development Kit software provides several tools to help you build and test an agent or subagent. The following list describes these tools.

build_agent

Builds SNMP and SMUX agent executables.

imibgenall

Generates or updates skeletal access function and hooks source code to support a private MIB group.

imibprint

Prints a list of the MIB object identifiers and names.

instsrv

Installs an agent as a Windows NT service.

snmpget

Reports information about scalar managed objects.

snmpgetnext

Returns the next entry in a table or the next consecutive managed object in a MIB.

snmptest

Selectively performs get and set operations on any MIB object.

snmptrap

Sends an SNMP trap message to a host.

snmptrapd

Receives and logs SNMP trap messages sent on a local machine to the snmp-trap port.

snmpwalk

Traverses the OID tree using the SNMP getnext request to query managed objects.

build_agent

Purpose

Builds SNMP and SMUX agents.

Synopsis

build_agent [ -q ] [ -n AgentName | -r MIBRootName ]

Arguments

-q
The utility does not prompt for user input if this option is specified.

-n AgentName
The name of the agent executable that will be generated. Newly generated agents are placed in:

$RELEASE_ROOT/agent_src/agentlib

-r MIBRootName
This option specifies the MIB group name used when creating the access function module for stand-alone testing. The name of the built module is:

csnmp_MIBRootName

The -r and -n options are mutually exclusive.

Description

If no options are specified, the utility enters agent creation mode with the default name of the agent set to snmpd.

The first time an agent is built, the build_agent utility prompts the user for the MIB groups to be included, any ancillary files to be compiled, and any ancillary library files to be linked with the agent executable. This information is stored by the build_agent utility. If this agent is rebuilt, the current configuration is displayed and the utility prompts the user for any changes. A newly created agent is placed in the $RELEASE_ROOT/agent_src/agentlib directory.

The build_agent utility also builds a module of access functions for the specified MIB group. When created, the file is called csnmp_MIBRootName and is placed in the $RELEASE_ROOT/agent_src/agentlib directory. This module can be used for testing the access functions in stand-alone mode.

Examples

The command: 

build_agent -n ex_snmpd -q

creates an agent with the name ex_snmpd.

Because the -q option has been specified, build_agent will not go into interactive mode, asking which MIB groups need to be included in ex_snmpd. If the configuration is being created for the first time, ex_snmpd will be created with all the MIB groups currently developed. If this is not the first time the ex_snmpd agent has been built, the previously specified configuration is displayed but you will not be prompted for any changes.

Environment Variables

RELEASE_ROOT
Contains the root directory of the Agent Development Kit installation.

imibgenall

Purpose

Generates or updates all necessary agent code to support a new private MIB group

Synopsis

imibgenall [ -u | -H Headerfile ] MIBRootName

Arguments

-u
Undo any code generation for the MIBRootName MIB group.

-H HeaderFile
Specifies the file name containing customer-specific header information to be placed at the beginning of the generated files.

MibRootName
The root of the section of the MIB tree for which code will be generated.

Description

The imibgenall utility must be run from the $RELEASE_ROOT/agent_src/agentlib directory.

The imibgenall utility requires a MIBRootName argument. For scalar objects, indicate the name of the ancestor object (e.g., the name of the object above them in the tree). For tabular objects, indicate the name of the table object.

By default, the imibgenall utility creates agent source code to support your private MIB. When the -u argument is specified, the utility removes any code previously generated for any portion of your MIB.

If you are creating code to support your MIB, this utility creates several files to support the specified MIB in the SNMP agent: agent hook and access functions files, and their supporting header files. It also updates the makefiles that are needed to build an SNMP agent. You need only modify the generated access functions file: 

$RELEASE_ROOT/agent_src/agentlib/MIBRootName.c

where MIBRootName is the same as the argument passed to imibgenall. Once the code is created, your only concern is with filling in the access function skeletons in a single source file, and perhaps tuning of constants defined in its associated header file: 

$RELEASE_ROOT/agent_src/agentlib/MIBRootName.h

Environment Variables

RELEASE_ROOT
Contains the root directory of the Agent Development Kit installation.

Examples

Assume a private MIB such as in the following diagram, where objects a through g are scalar, and objects h through n are columnar objects (i.e., scalar-valued objects that can have multiple instances).

Figure 3-1 Sample Private MIB Tree

The imibgenall utility must be run four times to create four agent hook files, their corresponding access function files, and other files. The four commands would be the following: 

imibgenall beaSecParam
imibgenall beaSecStats
imibgenall beaSecMgrTable
imibgenall beaSecUserTable

The following creates code associated with the MIB group item beaSecParam: 

imibgenall beaSecParam

Several files will be created. Usually, you will only need to modify the file beaSecParam.c, but you may be required to make some changes to the beaSecParam.h file. You can undo these operations by entering: 

imibgenall -u beaEm

Warning: The imibgenall -u command will delete the MIBRootName.c and MIBRootName.h files. Before invoking imibgenall with this option, you may wish to make a backup copy of any changes in the MIBRootName.c and MIBRootName.h files that you want to preserve. The imibgenall -u command will also delete any entries in the makefiles for the specified MIB group.

imibprint

Purpose

Prints a list of the MIB object identifiers and names from mib.txt.

Synopsis

imibprint -o | -t | -sa | -so | -h

Arguments

-o
Prints the object identifiers, one per line.

-t
Prints the object identifiers in a tree structure, with each descendant OID indented one level from its ancestor OID.

-sa
Prints object identifiers, sorted by name.

-so
Prints object identifiers, sorted by numeric identifier.

-h
Prints the command synopsis.

Description

mib.txt is an ASCII text description of your MIB objects, generated from your ASN.1 MIB file by the code generator/MIB compiler.

Environment Variables

BEA_SM_SNMP_MIBFILE
By default, imibprint first looks for mib.txt in /etc. If the file is not in that directory, imibprint uses the directory specified by this environment variable to locate mib.txt. If this environment variable is not set, and mib.txt is not in /etc, imibprint looks in the current directory.

instsrv

Purpose

Agents built using the Agent Development Kit can be installed as a Windows NT service using this utility. Supported on Windows NT machines only.

Synopsis

instsrv service-name [executable-file | remove]

Enter executable-file to create a service. Enter remove to remove a service.

Arguments

service-name
The name of the service. This should always be the same as the basename of the executable file.

executable-file
The complete path to the agent executable file.

snmpget

Purpose

Reports information about scalar managed objects.

Synopsis

snmpget [-d] [-p port] host community variable-name [variable-name  ...]

Arguments

-d
Causes the program to display a message for each packet.

-p port
Specifies the port used to communicate with the SNMP agent (default: 161).

host
The internet address or host name of the node executing the SNMP agent to be queried.

community
The community name for the transaction.

variable-name
At least one unique object identifier (OID).

Description

The snmpget utility uses SNMP get requests to retrieve information about managed objects.

You can enter one or more object identifiers as arguments on the command line. These names can be absolute, starting from the root of the tree, or relative to .iso.org.dod.internet. Read Chapter 2, "Agent Development Kit Overview," for more information on specifying object identifiers.

Environment Variables

BEA_SM_SNMP_MIBFILE
Must be set to specify the path to mib.txt, which provides an ASCII text description of the contents of your private MIB.

Examples

The following command sends a query to the SNMP agent running on the host named topaz, using public as the community for authorization. The agent retrieves the value of the managed object beaSysHasDisk in the BEA private MIB. Note that in this example, a relative OID (private.enterprises.bea.beaSystem) is specified. .iso.org.dod.internet. is prepended to generate an absolute path. 

snmpget topaz public private.enterprises.bea.beaSystem 
    .beaSysHasDisk.0

This command returns the following information about the object: 

Name: private.enterprises.bea.beaSystem.beaSysHasDisk.0
INTEGER: yes(2)

The following command sends a query to the SNMP agent running on the host named ruby, using public as the community for authorization. The agent retrieves the value of the managed objects sysDescr and sysUptime in the MIB. 

snmpget ruby public mgmt.mib.system.sysDescr.0 
    mgmt.mib.system.sysUpTime.0

This command returns the following information: 

Name: mgmt.mib.system.sysDescr.0
OCTET STRING- (ascii): Kinetics FastPath2
Name: mgmt.mib.system.sysUpTime.0
Timeticks: (2270351) 6:18:23

snmpgetnext

Purpose

Returns the next entry in a table or the next consecutive managed object in a MIB.

Synopsis

snmpgetnext [-d] [-p port] host community variable-name
   [variable-name ...]

Arguments

-d
Causes the program to display a message for each packet.

-p port
Specifies the port used to communicate with the SNMP agent (default: 161).

host
The internet address or host name of the node executing the SNMP agent to be queried.

community
The community name of the transaction.

variable-name
At least one unique object identifier (OID).

Description

You can enter one or more object identifiers as arguments on the command line. These names can be absolute, starting from the root of the tree, or relative to .iso.org.dod.internet. Read Chapter 2, "Agent Development Kit Overview," for more information on specifying object identifiers.

Environment Variables

BEA_SM_SNMP_MIBFILE
Must be set to specify the path to mib.txt, which provides an ASCII text description of your private MIB.

Examples

This example contacts the host named blueberry using the community name public and retrieves the value of the instance immediately following mgmt.mib.interfaces.ifTable.ifEntry.ifOutOctets.0 from the MIB: 

snmpgetnext blueberry public mgmt.mib.interfaces.ifTable.ifEntry
  .ifOutOctets.0

Note: The instance index .0 must be appended to the end of the OID to refer to the value of the object.

The output of the previous command might look like this: 

Name: mgmt.mib.interfaces.ifTable.ifEntry.ifOutOctets.1
COUNTER: 85655250

You could then enter a command that retrieves information about the next variable: 

snmpgetnext blueberry public mgmt.mib.interfaces.ifTable.ifEntry
  .ifOutOctets.1

snmptest

Purpose

Selectively performs get, getnext and set operations on any MIB object.

Synopsis

snmptest [-d] [-p port] host community

Arguments:

-d
Causes the program to display a message for each packet.

-p port
Specifies the port used to communicate with the SNMP agent (default: 161).

host
The internet address or host name of the node executing the SNMP agent to be queried.

community
The community name of the transaction.

Description

When this program is executed, it prompts you to enter an OID. The snmptest utility returns information about request and reply packets as well as the name and type of the object. Read Chapter 2, "Agent Development Kit Overview," for more information on specifying object identifiers.

By default, the program sends a GET request packet. This can be changed by entering a value from the following table at the prompt.

Command Request Type

$G

GET

$N

GETNEXT

$S

SET

If you choose the SET request mode, the program prompts you for a variable type from the following list.

Variable Type Description

a

IP address.

d

Octet string as decimal bytes separated by white space (i.e., 105 118 105 101 119)

i

Integer

n

Null value

o

Object identifier

s

Octet string in ASCII (i.e., bea)

t

Time ticks

x

Octet string as hexadecimal bytes separated by white space (i.e., 69 76 69 65 77)

After specifying the request type, the program prompts you to enter a value of the type you just specified. At this prompt, enter the integer (in decimal) or enter a string and press Return. To send the request packet, press Return again at the next prompt.

To quit the program, enter: 

$Q

Environment Variables

BEA_SM_SNMP_MIBFILE
Must be set to specify the path to mib.txt, which provides an ASCII text description of your private MIB.

Examples

Start the program by entering the command: 

snmptest topaz public

The program responds with: 

Please enter the variable name:

Enter a variable name and press Return: 

private.enterprises.bea.beaEm.beaEmMonitorTimer.0

The program requests another variable name: 

Please enter the variable name:

You can either enter another variable name, or press Return to see the result. When you press Return, the program displays the result of the test: 

Received GET RESPONSE from 192.84.232.47
requestid 0x775efba0 errstat 0x0 errindex 0x0
Name: private.enterprises.bea.beaEm.beaEmMonitorTimer.0
INTEGER: 5000

After displaying the result, you can enter another variable name, or $Q to quit the program. 

Please enter the variable name: $Q

If you enter $Q, a quit message displays: 

Quitting, Good-bye

snmptrap

Purpose

Sends an SNMP trap message to a host.

Synopsis

snmptrap [-a agent-addr] [-d] [-p port] host community trap-type
 specific-trap variable-binding-value

Arguments

-a agent-addr
Specifies an originating address, if different from the host, where snmptrap is executed. This allows you to send a trap on behalf of another host.

-d
Causes the program to display a message for each packet.

-p port
Specifies the port to which the SNMP trap should be sent on the target host (default is port 162).

host
The Internet address or name of the host to which the SNMP trap is to be sent.

community
The community name of the transaction.

trap-type
An integer that specifies the generic type (in the range 0 to 6) of the trap to be sent.

specific-trap
An integer that identifies the enterprise-specific trap that occurred when trap-type is set to generic trap type 6.

variable-binding-value
Information to be transported within the trap packet. The program uses this as the value in the variable binding list when it sends the trap.

Description

This table defines the valid (generic) trap types.

Name of
Trap Type 		Generic Trap Number Description

coldStart

0

The sending agent is re-initializing itself, typically due to a reboot.

warmStart

1

The sending agent is re-initializing itself, typically due to a normal restart.

linkDown

2

One of the communication links on the agent node has failed. The first element in the variable bindings contains the name and value of the ifIndex instance for the downed interface.

linkUp

3

One of the communication links on the agent node has come up. The first element in the variable bindings contains the name and value of the ifIndex instance for the affected interface.

authenticationFailure

4

The agent is reporting it has received a request with an invalid community specification or a community with insufficient permissions to complete the request.

egpNeighborLoss

5

The agent is reporting that the peer relationship between an External Gateway Protocol (EGP) neighbor and an EGP peer no longer exists.

enterpriseSpecific

6

The sending agent is reporting that an enterprise-specific event has occurred. The value of the specific-trap field indicates the nature of the event.

The trap generated by this tool has a fixed variable-binding list that contains only one object-value pair. The object is: 

.iso.org.dod.internet.private.enterprises.bea.beaSystem.
  beaTrapDescr.0

The value of this object may be specified in the variable-binding-value argument.

The enterprise field, which is part of the SNMP trap PDU header, is always: 

.1.3.6.1.4.1.140.1.1

Which is equivalent to: 

.iso.org.dod.internet.private.enterprises.bea.beaSystem.sysDescr

Read Chapter 2, "Agent Development Kit Overview," for more information about the SNMP trap PDU.

Examples

The following command sends a coldStart trap to the host named topaz, using public as the community for authorization. Note that a value for the specific-trap argument must be present, even though it is ignored when the value of the trap-type argument is not 6 (enterpriseSpecific). 

snmptrap topaz public 0 1 "host xyz is booting"

snmptrapd

Purpose

Receives and logs SNMP trap messages sent to the snmp-trap port.

Synopsis

snmptrapd [-d] [ -l port ] [-p]

Arguments

-d
Causes the program to display a debug message for each packet.

-l port
Specifies the port to use when listening for incoming trap packets (default is port 162).

-p
Causes the program to print trap information output to the standard output.

Environment Variables

BEA_SM_SNMP_MIBFILE
Must be used to specify the path to mib.txt, which provides an ASCII text description of your private MIB.

Description

This utility receives SNMP traps sent on the port specified by the -l argument. If no port is specified, it uses port number 162. This utility must be able to open the snmp-trap port, which usually requires root permissions.

On UNIX platforms, if the -p argument is not specified, snmptrapd uses the UNIX syslog utility to log messages with a status of WARNING. If the LOG_LOCAL0 facility is available, it is used instead of syslog or snmptrapd.

On machines running Windows NT, if the -p argument is not specified, the NT Event Log is used to log WARNING messages.

Examples

This command collects the incoming SNMP trap sent by another host, and displays it to standard output: 

snmptrapd -p

When the host receives the trap, it displays the following information: 

192.84.232.47: Cold Start Trap (0) Uptime: 0:00:00
Name: private.enterprises.bea. beaSystem.beaTrapDescr.0
OCTET STRING- (ascii): host xyz is booting

snmpwalk

Purpose

Traverses the OID tree using the SNMP getnext request to query managed objects.

Synopsis

snmpwalk [-d] [-p port] host community [variable-name  ...]

Arguments

-d
Causes the program to display a message for each packet.

-p port
Specifies the port used to communicate with the SNMP agent (default: 161).

host
The host name or an Internet address, in "dot-dot" notation (i.e., separated with periods), where the SNMP request is to be sent.

community
The community name to use in the SNMP request.

variable-name
This is the unique object identifier, expressed symbolically, decimally, or as a combination of both. If you do not specify a variable name, snmpwalk searches the entire MIB.

Description

This utility traverses the OID tree from the object specified on the command line. You can enter one or more object identifiers as arguments on the command line. These names can be absolute, starting from the root of the tree, or relative to .iso.org.dod.internet. Read Chapter 2, "Agent Development Kit Overview," for more information on specifying object identifiers. If no objects are specified, snmpwalk searches the entire MIB tree supported by the SNMP agent.

Environment Variables

BEA_SM_SNMP_MIBFILE
Must be used to specify the path to mib.txt, which provides an ASCII text description of your private MIB objects.

Diagnostics

If the tree search causes the program to search beyond the end of the MIB, this message is displayed: 

End of MIB

Examples

This is an example of an snmpwalk command: 

snmpwalk blueberry public private.enterprises.bea.beaSystem

This is some of the output generated from the command: 

Name: private.enterprises.bea.beaSystem.beaSysSysname.0 
  OCTET STRING- (ascii): SunOS
Name: private.enterprises.bea.beaSystem.beaSysNodename.0 
  OCTET STRING- (ascii):  blueberry

Agent Functions

There are three interfaces available that can be used to send an SNMP trap:

The simplest, but least flexible is sendtrap. This interface can only send enterprise-specific traps, but allows you to set the specific trap type and trap content. The trap host and community are taken from the beamgr.conf configuration file. The sendtrap function is actually a special case of the next interface, the snmptrap function.

The second interface, snmptrap, is more flexible, allowing you to specify an increased number of SNMP trap fields, but does not allow you to specify the variable binding list. A fixed variable (private.enterprises.bea.beaSystem.beaTrapDescr.0) is always sent as part of the trap. You can specify the value of this object as the trap description.

The third interface is the most powerful and flexible way of sending SNMP traps. Using the csam_trap_create, csam_trap_add_var_bind, and csam_trap_send functions, you can specify any part of an SNMP trap and include any number of variables in the variable binding list.

All of these interfaces are described in detail in this section.

Function Description

csam_get_keyword

Returns the value of a keyword

csam_set_keyword

Sets the value of a keyword.

csam_trap_add_var_bind

Specifies the variable binding list for an SNMP trap.

csam_trap_create

Creates the header portion of an SNMP trap.

csam_trap_send

Sends an SNMP trap to a host.

bea_sendtrap

Sends SNMP enterprise-specific traps only.

bea_snmptrap

Sends an SNMP trap.

csam_get_keyword

Purpose

Returns the value of a keyword

Synopsis

#include <asn1.h>

csam_get_keyword(keyword, value)
char *keyword;
char *value;

Arguments

keyword
The string to match against the first token of each record (maximum length, 40 characters).

value
A pointer to a buffer where a string of token(s) following the matched keyword is returned (maximum length, 200 characters).

Return Values

The csam_get_keyword function returns one of the following values:

SNMP_SUCCESS
This function has executed successfully.

SNMP_FAILURE
This function has not executed successfully.

Description

The csam_get_keyword function reads a record from the BEA Manager configuration file beamgr.conf (located in the /etc directory by default) based on the keyword passed to the function and returns the corresponding value. This function should be called only from the access functions or from the code which will be linked with the agent.

Each record in /etc/beamgr.conf is a newline-delimited keyword/value pair. A record can be continued on the next line by terminating the line with a backslash character. The backslash must be immediately followed by a newline character.

It is possible for multiple entries with the same keyword to exist in the beamgr.conf file. When the csam_get_keyword function is used with a specific keyword, it returns the value corresponding to the first matching entry in the file. Subsequent calls to csam_get_keyword with the keyword argument set to NULL retrieve the value corresponding to the next record matching the previously specified keyword. If there are no additional records that contain the previously specified keyword, the function fails, returning SNMP_FAILURE.

You need to make sure that the buffer pointed to by the value argument has sufficient space to store the returned value.

Environment Variables

BEA_SM_BEAMGR_CONF
May be used to specify the path to a BEA Manager configuration file (default: /etc/beamgr.conf).

csam_set_keyword

Purpose

Sets the value of a keyword.

Synopsis

#include <asn1.h>

csam_set_keyword(keyword, value)
char *keyword;
char *value;

Arguments

keyword
The string to match against the first token of each record (maximum length, 40 characters).

value
A pointer to a buffer where a string of tokens following the matched keyword will be returned (maximum length, 200 characters).

Return Values

The csam_set_keyword function returns one of the following values:

SNMP_SUCCESS
This function has executed successfully

SNMP_FAILURE
This function has not executed successfully.

Description

The csam_set_keyword function sets the value of a keyword in the BEA Manager configuration file, beamgr.conf (located by default in /etc), and returns the corresponding value. This function should be called only from the access functions or from the code which will be linked with the agent.

Each record in /etc/beamgr.conf is a newline-delimited keyword/value pair. A record can be continued on the next line by terminating the line with a backslash character. The backslash must be immediately followed by a newline character.

Note: It is possible for multiple entries with the same keyword to exist in the beamgr.conf file. The csam_set_keyword function only sets the first instance of a specific keyword.

You need to make sure that the buffer pointed to by the value argument has sufficient space to store the returned value.

Environment Variables

BEA_SM_BEAMGR_CONF
May be used to specify the path to a BEA Manager configuration file (default: /etc/beamgr.conf).

csam_trap_create

Purpose

Creates the header portion of an SNMP trap.

Synopsis

#include <stdio.h>
#include <snmp_user.h>
int csam_trap_create (community, EnterpriseOID, EnterpriseOIDLen,
    trapID, specificTrapID, agentAddr)
char *community;
oid *EnterpriseOID;
int EnterpriseOIDLen;
int trapID;
int specificTrapID;
char *agentAddr;

Parameters

community
A pointer to the SNMP community name.

If the community parameter is NULL, the community defined in the TRAP_HOST entry in the beamgr.conf file is used. If beamgr.conf cannot be located or the TRAP_HOST entry is not defined in beamgr.conf, public is used as the default.

EnterpriseOID
The enterprise specific OID.

If the EnterpriseOID is a NULL pointer, then the OID defined in the SYSOBJID entry in the beamgr.conf file is used. If the beamgr.conf file cannot be located or SYSOBJID entry is not defined in the beamgr.conf file, then the default enterprise specific OID (.1.3.6.1.4.1.140.1.1) is used. This number is the BEA Systems enterprise specific OID.

EnterpriseOIDLen
The length of the EnterpiseOID in the sub-OID.

trapID
A pointer to the generic trap type, an integer in the range 0 to 6. The meaning of these trap types is described in Table 3-1.

specificTrapID
This should contain a meaningful number if trapID is set to 6.

agentAddr
The host name of the system purportedly sending this trap.

Return Values

The csam_trap_create function returns one of the following values:

CSAM_NOT_RIGHT_STATE
This function has been used in an incorrect order.

CSAM_INTERNAL_ERR
There has been an internal error.

CSAM_SUCCESS
This function has executed successfully.

Description

This function can be used to create the header of an SNMP trap within an agent program or other application. The csam_trap_add_var_bind function is used to specify the variable binding list of the trap and the csam_trap_send function is used to send the trap.

The value of the trapID parameter indicates one of the following (generic) trap types.

Table 3-1 Generic Trap Ids
Name of
Trap Type 		Generic Trap Number Description

coldStart

0

The sending agent is re-initializing itself, typically due to a reboot.

warmStart

1

The sending agent is re-initializing itself, typically due to a normal restart.

linkDown

2

One of the communication links on the agent node has failed. The first element in the variable bindings contains the name and value of the ifIndex instance for the downed interface.

linkUp

3

One of the communication links on the agent node has come up. The first element in the variable bindings contains the name and value of the ifIndex instance for the affected interface.

authenticationFailure

4

The agent is reporting it has received a request with an invalid community specification or a community with insufficient permissions to complete the request.

egpNeighborLoss

5

The agent is reporting that the peer relationship between an External Gateway Protocol (EGP) neighbor and an EGP peer no longer exists.

enterpriseSpecific

6

The sending agent is reporting that an enterprise-specific event has occurred. The value of the specific-trap field indicates the nature of the event.

If any other number is given, it is treated as 6, and a value of 90000 is used in place of specificTrapID.

If the value of the agentAddr parameter is NULL, the name of the host where the program using this function is used. This argument can be set to some other value, allowing an agent program to send a trap on behalf of another host.

Example

The following example creates the trap PDU header with a trap community name of public, generated on a host named bigguy: 

if (( ret = csam_trap_create("public" /* Community  */
               ,bea /* Enterprise OID               */
               ,7   /* Length of the enterprise OID */
               ,6   /* Generic trap ID              */
               ,123 /* Specific trap ID             */
               ,"bigguy" /*Host that generates trap */
               )) != CSAM_SUCCESS)
       printf("Trap Create Failed with Error %d\n", ret);

A generic trap ID of 6 identifies this trap as an enterprise-specific trap. The length of the enterprise OID is the number of nodes in the path to the object from the root of the OID tree.

csam_trap_add_var_bind

Purpose

Specifies the variable binding list for an SNMP trap.

Synopsis

#include <stdio.h>
#include <snmp_user.h>

int csam_trap_add_var_bind(type, oidptr, oid_len, value, value_len)
int type;
oid *oidptr;
int oid_len;
union obj_val value;
int value_len;

Parameters

type
The type of the object.

oidptr
The OID of the object being sent.

oid_len
The number of nodes in the absolute path from root.

value
The value of the object. It is of the obj_val union type as defined in the file snmp_user.h.

value_len
The length of the value parameter.

Return Values

The csam_trap_add_var_bind function returns one of the following values:

CSAM_NOT_RIGHT_STATE
This function has been used in an incorrect order.

CSAM_WRONG_TYPE
The type argument is not valid.

CSAM_INTERNAL_ERR
There has been an internal error.

CSAM_SUCCESS
This function has executed successfully.

Description

After the csam_trap_create function has been called, this function can be called one or more times.

The type parameter must have one of the following values.

Type value_len

OPAQUE

Length in bytes

STRING

Length in bytes

IPADDRESS

Length in bytes

OBJID

Number of nodes in the absolute OID path

INTEGER

Ignored

COUNTER

Ignored

GAUGE

Ignored

TIMETICKS

Ignored

Examples

The following example adds an integer value to the variable bindings of a trap PDU: 

value.int_val = 812;
if ( (ret = csam_trap_add_var_bind(INTEGER /*Object type    */
               ,oid1 /* OID of the object                   */
               ,10   /* Length of the OID                   */
               ,value /* Object value                       */
               ,sizeof(int) /* Size of the object value     */
               )) != CSAM_SUCCESS)
     printf("Add to Trap Var Bind Failed with Error %d\n", ret);

The length of the value is not significant in the case of integer values. The length of the OID is the number of nodes from root to the specified object in the path through the OID tree. In the next example, a string value is added to the trap variable bindings: 

trap_str_val = "Device is not responding";
value.str_val = trap_str_val;
if (( ret = csam_trap_add_var_bind(STRING, oid2, 10, value,
              strlen(trap_str_val) /*Length of value in bytes */
              )) != CSAM_SUCCESS)
      printf("Add to Trap Var Bind Failed with Error %d\n", ret);

In the following example, an object identifier is added to the trap variable bindings: 

value.oid_val = trap_oid_val;
if (( ret = csam_trap_add_var_bind(OBJID, oid3, 10, value,
                9  /* Length of the object */
                )) != CSAM_SUCCESS)
      printf("Add to Trap Var Bind Failed with Error %d\n", ret);

The length of the OID is nine in this case.

csam_trap_send

Purpose

Sends an SNMP trap to a host.

Synopsis

#include <stdio.h>
#include <snmp_user.h>
int csam_trap_send( hostname, port )
char *hostname;
int port;

Parameters

hostname
The host to which the trap is sent.

port
The UDP port to which this trap is sent.

Return Values

 The csam_trap_send function returns one of the following values:

CSAM_NOT_RIGHT_STATE
This function has been used in an incorrect order.

CSAM_GETHOSTNAME_FAILED
Invocation of gethostname to determine current host name failed.

CSAM_ASN_ENCODING_FAILED
ASN.1 encoding failed.

CSAM_SOCKET_OP_FAILED
Socket operation failed.

CSAM_BIND_OP_FAILED
Bind operation failed.

CSAM_HOST_NOTOK
The host name to which the trap is being sent is not valid.

CSAM_SENDTO_FAILED
Send failed.

CSAM_INTERNAL_ERR
There has been an internal error.

CSAM_SUCCESS
Function executed successfully.

Description

This function must be called after the csam_trap_create and csam_trap_add_var_bind functions.

If the hostname argument is NULL, the host name specified by the TRAP_HOST entry in the beamgr.conf is used. If beamgr.conf cannot be located, or the TRAP_HOST entry is not defined, the local host name is used. If there are multiple TRAP_HOST entries, the trap will be sent to each host specified in all TRAP_HOST entries.

If the port argument is 0, the port number specified by the TRAP_HOST entry in the beamgr.conf file is used. If beamgr.conf cannot be located, or the TRAP_HOST entry is not defined, the standard SNMP trap port 162/udp is used.

Example

In the following example a trap is sent to the host comet on port 162: 

if (( ret = csam_trap_send("comet"  /* Name of destination host */
                     ,162   /* Destination port number          */
                     )) != CSAM_SUCCESS )
     printf("Trap Send Failed with Error %d\n", ret);

The destination host name is the name of a machine running an SNMP manager or an SNMP trap daemon, or the BEA snmptrapd utility.

bea_sendtrap

Purpose

Sends an SNMP trap.

Synopsis

#include <snmp_user.h>
int bea_sendtrap (specificType, trapDesc)
int specificType;
char *trapDescr;

Parameters

specificType
Because the generic trap type is enterprise-specific, this parameter identifies more accurately the type of trap.

*trapDescr
A pointer to some data describing the trap. This parameter is always transmitted in the MIB object:

private.enterprises.bea.beaSystem.beaTrapDescr.0

Return Values

The bea_sendtrap function returns one of the following values:

SNMPERR_NOERR
No error occurred.

SNMPERR_CANNOT_OPEN
Cannot open SNMP port.

SNMPERR_CANNOT_SEND
Cannot send SNMP packet.

SNMPERR_CANNOT_OPEN_CONF_FILE
Cannot open the SNMP configuration file to read the host name (TRAP_HOST entry) that receives the trap. The default file is /etc/beamgr.conf or is defined by the environment variable BEA_SM_BEAMGR_CONF.

SNMPERR_INVALID_PARAMS
Invalid parameters were passed.

Description

The bea_sendtrap function takes an integer and a character pointer as input. All other SNMP trap fields are predefined. It is a specific case of snmptrap, in which the gateway and the community are extracted from the beamgr.conf file and the trap type is 6 (i.e., enterprise-specific).

The trapDescr pointer is always transmitted in the MIB object: 

private.enterprises.bea.beaSystem.beaTrapDescr.0

The trap is sent on the standard SNMP trap port 162/udp.

Example

In the following example, an enterprise-specific trap is sent to the host name specified by the TRAP_HOST keyword in the beamgr.conf configuration file: 

if (( ret = bea_sendtrap(2244  /* Specific Trap ID        */
               ,"ZYZ queue is clogged" /* Trap description */
               )) != SNMPERR_NOERR )
       printf("Trap Send Failed with Error %d\n", ret);

bea_snmptrap

Purpose

Sends an SNMP trap.

Synopsis

#include <snmp_user.h>
int bea_snmptrap ( gateway, community, trapType, specificType,
   trapDesc, agentAddr )
char *gateway, *community, *trapType, *specificType, *trapDescr,
   *agentAddr;

Parameters

gateway
A pointer to the address of the host where the trap is to be sent. It can be a host name or an IP address in the "dot-dot" notation.

community
A pointer to the SNMP community name.

trapType
A pointer to the generic trap type.

specificType
A pointer to a specific trap type. It is applicable only for enterprise-specific trap type, (i.e., generic trap type 6). It is present even if the generic trap type is not enterprise-specific.

trapDescr
A pointer to some data describing the trap.

agentAddr
The name or the IP address of the host that is assumed to send the SNMP trap. If it is passed as NULL, the local host name is used.

All parameters are essential. This function has no defaults.

Return Values

The bea_snmptrap function returns one of the following values:

SNMPERR_NOERR
No error occurred.

SNMPERR_CANNOT_OPEN
Cannot open SNMP port.

SNMPERR_CANNOT_SEND
Cannot send SNMP packet.

SNMPERR_CANNOT_OPEN_CONF_FILE
Cannot open the SNMP configuration file.

BEA_SNMPERR_INVALID_PARAMS
Invalid parameters were passed.

Description

trapDescr is always sent as the value of the same predefined object. It is always transmitted in the MIB object: 

private.enterprises.bea.beaSystem.beaTrapDescr.0

The trap is sent on the standard SNMP trap port 162/udp.

Examples

The sample program snmp_appl.c that makes use of this function (and a sample makefile for use with snmp_appl.c) can be found in the $RELEASE_ROOT/agent_src/agentlib directory.