NAME

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

C++ SYNOPSIS

       #include <QmcGroup.h>

       CC ... -lqmc -lpcp

DESCRIPTION

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

CONSTRUCTORS & DESTRUCTOR

       ~QmcGroup();
           Destructor which destroys all metrics and contexts created by this group.

       QmcGroup(bool restrictArchives = false);
           Construct  a new fetch group.  restrictArchives will restrict the creating of multiple
           archive contexts created from the same host.

CONTEXTS

       The  default  context  of  the  group  is  defined  as  the  first  context  created  with
       QmcGroup::use  before  the  first  call  to QmcGroup::addMetric.  If no context is created
       before the first  metric  is  added,  the  localhost  is  used  as  the  default  context.
       Therefore,  if  any metrics specifications contain archive sources, an archive source must
       have been created with QmcGroup::use to avoid an error for mixing context types.

       uint_t numContexts() const;
           The number of valid contexts created in this group.

       QmcContext const& context(uint_t index) const
           Return a handle to a context.

       QmcContext& context(uint_t index);
           Return a modifiable handle to a context.

       int mode() const;
           Return  the   type   of   context,   either   PM_CONTEXT_LOCAL,   PM_CONTEXT_HOST   or
           PM_CONTEXT_ARCHIVE.

       QmcContext* which() const;
           Return   a  handle  to  the  current  context  of  this  group.  This  does  not  call
           pmUseContext(3) so it may not be the current PMAPI(3) context.

       uint_t whichIndex() const
           The index to the current group context.

       int use(int type, char const* source);
           Use the context of type from source.  If a context to this source  already  exists  in
           this  group,  that  context will become the current PMAPI(3) context.  Otherwise a new
           context will  be  created.   The  result  is  the  PMAPI(3)  context  handle  for  the
           QmcGroup::context or a PMAPI(3) error code if the context failed.

       bool defaultDefined() const;
           Returns true if a default context has been determined.

       int useDefault();
           Use the default context. If a default context has not been created, the context to the
           local host will be attempted.  A result less  than  zero  indicates  that  the  method
           failed with the PMAPI(3) error encoded in the result.

       void createLocalContext();
           Create  and  use  a context to the local host.  A result less than zero indicates that
           the method failed with the PMAPI(3) error encoded in the result.

METRICS

       These addMetric methods should be used to create new metrics as the QmcMetric constructors
       are private. These methods will always return a pointer to a QmcMetric object, however the
       QmcMetric::status() field should be checked to ensure the metric is valid.

       QmcMetric* addMetric(char const* str, double theScale = 0.0,
           bool active = false);

           Add the metric str to the group, with a scaling factor of scale.  If active is set the
           metric will use only active instances (see QmcMetric(3)).

       QmcMetric* addMetric(pmMetricSpec* theMetric, double theScale
           = 0.0, bool active);

           Add  the  metric theMetric to the group, with a scaling factor of scale.  If active is
           set the metric will use only active instances (see QmcMetric(3)).

       int fetch(bool update = true);
           Fetch all the metrics in all the contexts in this group.  If update is equal to  true,
           all counter metrics will be automatically converted to rates (see QmcMetric(3)).

       int setArchiveMode(int mode, const struct timeval *when,
           int interval);

           Set  the mode and time to access all archive contexts in this group.  See pmSetmode(3)
           for more details.

TIMEZONES

       These methods assist in the management of multiple  timezones  and  help  to  control  the
       current timezone.

       enum TimeZoneFlag { localTZ, userTZ, groupTZ, unknownTZ };
           Enumeration  used to describe the origin of the default timezone.  localTZ, userTZ and
           groupTZ   indicate   that   the   timezone   was   set   with    QmcGroup::useLocalTZ,
           QmcGroup::useTZ(QString   const&)   and   QmcGroup::useTZ()  respectively.   unknownTZ
           indicates that a timezone has not been set.  userTZ indicates that the timezone was

       int useTZ();
           Use the timezone of the current group context as the default.

       int useTZ(const QString &tz);
           Add and use tz as the default timezone of this group.

       int useLocalTZ();
           Use the timezone of the localhost as the default for this group.

       void defaultTZ(QString &label, QString &tz);
           Return the label and tz string of the default timezone of this group.

       TimeZoneFlag defaultTZ() const
           Return the origin of the default timezone.

       int useDefaultTZ();
           Set the timezone to be  the  default  timezone  as  defined  in  a  previous  call  to
           QmcGroup::useTZ or QmcGroup::useLocalTZ.

       struct timeval const& logStart() const;
           Return  the  earliest  starting  time  of  any  archives  in this group.  Assumes that
           QmcGroup::updateBounds has been called.

       struct timeval const& logEnd() const;
           Return  the  latest  finish  time  of  any  archives  in  this  group.   Assumes  that
           QmcGroup::updateBounds has been called.

       void updateBounds();
           Determine the earliest start and latest finish times of all archives in this group.

       int sendTimezones();
           Send the current timezones to kmtime (3).

DEBUGGING

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

SEE ALSO

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

DIAGNOSTICS

       Error   messages  are  generated  using  pmprintf(3)  but  are  not  flushed.  It  is  the
       responsibility of the user to call pmflush(3) to output any messages.

       Additional diagnostics may be activated by adding DBG_TRACE_PMC to the global pmDebug.