netmgt_request_events manual page
Table of Contents
NAME
netmgt_request_events - request event reports from an agent
SYNOPSIS
struct timeval *
netmgt_request_events(agent_host, agent_prog, agent_vers, rendez_host, rendez_prog, agent_vers, count, interval, timeout, flags)
- char
- *agent_host;
- u_long
- agent_prog;
- u_long
- agent_vers;
- char
- *rendez_host;
- u_long
- rendez_prog;
- u_long
- rendez_vers;
- u_int
- count; struct timeval interval; struct timeval timeout;
- u_int
- flags;
DESCRIPTION
netmgt_request_events sends a request to an agent to watch for interesting events on specific attributes. The caller must have previously called netmgt_set_instance(3n) to define the system, group, and optional key of the request, and netmgt_set_threshold(3n) to define the threshold and relation parameters of the request. If any agent-specific options are to be set, the caller must have previously called netmgt_set_argument(3n).
The request is sent to the agent process on agent_host with RPC program number agent_prog and RPC version number agent_vers.
An event report is sent when the infix expression
<attribute value> <relational operator> <threshold value>
is TRUE.
If an event occurs, an event report will be sent to the rendezvous on rendez_host with RPC program number rendez_prog and RPC version number rendez_vers.
INPUT ARGUMENTS
agent_host
host where the agent runs.
agent_prog
agent's RPC program number.
agent_vers
agent's RPC version number.
rendez_host
host where the rendezvous runs.
rendez_prog
rendezvous' RPC program number.
rendez_vers
rendezvous' RPC version number.
count
maximum number of data reports wanted. An event report may be sent up to count times, once per interval, but only if an event occurs. Otherwise no report is sent. If count is zero, event reporting will continue until the agent is told to stop.
interval
reporting interval. If an event has not occurred when the report is scheduled to be sent, no report will be sent.
If interval is zero, the agent will use its own default interval.
timeout
maximum time to wait for confirmation from the agent before the call fails.
flags
request options flags. Three flags are currently defined:
- NETMGT_SEND_ONCE
- Have the agent terminate after one event report has been sent. If this flag is not set, the agent continues to conditionally send event reports until otherwise directed. By default, this flag is not set.
- NETMGT_RESTART
- Restart the request if the agent abnormally terminates and is restarted. Otherwise, when the agent restarts, this request is forgotten. This flag is advisory; request restart is not guaranteed. The restart is not attempted until the agent parent is started (asked to start another request, or asked what requests it is working on), when all requests marked for restart will be restarted, if possible. By default, this flag is not set.
- NETMGT_DO_DEFERRED
- Have the agent collect the event but don't send it just yet. In many cases, an agent collects useful information for debugging problems, but the information isn't useful under normal conditions. If the manager started the request only after the error condition started, it would have been started after the fact, and valuable data would have been lost. On the other hand, if the request was started and the event reports were continually streaming back to the manager before the error condition occurred, an unnecessary traffic and CPU load would be caused from lots of uninteresting event reports coming back. With this flag, data reports can be held on the agent's system until the manager is ready (if ever) to ask for them. When the manager asks via a call to netmgt_request_deferred(3n) for the collected reports, the ``old'' reports will be sent. This option (as well as netmgt_request_deferred(3n) ) is handled transparently for the agent by the Agent Services library. The library keeps only the last 32 reports the agent ``sent,'' memory permitting. By default, this flag is not set.
RETURN VALUE
Timestamp of the request, if successful, otherwise NULL.
DIAGNOSTICS
If NULL is returned, global variable netmgt_error indicates the error. The caller can get the reason for the error with netmgt_fetch_error(3n).
SEE ALSO
- netmgt_fetch_error(3n),
- netmgt_request_deferred(3n),
- netmgt_set_argument(3n),
- netmgt_set_instance(3n), netmgt_set_threshold(3n)
NOTES
Deferring event reports is a dubious activity.
Table of Contents