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 extracting values from the
       pmValue part of a pmResult structure, optionally 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 according 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 structure, following a call to
       pmLookupDesc(3) for a particular performance 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 pmResult structure that
       provides the ival parameter, and if valfmt specifies  PM_VAL_INSITU,  then  the  following
       types  are  not  allowed,  as  these  cannot be encoded in 32-bits; __int64_t, __uint64_t,
       double, char * and void * (the corresponding itype  values  are  PM_TYPE_64,  PM_TYPE_U64,
       PM_TYPE_DOUBLE,  PM_TYPE_STRING,  PM_TYPE_AGGREGATE  and  PM_TYPE_EVENT respectively).  If
       valfmt specifies PM_VAL_PTR,  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 performed
       (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 represented by oval will be zero (or NULL).

       Note that although  some  of  the  conversions  involving  the  types  PM_TYPE_STRING  and
       PM_TYPE_AGGREGATE  are  indeed  possible,  but  are  marked  N  -  the  rationale  is that
       pmExtractValue should not be attempting to duplicate functionality  already  available  in
       the C library via sscanf(3) and sprintf(3).

       No conversion involving the type PM_TYPE_EVENT is supported.

             | 32  |  U32  | 64  |  U64  | FLOAT | DBLE | STRNG | AGGR | EVENT
       ======|=====|=======|=====|=======|=======|======|=======|======|=======
       32    |  Y  |   S   |  Y  |   S   |   P   |  P   |   N   |  N   |   N
       U32   |  T  |   Y   |  Y  |   Y   |   P   |  P   |   N   |  N   |   N
       64    |  T  |  T,S  |  Y  |   S   |   P   |  P   |   N   |  N   |   N
       U64   |  T  |   T   |  T  |   Y   |   P   |  P   |   N   |  N   |   N
       FLOAT | P,T | P,T,S | P,T | P,T,S |   Y   |  Y   |   N   |  N   |   N
       DBLE  | P,T | P,T,S | P,T | P,T,S |   P   |  Y   |   N   |  N   |   N
       STRNG |  N  |   N   |  N  |   N   |   N   |  N   |   Y   |  N   |   N
       AGGR  |  N  |   N   |  N  |   N   |   N   |  N   |   N   |  Y   |   N
       EVENT |  N  |   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 checking 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 constructed 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.

SEE ALSO

       PMAPI(3),  pmAtomStr(3),  pmConvScale(3),  pmFetch(3),  pmFetchGroup(3),  pmLookupDesc(3),
       pmPrintValue(3), pmTypeStr(3), pmUnitsStr(3) and pmUnpackEventRecords(3).

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