[Top] [Prev] [Next] [Bottom]

3 - Getting Data, Event, and Trap Reports

When you registered for data or event/trap reports, one parameter you specified was the function to handle incoming reports. Each time an event or data report comes in, your report-handling function is called with the following arguments:

u_int type

report type--either NETMGT_DATA_REPORT, NETMGT_EVENT_REPORT, NETMGT_TRAP_REPORT, or NETMGT_ERROR_REPORT .
char *target
name of the target system where the managed element resides.
char *group
name of the group whose attribute values are being reported.
char *key
unique row identifier for tables. An instance of the group on the managed system. This is used if a key was specified.
u_int count
the reporting count.
timeval interval
the reporting interval.
u_int flags
report flags.
The count and interval parameters are generally unused. They are provided if your application needs them.

The group identifies the collection of object attributes being reported by the agent.

3.1 Message Information

Once you get called, you'll want to find out who sent the report. Call netmgt_fetch_msginfo(3n). The information returned contains items like the RPC program number of the agent who sent the report and the timestamp identifying the request (more about request identification when we discuss sending requests).

An additional piece of information returned by netmgt_fetch_msginfo(3n) is a status code from the agent. It is usually NETMGT_SUCCESS, but could be NETMGT_WARNING or NETMGT_FATAL (or something else), in which case you need to find out more. Chapter 6, "Handling Error Reports ," explains the procedures for handling error conditions.

Now you know who sent you the report. The type field tells you what type of report was sent--either NETMGT_DATA_REPORT, NETMGT_EVENT_REPORT , NETMGT_TRAP_REPORT, or NETMGT_ERROR_REPORT. The first three are discussed below. Error reports are discussed in Chapter 6, "Handling Error Reports ."

3.2 Data Reports

If you received a data report, you need to cycle through the data statistics in the report by calling netmgt_fetch_data (3n) with a pointer to a local buffer of type Netmgt_data. Each time you call, your buffer will be filled in with the attribute's <name> , <type>, <length>, and <value> . The type is a standard C type, listed in netmgt_arglist.h , which describes the format of <value>.

NOTE - Agents that report tables can immediately follow NETMGT_ENDOFROW with NETMGT_ENDOFARGS . You need to check for this so you don't process a "blank" row.
The first time you call netmgt_fetch_data (3n) after getting a data report, you get the first data statistic in the report. Each successive call gets another data statistic. Two sentinel statistics are possible--if <name> is NETMGT_ENDOFROW, you've just hit the end of a row of a table. You might need this information to format your output report. The second sentinel you might get is a <name> of NETMGT_ENDOFARGS, which signals the end of the data report.

If the flags parameter contains the bit NETMGT_LAST, this is the last data report the agent is scheduled to send, and it is about to exit because it has finished its assigned task.

3.3 Event Reports

If you received an event report, cycle through the event statistics with netmgt_fetch_event(3n). The usage of this call is similar to netmgt_fetch_data(3n) except you provide it a pointer to a local buffer of type Netmgt_event. On return, the buffer is filled in with the usual <name>, <type> , <length>, and <value> fields, but three additional fields are present: <relop>, <thresh_val> , and <priority>.

Each of these three fields was set by the manager making the request. <relop> is the relational operator (defined in netmgt_arglist.h) that triggered the event on this attribute. If this attribute did not cause the event report, the field will be set to NETMGT_NOP. <thresh_val> is the value of the threshold. It has the same internal representation as <value> . Finally, <priority> is the "severity" of the report, one of NETMGT_LOW_PRIORITY, NETMGT_MEDIUM_PRIORITY , or NETMGT_HIGH_PRIORITY.

While cycling through the event statistics, it is possible to get the two sentinel values NETMGT_ENDOFROW and NETMGT_ENDOFARGS, just as with data reports.

If the flags parameter contains the bit NETMGT_LAST, this is the last event report the agent is scheduled to send, and it is about to exit because it has finished its assigned task.

It's possible for an agent to finish its processing but not have any events to send. You will be notified by a special event report with the NETMGT_NO_EVENTS bit set in the flags parameter.

3.4 Trap Reports

Even though you register with the event dispatcher to receive traps, traps are returned in data report format. This is because traps do not contain any threshold information. Therefore, to fetch attributes from a trap, call netmgt_fetch_data(3n).

The attributes returned in a trap are specific to each trap generator. SNMP is one entity that generates traps.

The attributes returned by the SNMP trap proxy consist of a fixed set of attributes, followed by an ENDOFROW indication, following by zero or more trap-specific attributes.

The fixed set of attributes are listed in Table 3-1 .

Table  3-1 SNMP Trap Attributes
Attribute Name
 		Type
 		Description

sequence  

unsigned long  

sequence number of the trap  

receive-time  

unixtime  

time trap was received by proxy  

version  

unsigned long  

version returned by the device  

community  

string  

community string in SNMP trap  

enterprise  

object id  

enterprise in the SNMP trap  

source time  

timeticks  

time since device was booted  

