# 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," lists the tools and functions available with the Agent Development Kit and provides general information about the Agent Development Kit software.

- "Agent Tools," describes the tools included with the Agent Development Kit software.

- "Agent Functions," describes the library of functions available to the programmer for use in creating SNMP agents.

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

- Build an agent or subagent that supports a management information base (MIB).

- Query objects via your SNMP agent.

- Generate SNMP traps from your agent.

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:

- `sendtrap`

- `snmptrap`

- Combined use of `csam_trap_create`, `csam_trap_add_var_bind`, and `csam_trap_send`

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.