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 pmAtom­
       Value 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 */
                void         *vp;   /* void 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 par­
       ticular 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

       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     and
       PM_TYPE_AGGREGATE   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 horizon­
       tally.  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 conver­
       sions   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(3S) and sprintf(3S).

              | 32  |  U32  | 64  |  U64  | FLOAT | DBLE | STRING | AGGR |
       =======|=====|=======|=====|=======|=======|======|========|======|
       32     |  Y  |   S   |  Y  |   S   |   P   |  P   |   N    |  N   |
       U32    |  T  |   Y   |  Y  |   Y   |   P   |  P   |   N    |  N   |
       64     |  T  |  T,S  |  Y  |   S   |   P   |  P   |   N    |  N   |
       U64    |  T  |   T   |  T  |   Y   |   P   |  P   |   N    |  N   |
       FLOAT  | P,T | P,T,S | P,T | P,T,S |   Y   |  Y   |   N    |  N   |
       DBLE   | P,T | P,T,S | P,T | P,T,S |   P   |  Y   |   N    |  N   |
       STRING |  N  |   N   |  N  |   N   |   N   |  N   |   Y    |  N   |
       AGGR   |  N  |   N   |  N  |   N   |   N   |  N   |   N    |  Y   |

       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  pmExtract­
       Value(3)  using malloc(3C), and it is the caller's respon­
       sibility 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

       the type field in a pmDesc  structure,  into  a  canonical
       type for local processing.


SEE ALSO

       PMAPI(3),    pmAtomStr(3),   pmConvScale(3),   pmFetch(3),
       pmLookupDesc(3), pmPrintValue(3),  pmTypeStr(3)  and  pmU­
       nitsStr(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


Man(1) output converted with man2html