# pmiaddmetric

## NAME



           **pmiAddMetric** - add a new metric definition to a LOGIMPORT context
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
           **#include <pcp/import.h>**
    
           **int pmiAddMetric(const char ***_name_**, pmID** _pmid_**, int** _type_**,**
                            **pmInDom** _indom_**, int** _sem_**, pmUnits** _units_**);**
    
           **cc ... -lpcp_import -lpcp**
    


## Perl SYNOPSIS



           **use PCP::LogImport;**
    
           **pmiAddMetric($**_name_**, $**_pmid_**, $**_type_**, $**_indom_**, $**_sem_**, $**_units_**);**
    


## DESCRIPTION



           As   part   of  the  Performance  Co-Pilot  Log  Import  API  (see
           LOGIMPORT(3)), **pmiAddMetric** is used to define a new  metric.   The
           metric's  _name_  must  follow  the  naming conventions described in
           PCPIntro(1) and should be unique for each LOGIMPORT context.
    
           The other arguments are in effect the fields of  a  **pmDesc** struc‐
           ture.   Refer to pmLookupDesc(3) for a complete description of the
           values and semantics of the  components  of  this  structure,  and
           hence the valid argument values for **pmiAddMetric**.
    
           The internal identifier for the metric may be given using the _pmid_
           argument and must be unique for each LOGIMPORT context.  The value
           for _pmid_ which would typically be constructed using the **pmID_build**
           macro,  e.g. pmID_build(PMI_DOMAIN, 0, 3) for the fourth metric in
           first ``cluster'' of metrics in  the  Performance  Metrics  Domain
           PMI_DOMAIN  (which is the default for all meta data created by the
           LOGIMPORT library).  Alternatively, _pmid_  may  be  **PM_IN_NULL** and
           **pmiAddMetric** will  assign  a unique _pmid_ (although this means the
           _pmid_ remains opaque and the application must use pmiPutValue(3) or
           pmiPutValueHandle(3) and cannot use pmiPutResult(3)  to  add  data
           values to the PCP archive).
    
           _type_  defines  the  data type of the metric and must be one of the
           **PM_TYPE_...** values defined in **< pcp/import.h>**.
    
           The instance domain for the metric is defined by _indom_ and may  be
           **PM_INDOM_NULL** for  a metric with a singular value, else the value
           for _indom_ would normally be constructed  using  the  **pmInDom_build**
           macro,  e.g. pmInDom_build(LOGIMPORT,0) for the first instance do‐
           main in the Performance Metrics Domain LOGIMPORT (which is the de‐
           fault for all meta data created by the LOGIMPORT library).  Multi‐
           ple metrics can share the same instance domain if they have values
           for a similar (or more usually, identical) set of instances.
    
           The semantics of the metric (counter, instantaneous  value,  etc.)
           is  specified  by the _sem_ argument which would normally be the re‐
           sult of a call to the convenience constructor method pmiUnits(3).
    


## DIAGNOSTICS



           **pmiAddMetric** returns zero on success else a  negative  value  that
           can be turned into an error message by calling pmiErrStr(3).
    


* * *