1PMEXTRACTVALUE(3)          Library Functions Manual          PMEXTRACTVALUE(3)
2
3
4

NAME

6       pmExtractValue  -  extract  a  performance metric value from a pmResult
7       structure
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11
12       int pmExtractValue(int valfmt, const pmValue *ival, int itype,
13               pmAtomValue *oval, int otype);
14
15       cc ... -lpcp
16

DESCRIPTION

18       The pmValue structure is embedded within the pmResult structure that is
19       used to return one or more performance metrics; see pmFetch(3).
20
21       All performance metric values may be encoded in  a  pmAtomValue  union,
22       defined as follows;
23
24            typedef union {
25                __int32_t    l;     /* 32-bit signed */
26                __uint32_t   ul;    /* 32-bit unsigned */
27                __int64_t    ll;    /* 64-bit signed */
28                __uint64_t   ull;   /* 64-bit unsigned */
29                float        f;     /* 32-bit floating point */
30                double       d;     /* 64-bit floating point */
31                char         *cp;   /* char ptr */
32                pmValueBlock *vbp;  /* pmValueBlock ptr */
33            } pmAtomValue;
34
35       The routine pmExtractValue provides a convenient mechanism for extract‐
36       ing values from the pmValue part of a  pmResult  structure,  optionally
37       converting the data type, and making the result available to the appli‐
38       cation programmer.
39
40       itype defines the data type of the input value held in  ival  according
41       to  the  storage  format defined by valfmt (see pmFetch(3)).  otype de‐
42       fines the data type of the result to be placed in oval.
43
44       The value for itype is typically extracted  from  a  pmDesc  structure,
45       following  a  call to pmLookupDesc(3) for a particular performance met‐
46       ric.
47
48       The otype value should be one of the defined PM_TYPE_...  values,  that
49       have a 1:1 correspondence with the fields in the pmAtomValue union.
50
51       Normally  the  valfmt parameter would be plucked from the same pmResult
52       structure that provides the ival parameter,  and  if  valfmt  specifies
53       PM_VAL_INSITU,  then the following types are not allowed, as these can‐
54       not be encoded in 32-bits; __int64_t, __uint64_t, double,  char  *  and
55       void  *  (the  corresponding  itype values are PM_TYPE_64, PM_TYPE_U64,
56       PM_TYPE_DOUBLE, PM_TYPE_STRING, PM_TYPE_AGGREGATE and PM_TYPE_EVENT re‐
57       spectively).   If  valfmt  specifies PM_VAL_PTR, then the value will be
58       extracted  from  the  associated  pmValueBlock   structure,   and   the
59       __int32_t,  __uint32_t  and  float  options  (itype  being  PM_TYPE_32,
60       PM_TYPE_U32  and  PM_TYPE_FLOAT  respectively)  are  not  allowed,   as
61       PM_VAL_INSITU is the appropriate encoding for these.
62
63       The following table defines the various possibilities for the type con‐
64       version -- the input type (itype) is shown vertically, and  the  output
65       type  (otype)  is shown horizontally.  Y means the conversion is always
66       acceptable, N means the conversion can never be performed (the function
67       returns  PM_ERR_CONV), P means the conversion may lose accuracy (but no
68       error status is returned), T means the result may be subject  to  high-
69       order  truncation (in which case the function returns PM_ERR_TRUNC) and
70       S means the conversion may be impossible due to the sign of  the  input
71       value  (in  which  case the function returns PM_ERR_SIGN).  If an error
72       occurs, the value represented by oval will be zero (or NULL).
73
74       Note  that  although  some  of  the  conversions  involving  the  types
75       PM_TYPE_STRING  and  PM_TYPE_AGGREGATE  are  indeed  possible,  but are
76       marked N - the rationale is that pmExtractValue should not be  attempt‐
77       ing  to  duplicate functionality already available in the C library via
78       sscanf(3) and sprintf(3).
79
80       No conversion involving the type PM_TYPE_EVENT is supported.
81
82             | 32  |  U32  | 64  |  U64  | FLOAT | DBLE | STRNG | AGGR | EVENT
83       ======|=====|=======|=====|=======|=======|======|=======|======|=======
84       32    |  Y  |   S   |  Y  |   S   |   P   |  P   |   N   |  N   |   N
85       U32   |  T  |   Y   |  Y  |   Y   |   P   |  P   |   N   |  N   |   N
86       64    |  T  |  T,S  |  Y  |   S   |   P   |  P   |   N   |  N   |   N
87       U64   |  T  |   T   |  T  |   Y   |   P   |  P   |   N   |  N   |   N
88       FLOAT | P,T | P,T,S | P,T | P,T,S |   Y   |  Y   |   N   |  N   |   N
89       DBLE  | P,T | P,T,S | P,T | P,T,S |   P   |  Y   |   N   |  N   |   N
90       STRNG |  N  |   N   |  N  |   N   |   N   |  N   |   Y   |  N   |   N
91       AGGR  |  N  |   N   |  N  |   N   |   N   |  N   |   N   |  Y   |   N
92       EVENT |  N  |   N   |  N  |   N   |   N   |  N   |   N   |  N   |   N
93
94       In the cases where multiple conversion errors could  occur,  the  first
95       encountered  error  will  be notified, and the order of checking is not
96       defined.
97
98       If the output conversion is to one of the pointer types, i.e. otype  is
99       PM_TYPE_STRING  or  PM_TYPE_AGGREGATE,  then the value buffer will have
100       been allocated by pmExtractValue(3) using  malloc(3),  and  it  is  the
101       caller's  responsibility  to  free  the  space when it is no longer re‐
102       quired.
103
104       Although this function appears rather complex, it has been  constructed
105       to  assist  the  development  of performance tools that wish to convert
106       values, whose type is only known via the type field in a pmDesc  struc‐
107       ture, into a canonical type for local processing.  See the pmFetchGroup
108       functions for a simpler alternative.
109

DIAGNOSTICS

111       PM_ERR_CONV
112
113              Impossible conversion, marked by N in above table
114
115       PM_ERR_TRUNC
116
117              High-order truncation occurred
118
119       PM_ERR_SIGN
120
121              Conversion of negative value to unsigned type attempted
122

SEE ALSO

124       PMAPI(3), pmAtomStr(3),  pmConvScale(3),  pmFetch(3),  pmFetchGroup(3),
125       pmLookupDesc(3),   pmPrintValue(3),   pmTypeStr(3),  pmUnitsStr(3)  and
126       pmUnpackEventRecords(3).
127
128
129
130Performance Co-Pilot                  PCP                    PMEXTRACTVALUE(3)
Impressum