'\"macro stdmacro
.\"
.\" Copyright (c) 2000-2004 Silicon Graphics, Inc.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMSTORE 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmstore\f1 \- modify performance metric values
.SH SYNOPSIS
\f3pmstore\f1
[\f3\-fFLV?\f1]
[\f3\-h\f1 \f2host\f1]
[\f3\-i\f1 \f2instances\f1]
[\f3\-K\f1 \f2spec\f1]
[\f3\-n\f1 \f2pmnsfile\f1]
\f2metricname\f1 \f2value\f1
.SH 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.
.PP
.B pmstore
changes the current values for the nominated instances of a
single performance metric, as identified by
.I metricname
and the list of instance identifiers following the
.B \-i
argument.
.I instances
must be a single argument, with
elements of the list separated by commas and/or white space.
By default all
instances of
.I metricname
will be updated.
.PP
Normally
.B pmstore
operates on the default Performance Metrics Name Space (PMNS), see
.BR PMNS (5),
however if the
.B \-n
option is specified an alternative namespace is loaded
from the file
.IR pmnsfile .
.PP
Unless directed to another host by the
.B \-h
option,
.B pmstore
will interact with the Performance Metric Collector Daemon (PMCD)
on the local host.
.PP
The
.B \-L
option causes
.B 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
.BR \-h
and
.B \-L
options are mutually exclusive.
.PP
The
.B \-f
option forces the given value to be stored, even if there is no current value set.
.PP
The interpretation of
.I value
is dependent on the syntax used in its specification and
the underlying data type of
.IR metricname ,
as follows.
.IP 1. 4
If the metric has an \fBinteger\fR type, then
.I 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
.BR strtol (3)
and the related routines.
.IP 2. 4
If the metric has a \fBfloating point\fR type, then
.I value
should be either in the form of an integer described above, or
a fixed point number, or a number in scientific notation.
See
.BR strtod (3).
.IP 3. 4
If the metric has a \fBstring\fR type, then
.I value
is interpreted as a literal string of ASCII characters.
.IP 4. 4
If the metric has any other type (i.e.
.B PM_TYPE_EVENT
or
.BR PM_TYPE_AGGREGATE )
then no encoding of
.I value
from the command line makes sense, and the values of these metrics cannot
be modified with
.BR pmstore .
.PP
The output reports the old value and the new value for each updated
instance of the requested metric.
.PP
When using the
.B \-L
option to fetch metrics from a local context, the
.B \-K
option may be used to control the DSO PMDAs that should be
made accessible.
The
.I spec
argument conforms to the syntax described in
.BR pmSpecLocalPMDA (3).
More than one
.B \-K
option may be used.
.PP
Normally
.B pmstore
will report the old value (as initially retrieved using
.BR pmFetch (3))
and the new value from the command line.
The
.B \-F
option forces another
.BR pmFetch (3)
after the
.BR pmStore (3)
and the returned value is reported as the new value.
This is useful in cases where
.I 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
.I value
from the command line).
.SH OPTIONS
The available command line options are:
.TP 5
\fB\-f\fR, \fB\-\-force\fR
Store the value even if no current value set.
.TP
\fB\-F\fR, \fB\-\-fetch\fR
Report the metric value after setting it.
.TP
\fB\-i\fR \fIinsts\fR, \fB\-\-insts\fR=\fIinsts\fR
Restrict store to the comma-separated list of instances.
.TP
\fB\-h\fR \fIhost\fR, \fB\-\-host\fR=\fIhost\fR
Connect to
.BR pmcd (1)
on
.IR host ,
rather than on the default localhost.
.TP
\fB\-K\fR \fIspec\fR, \fB\-\-spec\-local\fR=\fIspec\fR
When fetching metrics from a local context (see
.BR \-L ),
the
.B \-K
option may be used to control the DSO PMDAs that should be made accessible.
The
.I spec
argument conforms to the syntax described in
.BR pmSpecLocalPMDA (3).
More than one
.B \-K
option may be used.
.TP
\fB\-L\fR, \fB\-\-local\-PMDA\fR
Use a local context to collect metrics from DSO PMDAs on the local host
without PMCD.
See also
.BR \-K .
.TP
\f3\-n\f1 \f2pmnsfile\f1, \f3\-\-namespace\f1=\f2pmnsfile\f1
Normally
.B pmcd
loads the default Performance Metrics Name Space (PMNS) from
.BR $PCP_VAR_DIR/pmns/root ,
however if the
.B \-n
option is specified an alternative namespace is loaded
from the file
.IR pmnsfile .
.TP
\fB\-V\fR, \fB\-\-version\fR
Display version number and exit.
.TP
\fB\-?\fR, \fB\-\-help\fR
Display usage message and exit.
.SH DIAGNOSTICS
Two messages indicate a mismatch between the internal data type for
.I metricname
and the
.I value
provided.
.P
The value "???" is out of range for the data type (PM_TYPE_...)
.P
The value "???" is incompatible with the data type (PM_TYPE_...)
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fP are used to parameterize
the file and directory names used by PCP.
On each installation, the
file \fI/etc/pcp.conf\fP contains the local values for these variables.
The \fB$PCP_CONF\fP variable may be used to specify an alternative
configuration file, as described in \fBpcp.conf\fP(5).
.SH SEE ALSO
.BR pmcd (1),
.BR pminfo (1),
.BR pmval (1),
.BR PMAPI (3),
.BR pmFetch (3),
.BR pmSpecLocalPMDA (3),
.BR pmStore (3),
.BR strtod (3),
.BR strtol (3)
and
.BR PMNS (5).