Important

   

This documentation space contains information about PATROL Agents when deployed in a TrueSight Operations Management environment. If you are a BMC Helix Operations Management user, see PATROL Agent 22.1 for BMC Helix Operations Management. Open link

snmp_trap_receive()

Return PATROL SNMP event traps.

Syntax

snmp_trap_receive([flags])

Parameter

Parameter

Definition

flags

binary flags that control the actions of the snmp_trap_receive() function*Valid Values* 
0 neither ranges 1 nor 2 applies 
1 print the trap information in a formatted output 
2 don't block the current process waiting for an SNMP event trap (that is, poll for the trap) 
3 both flags 1 and 2 apply 
4 return the full trap information including the trap specific id and community string*Default* 
0

Description

The snmp_trap_receive() function returns a formatted string containing information about the first accumulated trap (if any). Only one snmp_trap_receive() function may be active on a PATROL Agent. 

The snmp_trap_receive() function returns the NULL string and sets the PSL errno variable as follows:

  • E_PSL_SNMP_NOT_LISTENING (numeric value 99) if there is no active socket established by a prior snmp_trap_listen() function
  • E_PSL_SNMP_ALREADY_LISTENING (numeric value 98) if there is already an active snmp_trap_receive() function active against the PATROL Agent.

Blocking snmp_trap_receive() Function

If the snmp_trap_receive() function is specified as blocking, it blocks the current process until one of the following occurs:

  • A snmp_trap_ignore() function from another PSL process ends trapping.
  • The socket established by the snmp_trap_listen() function receives an SNMP trap.

In the first case, the snmp_trap_listen() function returns the NULL string. In the second case, snmp_trap_listen() unblocks the current process and returns the trap.

Nonblocking snmp_trap_receive() Function

If the snmp_trap_receive() function is specified as nonblocking, it queries the socket established by the snmp_trap_listen() function and returns any trap waiting there or the NULL string indicating that no trap was waiting.

Default Trap Format

The snmp_trap_receive() function returns a trap as a character string. The format of the return string depends on flags specified:

  • The default format for the string ( flags = 0) is as follows: 

    address enterprise subid uptime\n
    objectid1 type1 value1\n
    . . .
    objectidn typen valuen\n

The traptype is not returned when the flags parameter is set to 0.

  • The format for the string when flags = 1 or 3 is as follows: 

    address enterprise traptype subid uptime\n
    objectid1 type1 value1\n
    . . .
    objectidn typen valuen\n
  • The format for the string when flags = 4 is as follows: 

    address enterprise traptype specific_id uptime community\n
    objectid1 type1 value1\n
    . . .
    objectidn typen valuen\n

Field

Definition

address

address of the SNMP agent that sent the trap

enterprise

enterprise object identifier for the SNMP agent

traptype

SNMP trap type as defined in RFC 1213 (only returned when flags = 1 or 3) 

Valid Values 
0-5 standard traps 
6 enterprise trap

specific_id

specific id of the SNMP trap

subid

identifier number for the trap

uptime

number of clock ticks that the SNMP agent has been active A clock tick is hardware-dependent and for Unix systems is typically between 10 and 20 milliseconds.

community

community string of the SNMP trap

objectidn

character string SNMP object identifier for the returned variable

typen

character string indicating the objectidn type*Valid Values*

  • integer
  • string
  • oid
  • null
  • counter
  • gauge
  • timeticks
  • ipaddress

valuen

value of objectidn

Each return variable consisting of an objectidntypen, and valuen triplet is separated by spaces and terminated by a newline character. This format is identical to the second snmp_trap_send() function format type. Output from the snmp_trap_receive() function can be piped to the snmp_trap_send() function without modification.

Example

The following is an example of the snmp_trap_receive() function:

myhost = get("/hostname");
if (index(snmp_trap_register_im("","list"),myhost) == 0) {
# host not currently registered to receive traps
opstatus = snmp_trap_register_im(myhost,"add");
if (opstatus != "OK") {
# registration failed -- exit
exit;
}
# at this point, it is OK to receive traps
snmp_trap_receive(2); # 2 is non-blocking
} else {
snmp_trap_receive(2); # 2 is still non-blocking
}
Was this page helpful? Yes No Submitting... Thank you

Comments