# QmcGroup

## NAME



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


## C++ SYNOPSIS



           **#include <QmcGroup.h>**
    
           **c++ ... -lpcp_qmc -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 cre‐
           ated 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::add‐**
           **Metric**.  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_CON‐**
               **TEXT_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 contextIndex() 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 **QmcMet‐**
           **ric::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 in‐
               stances (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 automati‐
               cally 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 time‐
               zone.  **localTZ** , **userTZ** and **groupTZ** indicate that the timezone
               was set with **QmcGroup::useLocalTZ** , **QmcGroup::useTZ(QString**
               **const &) **and **QmcGroup::useTZ()** respectively.  **unknownTZ** indi‐
               cates 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.
    


## DEBUGGING



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


## 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 the option **pmc**
           to the global debugging specification, as described in
           pmSetDebug(3).
    


* * *