int pmStore(const pmResult *result)
int pmRequestStore(int ctx, const pmResult *result)
int pmReceiveStore(int ctx)
cc ... -lpcp
DESCRIPTION
In some special cases it may be helpful to modify the current values of
performance metrics,
e.g. to reset a counter to zero, or to modify a ``metric'' which is a control
variable for some agent collecting performance metrics.
The routine
pmStore
is a lightweight inverse of
pmFetch(3).
The caller must build the
pmResult
data structure (of course, this could have been returned from an earlier
pmFetch(3)
call) and then call
pmStore.
It is an error to pass a request to
pmStore
in which the
numval
field within any of the
pmValueSet
structure has a value less than one.
The current
Performance Metrics Application Programming Interface (PMAPI)
context must be one with a host as the source of metrics, and the
current value of the nominated metrics will be changed, i.e.
pmStore
cannot be used to make retrospective changes to information in either
the archive logs, or in the recent past for real-time sources of metrics.
The return code from
pmStore
is zero for success.
pmRequestStore and pmReceiveStore are used by
applications which must communicate with the PMCD asynchronously.
These functions take explict context handle ctx which must refer
to a host context (i.e. created by passing PM_CONTEXT_HOST to
pmNewContext). pmRequestStore sends request to store data in
result in the metrics and returns without waiting for the response,
pmReceiveStore reads confirmation from PMCD. It is the responsibility
of the application to make sure the data are ready before calling
pmReceiveStore to avoid blocking.
At least one of the modifications was rejected.
No other status is available
from below the PMAPI (this is the lightweight part of the functionality!). In
cases where the outcome of
pmStore
for individual metrics is important, the caller should make one call to
pmStore
for each metric. On the other hand, a bulk modification can be performed in a
single
pmStore
call for situations in which the outcome is not critical.
PM_ERR_NOTHOST
The current PMAPI context is an archive rather than a host, or it
is a host that is not set to the current time, i.e. has been ``rewound''
to the recent past using
pmSetMode(3).
PM_ERR_TOOSMALL
The number of metrics specified in
result
is less than one.
PM_ERR_VALUE
One or more of the
pmValueSets
in
result
has a
numval
field with a value less than one.
PM_ERR_CTXBUSY
Context is currently in use by another asynchronous call.