snmp_trap_receive()
Return PATROL SNMP event traps.
Syntax
Parameter
Parameter | Definition |
|---|---|
flags | binary flags that control the actions of the snmp_trap_receive() function*Valid Values* |
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 |
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*
|
valuen | value of objectidn |
Each return variable consisting of an objectidn, typen, 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:
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
}