# pmstore

## NAME



           **pmstore** - modify performance metric values
    


## SYNOPSIS



           **pmstore**[**-fFLV?**]  [**-D** _debug_] [**-h** _host_] [**-i** _instances_] [**-K** _spec_]
           [**-n** _pmnsfile_] _metricname value_
    


## DESCRIPTION



           Under certain circumstances, it is useful to be able to modify the
           values of performance metrics, for example to re-initialize
           counters or to assign new values to metrics that act as control
           variables.
    
           **pmstore** changes the current values for the nominated instances of
           a single performance metric, as identified by _metricname_ and the
           list of instance identifiers following the **-i** argument.  _instances_
           must be a single argument, with elements of the list separated by
           commas and/or white space.  By default all instances of _metricname_
           will be updated.
    
           Normally **pmstore** operates on the default Performance Metrics Name
           Space (PMNS), see PMNS(5), however if the **-n** option is specified
           an alternative namespace is loaded from the file _pmnsfile_.
    
           Unless directed to another host by the **-h** option, **pmstore** will
           interact with the Performance Metric Collector Daemon (PMCD) on
           the local host.
    
           The **-L** option causes **pmstore** to use a local context to store to
           metrics from PMDAs on the local host without PMCD.  Only some
           metrics are available in this mode.  The **-h** and **-L** options are
           mutually exclusive.
    
           The **-f** option forces the given value to be stored, even if there
           is no current value set.
    
           The interpretation of _value_ is dependent on the syntax used in its
           specification and the underlying data type of _metricname_ , as
           follows.
    
           1.  If the metric has an **integer** type, then _value_ should be an
               optional leading hyphen, followed either by decimal digits or
               ``0x'' and some hexadecimal digits.  ``0X'' is also acceptable
               in lieu of ``0x''.  See strtol(3) and the related routines.
    
           2.  If the metric has a **floating point** type, then _value_ should be
               either in the form of an integer described above, or a fixed
               point number, or a number in scientific notation.  See
               strtod(3).
    
           3.  If the metric has a **string** type, then _value_ is interpreted as
               a literal string of ASCII characters.
    
           4.  If the metric has any other type (i.e.  **PM_TYPE_EVENT** or
               **PM_TYPE_AGGREGATE**) then no encoding of _value_ from the command
               line makes sense, and the values of these metrics cannot be
               modified with **pmstore**.
    
           The output reports the old value and the new value for each
           updated instance of the requested metric.
    
           When using the **-L** option to fetch metrics from a local context,
           the **-K** option may be used to control the DSO PMDAs that should be
           made accessible.  The _spec_ argument conforms to the syntax
           described in pmSpecLocalPMDA(3).  More than one **-K** option may be
           used.
    
           Normally **pmstore** will report the old value (as initially retrieved
           using pmFetch(3)) and the new value from the command line.  The **-F**
           option forces another pmFetch(3) after the pmStore(3) and the
           returned value is reported as the new value.  This is useful in
           cases where _metricname_ is a metric that provides different
           semantics for the store operation, e.g. to increment the current
           value or reset a counter (independent of the _value_ from the
           command line).
    


## OPTIONS



           The available command line options are:
    
           **-f** , **--force**
                Store the value even if no current value set.
    
           **-F** , **--fetch**
                Report the metric value after setting it.
    
           **-i** _insts_ , **--insts** =_insts_
                Restrict store to the comma-separated list of instances.
    
           **-h** _host_ , **--host** =_host_
                Connect to pmcd(1) on _host_ , rather than on the default
                localhost.
    
           **-K** _spec_ , **--spec-local** =_spec_
                When fetching metrics from a local context (see **-L**), the **-K**
                option may be used to control the DSO PMDAs that should be
                made accessible.  The _spec_ argument conforms to the syntax
                described in pmSpecLocalPMDA(3).  More than one **-K** option may
                be used.
    
           **-L** , **--local-PMDA**
                Use a local context to collect metrics from DSO PMDAs on the
                local host without PMCD.  See also **-K**.
    
           **-n** _pmnsfile_ , **--namespace** =_pmnsfile_
                Normally **pmcd** loads the default Performance Metrics Name
                Space (PMNS) from **$PCP_VAR_DIR/pmns/root** , however if the **-n**
                option is specified an alternative namespace is loaded from
                the file _pmnsfile_.
    
           **-V** , **--version**
                Display version number and exit.
    
           **-?** , **--help**
                Display usage message and exit.
    


## DIAGNOSTICS



           Two messages indicate a mismatch between the internal data type
           for _metricname_ and the _value_ provided.
    
           The value "???" is out of range for the data type (PM_TYPE_...)
    
           The value "???" is incompatible with the data type (PM_TYPE_...)
    


## PCP ENVIRONMENT



           Environment variables with the prefix **PCP_** are used to
           parameterize the file and directory names used by PCP.  On each
           installation, the file _/etc/pcp.conf_ contains the local values for
           these variables.  The **$PCP_CONF** variable may be used to specify an
           alternative configuration file, as described in pcp.conf(5).
    


## DEBUGGING OPTIONS



           The **-D** or **--debug** option enables the output of additional
           diagnostics on _stderr_ to help triage problems, although the
           information is sometimes cryptic and primarily intended to provide
           guidance for developers rather end-users.  _debug_ is a comma
           separated list of debugging options; use pmdbg(1) with the **-l**
           option to obtain a list of the available debugging options and
           their meaning.
    


* * *