1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
'\"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
.\" literals use .B or \f3
.\" arguments use .I or \f2
.SH SYNOPSIS
\f3pmstore\f1
[\f3\-L\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), 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 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 (3C)
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 (3C).
.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.
.SH FILES
.PD 0
.TP 10
.BI $PCP_VAR_DIR/pmns/ *
default PMNS specification files
.PD
.SH "PCP ENVIRONMENT"
Environment variables with the prefix
.B PCP_
are used to parameterize the file and directory names
used by PCP.
On each installation, the file
.I /etc/pcp.conf
contains the local values for these variables.
The
.B $PCP_CONF
variable may be used to specify an alternative
configuration file,
as described in
.BR pcp.conf (5).
.SH SEE ALSO
.BR pmcd (1),
.BR pminfo (1),
.BR pmval (1),
.BR __pmSpecLocalPMDA (3),
.BR strtod (3)
and
.BR strtol (3).
.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_...)
|
