# pmstore

## NAME



           **pmStore** - modify values of performance metrics
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
    
           **int pmStore(const pmResult ***_result_**);**
    
           **cc ... -lpcp**
    


## DESCRIPTION



           In some special cases it may be helpful to modify the current val‐
           ues 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.
    
           **pmStore** is a lightweight inverses of pmFetch(3).
    
           The caller must build the _result_ data structure (of  course,  this
           could have been returned from an earlier pmFetch(3) call).
    
           It  is  an  error  to pass a _result_ to **pmStore** in which the _numval_
           field within any of the **pmValueSet** structures  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  in‐
           formation  in either the archives, or in the recent past for real-
           time sources of metrics.
    
           The return code from **pmStore** is zero for success.
    


## DIAGNOSTICS



           **PM_ERR_GENERIC**
                  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 storing into individual metrics is impor‐
                  tant, the caller should make one call to either **pmStore** for
                  each metric.  On the other hand, a bulk modification can be
                  performed in a single call for situations in which the out‐
                  come 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 _pmValueSet_ s in _result_ has a _numval_ field
                  with a value less than one.
    


## COMPATIBILITY



           Prior to PCP 7.0 the _timestamp_ field in the pmResult struct was a
           struct timeval.  To support PMAPI transition, the old interface
           and semantics can be used if applications are recompiled with
           **-DPMAPI_VERSION=2**.
    
           For a time in PCP 6.x there was a routine with the same semantics
           as the current **pmStore** called **pmStoreHighRes** , and a struct with
           the same definition as the current pmResult struct called pmRe‐
           sultHighRes, although both are now deprecated and compile-time
           support for **pmStoreHighRes** and pmResultHighRes will be removed in
           a future release.
    


* * *