NAME

netmgt_request_data - request data reports from an agent

SYNOPSIS

struct timeval *

netmgt_request_data(agent_host, agent_prog, agent_vers,
                        rendez_host, rendez_prog, rendez_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_data sends a request to an agent for a specific group's attribute values. The caller must have previously called netmgt_set_instance(3N) to define the system, group, and optional key 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. The agent will report its collected data to the rendezvous process 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 reports wanted. If count is zero, the agent will send reports until it is told to stop.

interval reporting interval. 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 option flags. Two flags are currently defined:

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 data 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 data 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 data 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)