trap type  

string  

name of the trap  


3.5 Printing Data

Converting the attribute <value> to a printable entity is straightforward for most <type> definitions. One <type>, NETMGT_OBJECT_IDENTIFIER , is not as straightforward. This type is defined by Internet standard RFC 1065 for SNMP and by International Standards Organization for OSI, and in printed form looks like a string of numbers separated by dots.

The Manager Services library function netmgt_oid2string(3n) converts an object identifier--stored as an array of unsigned long integers--to a printable character string in "dot notation." You should use this function when converting object identifiers to a printable format.

3.6 Summary

This isn't as complicated as it might seem at first. To summarize, your report handling routine needs to do the following:

1. call netmgt_fetch_msginfo (3n) to get additional message information.


2. call netmgt_fetch_data (3n) or netmgt_fetch_event(3n) to fetch individual attribute statistics.


3. optionally format the report.

3.7 Sample Code

The following code fragment is an example of a routine that handles event reports. Note that the print functions are not defined here: they can be found in the complete program example from which this fragment is taken, which is included in the product structure in the file event_display.c in the API_examples directory. 










void report_handler(u_int type, char *target, char *group, char *key,




        u_int count, struct timeval interval, u_int flags)




{







Netmgt_msginfo  msginfo;                /* report message information */







        printf("report_handler: called\n");







        /* Get additional report message information. */




        if (!netmgt_fetch_msginfo(&msginfo)) {




                NETMGT_DBG("can't fetch message information: %s\n",




                    netmgt_sperror());




                return;




        }




        printf("IP address of the requesting manager : %s\n",




                inet_ntoa(msginfo.manager_addr));




        printf("IP address of the responding agent: %s\n",




                inet_ntoa(msginfo.agent_addr));







        if (flags & NETMGT_NO_EVENTS) {




                (void) printf("(last report from agent [got NETMGT_NO_EVENTS])\n");




                my_exit(NO_EVENT);




        }







        switch (type) {




        case NETMGT_ERROR_REPORT :




                print_agent_error();




                break;







        case NETMGT_DATA_REPORT:




                printf("report handler: data report\n");




                break;







        case NETMGT_TRAP_REPORT:




                printf("report handler: trap report\n");




                show_trap();




                break;




 




        case NETMGT_EVENT_REPORT:




                printf("report handler: event report\n");




                show_event();




                break;


 



 

















        default:




                printf("report handler: unknown report\n");




 




        }




 




        if (flags & NETMGT_LAST) {




                (void) printf ("(last report from agent) \n");




                my_exit(LAST_REPORT);




        }




 




}




 




void




show_trap()




{




Netmgt_data     trap;                   /* data-report buffer */




char *s;




 




        strcpy(trap.name, "!a!");




        while (strcmp(trap.name, NETMGT_ENDOFARGS)) {




                if (!netmgt_fetch_data(&trap)) {




                        NETMGT_DBG1("can't fetch trap statistics\n");




                        print_agent_error();




                }




 




                if (!strcmp(trap.name, NETMGT_ENDOFROW)) {




                        (void) printf("(end of row) \n\n");




                        continue;




                }




 




                if (!strcmp(trap.name, NETMGT_ENDOFARGS)) {




                        (void) printf( "(end of report) \n\n");




                        continue;




                }




 







                


 



 

















                /* print the received information */




                if (s = value2str(trap.type, trap.value, trap.length)) {




                        (void) printf ("%s = %s", trap.name, s);




                } else {




                        (void) printf("%s : has an UNKNOWN type \n",




                            trap.name, trap.type);




                }




 




                (void) printf("\n");




        }




 




}




void




show_event()




{




Netmgt_event    event;                  /* event-report buffer */




char *s;




 




 




        strcpy(event.name, "!a!");




        while (strcmp(event.name, NETMGT_ENDOFARGS)) {




                if (!netmgt_fetch_event(&event)) {




                        NETMGT_DBG1("can't fetch event statistics\n");




                        print_agent_error();




                }




 




                if (!strcmp(event.name, NETMGT_ENDOFROW)) {




                        (void) printf("end of row) \n\n");




                        continue;




                }




 




                if (!strcmp(event.name, NETMGT_ENDOFARGS)) {




                        (void) printf( "(end of report) \n\n");




                        continue;




                }







                /* print the received information */




                if (s = value2str(event.type, event.value, event.length)) {




                        (void) printf ("%s = %s", event.name, s);




 




 


 



 

















                        if (event.relop != NETMGT_NOP) {




                                s = value2str(event.type, event.thresh_val,




                                    event.length);




                                (void) printf("   (%s %s Priority %s)",




                                    relop2str(event.relop), s,




                                    prio2str(event.priority));




                        }




                } else {




                        (void) printf("%s : has an UNKNOWN type \n",




                            event.name, event.type);




                }




 




                (void) printf("\n");




        }




 




}


 

[Top] [Prev] [Next] [Bottom]

Copyright 1996 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA 94043-1100 USA. All Rights Reserved