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.