# pmextractvalue

## NAME



           **pmExtractValue** - extract a performance metric value from a
           pmResult structure
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
    
           **int pmExtractValue(int** _valfmt_**, const pmValue ***_ival_**, int** _itype_**,**
                              **pmAtomValue ***_oval_**, int** _otype_**);**
    
           **cc ... -lpcp**
    


## DESCRIPTION



           The  _pmValue_  structure  is embedded within the _pmResult_ structure
           that is used to  return  one  or  more  performance  metrics;  see
           pmFetch(3).
    
           All  performance  metric  values  may  be encoded in a _pmAtomValue_
           union, defined as follows;
    
                typedef union {
                    __int32_t    l;     /* 32-bit signed */
                    __uint32_t   ul;    /* 32-bit unsigned */
                    __int64_t    ll;    /* 64-bit signed */
                    __uint64_t   ull;   /* 64-bit unsigned */
                    float        f;     /* 32-bit floating point */
                    double       d;     /* 64-bit floating point */
                    char         *cp;   /* char ptr */
                    pmValueBlock *vbp;  /* pmValueBlock ptr */
                } pmAtomValue;
    
           The routine **pmExtractValue** provides a convenient mechanism for ex‐
           tracting values from the _pmValue_ part of a _pmResult_ structure, op‐
           tionally converting the data type, and making the result available
           to the application programmer.
    
           _itype_ defines the data type of the input value held  in  _ival_  ac‐
           cording  to the storage format defined by _valfmt_ (see pmFetch(3)).
           _otype_ defines the data type of the result to be placed in _oval_.
    
           The value for _itype_ is typically extracted from  a  _pmDesc_  struc‐
           ture, following a call to pmLookupDesc(3) for a particular perfor‐
           mance metric.
    
           The  _otype_ value should be one of the defined **PM_TYPE_**...  values,
           that have a 1:1 correspondence with the fields in the  _pmAtomValue_
           union.
    
           Normally the _valfmt_ parameter would be plucked from the same _pmRe‐_
           _sult_  structure  that  provides  the _ival_ parameter, and if _valfmt_
           specifies **PM_VAL_INSITU** , then the following input  types  are  not
           allowed,  as  these  cannot  be  encoded  in  32-bits;  **__int64_t** ,
           **__uint64_t** , **double** , **char *** and **void *** and the corresponding  _itype_
           values     are     **PM_TYPE_64** ,     **PM_TYPE_U64** ,    **PM_TYPE_DOUBLE** ,
           **PM_TYPE_STRING** ,   **PM_TYPE_AGGREGATE** and    **PM_TYPE_EVENT**(or
           **PM_TYPE_HIGHRES_EVENT**)    respectively.    If   _valfmt_   specifies
           **PM_VAL_SPTR** or **PM_VAL_DPTR** , then the value will be extracted  from
           the   associated   _pmValueBlock_   structure,  and  the  **__int32_t** ,
           **__uint32_t** and **float** options (_itype_ being **PM_TYPE_32** ,  **PM_TYPE_U32**
           and  **PM_TYPE_FLOAT** respectively) are not allowed, as **PM_VAL_INSITU**
           is the appropriate encoding for these.
    
           The following table defines the various possibilities for the type
           conversion -- the input type (_itype_) is shown vertically, and  the
           output type (_otype_) is shown horizontally.  Y means the conversion
           is  always  acceptable,  N  means the conversion can never be per‐
           formed (the function returns **PM_ERR_CONV**), P means the  conversion
           may  lose  accuracy (but no error status is returned), T means the
           result may be subject to high-order truncation (in which case  the
           function  returns  **PM_ERR_TRUNC**) and S means the conversion may be
           impossible due to the sign of the input value (in which  case  the
           function returns **PM_ERR_SIGN**).  If an error occurs, the value rep‐
           resented by _oval_ will be zero (or **NULL**).
    
           No  conversion  involving  the  types **PM_TYPE_EVENT** , **PM_TYPE_HIGH‐**
           **RES_EVENT** or **PM_TYPE_AGGR** is supported, and the label ``BLOB''  in
           the table below covers all three of these types.
    
                 | 32  |  U32  | 64  |  U64  | FLOAT | DBLE | STRNG | BLOB
           ======|=====|=======|=====|=======|=======|======|=======|======
           32    |  Y  |   S   |  Y  |   S   |   P   |  P   |   Y   |  N
           U32   |  T  |   Y   |  Y  |   Y   |   P   |  P   |   Y   |  N
           64    |  T  |  T,S  |  Y  |   S   |   P   |  P   |   Y   |  N
           U64   |  T  |   T   |  T  |   Y   |   P   |  P   |   Y   |  N
           FLOAT | P,T | P,T,S | P,T | P,T,S |   Y   |  Y   |   P   |  N
           DBLE  | P,T | P,T,S | P,T | P,T,S |   P   |  Y   |   P   |  N
           STRNG |  N  |   N   |  N  |   N   |   N   |  N   |   Y   |  N
           BLOB  |  N  |   N   |  N  |   N   |   N   |  N   |   N   |  N
    
           In  the  cases  where  multiple conversion errors could occur, the
           first encountered error will be notified, and the order of  check‐
           ing is not defined.
    
           If  the  output  conversion  is  to one of the pointer types, i.e.
           _otype_ is  **PM_TYPE_STRING** or  **PM_TYPE_AGGREGATE** ,  then  the  value
           buffer   will  have  been  allocated  by  pmExtractValue(3)  using
           malloc(3), and it is the caller's responsibility to free the space
           when it is no longer required.
    
           Although this function appears rather complex, it  has  been  con‐
           structed  to assist the development of performance tools that wish
           to convert values, whose type is only known via the _type_ field  in
           a  _pmDesc_  structure,  into a canonical type for local processing.
           See the **pmFetchGroup** functions for a simpler alternative.
    


## DIAGNOSTICS



           **PM_ERR_CONV**
    
                  Impossible conversion, marked by N in above table
    
           **PM_ERR_TRUNC**
    
                  High-order truncation occurred
    
           **PM_ERR_SIGN**
    
                  Conversion of negative value to unsigned type attempted
    


* * *