1QMC_GROUP(3)               Library Functions Manual               QMC_GROUP(3)
2
3
4

NAME

6       QmcGroup  - container representing a single fetch group of metrics from
7       multiple sources
8

C++ SYNOPSIS

10       #include <QmcGroup.h>
11
12       CC ... -lqmc -lpcp
13

DESCRIPTION

15       A QmcGroup object is a container for contexts and metrics  that  should
16       be  fetched  at  the  same  time.   The class manages the QmcContext(3)
17       objects, timezones and bounds  for  every  context  created  with  Qmc‐
18       Group::use and QmcGroup::addMetric.
19

CONSTRUCTORS & DESTRUCTOR

21       ~QmcGroup();
22           Destructor  which destroys all metrics and contexts created by this
23           group.
24
25       QmcGroup(bool restrictArchives = false);
26           Construct a new fetch group.  restrictArchives  will  restrict  the
27           creating of multiple archive contexts created from the same host.
28

CONTEXTS

30       The  default  context of the group is defined as the first context cre‐
31       ated with QmcGroup::use before the first call  to  QmcGroup::addMetric.
32       If  no  context is created before the first metric is added, the local‐
33       host is used as the default context.  Therefore, if any metrics  speci‐
34       fications  contain  archive  sources,  an archive source must have been
35       created with QmcGroup::use to avoid an error for mixing context types.
36
37       uint_t numContexts() const;
38           The number of valid contexts created in this group.
39
40       QmcContext const& context(uint_t index) const
41           Return a handle to a context.
42
43       QmcContext& context(uint_t index);
44           Return a modifiable handle to a context.
45
46       int mode() const;
47           Return  the  type  of  context,  either  PM_CONTEXT_LOCAL,  PM_CON‐
48           TEXT_HOST or PM_CONTEXT_ARCHIVE.
49
50       QmcContext* which() const;
51           Return a handle to the current context of this group. This does not
52           call pmUseContext(3) so it may not be the current PMAPI(3) context.
53
54       uint_t whichIndex() const
55           The index to the current group context.
56
57       int use(int type, char const* source);
58           Use the context of type from source.  If a context to  this  source
59           already  exists in this group, that context will become the current
60           PMAPI(3) context.  Otherwise a new context will  be  created.   The
61           result  is the PMAPI(3) context handle for the QmcGroup::context or
62           a PMAPI(3) error code if the context failed.
63
64       bool defaultDefined() const;
65           Returns true if a default context has been determined.
66
67       int useDefault();
68           Use the default context. If a default context has not been created,
69           the  context  to  the  local host will be attempted.  A result less
70           than zero indicates that the method failed with the PMAPI(3)  error
71           encoded in the result.
72
73       void createLocalContext();
74           Create  and  use  a  context to the local host.  A result less than
75           zero indicates that the  method  failed  with  the  PMAPI(3)  error
76           encoded in the result.
77

METRICS

79       These  addMetric  methods  should  be used to create new metrics as the
80       QmcMetric constructors are private. These methods will always return  a
81       pointer  to  a  QmcMetric object, however the QmcMetric::status() field
82       should be checked to ensure the metric is valid.
83
84       QmcMetric* addMetric(char const* str, double theScale = 0.0,
85           bool active = false);
86
87           Add the metric str to the group, with a scaling  factor  of  scale.
88           If  active  is  set  the metric will use only active instances (see
89           QmcMetric(3)).
90
91       QmcMetric* addMetric(pmMetricSpec* theMetric, double theScale
92           = 0.0, bool active);
93
94           Add the metric theMetric to the group, with  a  scaling  factor  of
95           scale.   If active is set the metric will use only active instances
96           (see QmcMetric(3)).
97
98       int fetch(bool update = true);
99           Fetch all the metrics in all the contexts in this group.  If update
100           is  equal  to  true, all counter metrics will be automatically con‐
101           verted to rates (see QmcMetric(3)).
102
103       int setArchiveMode(int mode, const struct timeval *when,
104           int interval);
105
106           Set the mode and time to access all archive contexts in this group.
107           See pmSetmode(3) for more details.
108

TIMEZONES

110       These  methods  assist in the management of multiple timezones and help
111       to control the current timezone.
112
113       enum TimeZoneFlag { localTZ, userTZ, groupTZ, unknownTZ };
114           Enumeration used to describe the origin of  the  default  timezone.
115           localTZ, userTZ and groupTZ indicate that the timezone was set with
116           QmcGroup::useLocalTZ,  QmcGroup::useTZ(QString  const&)  and   Qmc‐
117           Group::useTZ()  respectively.   unknownTZ indicates that a timezone
118           has not been set.  userTZ indicates that the timezone was
119
120       int useTZ();
121           Use the timezone of the current group context as the default.
122
123       int useTZ(const QString &tz);
124           Add and use tz as the default timezone of this group.
125
126       int useLocalTZ();
127           Use the timezone of the localhost as the default for this group.
128
129       void defaultTZ(QString &label, QString &tz);
130           Return the label and tz string of  the  default  timezone  of  this
131           group.
132
133       TimeZoneFlag defaultTZ() const
134           Return the origin of the default timezone.
135
136       int useDefaultTZ();
137           Set  the timezone to be the default timezone as defined in a previ‐
138           ous call to QmcGroup::useTZ or QmcGroup::useLocalTZ.
139
140       struct timeval const& logStart() const;
141           Return the earliest starting time of any archives  in  this  group.
142           Assumes that QmcGroup::updateBounds has been called.
143
144       struct timeval const& logEnd() const;
145           Return  the  latest  finish  time  of  any  archives in this group.
146           Assumes that QmcGroup::updateBounds has been called.
147
148       void updateBounds();
149           Determine the earliest start and latest finish  times  of  all  ar‐
150           chives in this group.
151
152       int sendTimezones();
153           Send the current timezones to kmtime (3).
154

DEBUGGING

156       void dump(ostream &os);
157           Dump state information about this group to os.
158

SEE ALSO

160       PMAPI(3),  QMC(3), QmcContext(3), QmcMetric(3), pmflush(3), pmprintf(3)
161       and pmSetMode(3).
162

DIAGNOSTICS

164       Error messages are generated using pmprintf(3) but are not flushed.  It
165       is the responsibility of the user to call pmflush(3) to output any mes‐
166       sages.
167
168       Additional diagnostics may be activated by adding DBG_TRACE_PMC to  the
169       global pmDebug.
170
171
172
173Performance Co-Pilot                  SGI                         QMC_GROUP(3)
Impressum