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

NAME

6       pmUnpackEventRecords,   pmUnpackHighResEventRecords   -   unpack  event
7       records
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11
12       int pmUnpackEventRecords(pmValueSet *vsp, int idx, pmResult ***rap);
13
14       int pmUnpackHighResEventRecords(pmValueSet *vsp, int idx,  pmHighResRe‐
15       sult ***hrap);
16
17       cc ... -lpcp
18

DESCRIPTION

20       Event  records  are encoded as a packed array of records within a pmRe‐
21       sult using a container metric with a value of type PM_TYPE_EVENT ,  and
22       a pmHighResResult when using a metric of type PM_TYPE_HIGHRES_EVENT.
23
24       pmUnpackEventRecords  and  pmUnpackHighResEventRecords  may  be used to
25       unpack event records from a metric value identified by vsp and idx.  If
26       the  metric  has  a  singular  value, idx should be 0, else the ordinal
27       instance   value   identified   by   idx   will   be   unpacked,   i.e.
28       vsp->vlist[idx].   The unpacked records are turned into either pmResult
29       or pmHighResResult structures, one per event record and one metric  per
30       event  parameter,  and  rap  is returned as a pointer to an array (NULL
31       pointer terminated) of pointers to the result structures.
32
33       The only difference between the  two  result  types  is  the  timestamp
34       scale;  the  pmHighResResult  allows  for nanosecond precision, whereas
35       pmResult allows for microsecond resolution.
36
37       Some control information from the packed event records is unpacked into
38       additional ``anonymous'' metrics as follows:
39
40       1.  If  the  event  record  has a non-zero flags value, then the corre‐
41           sponding pmResult/pmHighResResult will have the flags value encoded
42           with  the  additional  metric event.flags that is inserted ahead of
43           all other event parameters.
44
45       2.  If the event record flag is set to PM_EVENT_FLAG_MISSED,  then  the
46           corresponding   pmResult/pmHighResResult   will   have  one  metric
47           event.missed with a value that equals the number of  event  records
48           ``missed''  because either the PMDA could not keep up, or the PMAPI
49           client did not collect the event records fast enough.
50
51       pmUnpackEventRecords returns the number of pmResult structures  as  the
52       return value, which is >= 0 for success.  Similarly, pmUnpackHighResEv‐
53       entRecords returns the number  of  pmHighResResult  structures  as  the
54       return value, which is >= 0 for success.
55
56       rap  and the associated pmResult structures may be freed using the con‐
57       venience function pmFreeEventResult(3).
58
59       Similarly, the hrap and the associated pmHighResResult  structures  may
60       be freed using the convenience function pmFreeHighResEventResult.
61

RETURN VALUE

63       The following errors are possible:
64
65       PM_ERR_CONV
66                 The values associated with vsp are not encoded using the for‐
67                 mat PM_VAL_DPTR or PM_VAL_SPTR, or the flags at the  head  of
68                 the event record has an unexpected value.
69
70       PM_ERR_INST
71                 The value associated with vsp is not singular as expected.
72
73       PM_ERR_TYPE
74                 vsp is not a value of type PM_TYPE_EVENT.
75
76       PM_ERR_TOOSMALL
77                 The  value  identified  by vbp is not legal because the value
78                 length is less than the minimum size, or the number of  event
79                 records  encoded  in  the (value header) pmEventArray/pmEven‐
80                 tHighResArray structure is negative, or the number of  missed
81                 event records in the array is negative.
82
83       PM_ERR_TOOBIG
84                 Either  vsp indicates more than one value is present (all the
85                 event records are expected to be packed in  a  single  metric
86                 value),  or  when unpacking the event records, the processing
87                 continues past the end of  the  enclosing  value.   Indicates
88                 corruption of the packed event record.
89
90       PM_ERR_TYPE
91                 Event  parameters must have one of the arithmetic types, else
92                 PM_TYPE_AGGREGATE,    PM_TYPE_STRING    or     PM_TYPE_AGGRE‐
93                 GATE_STATIC.
94
95       other values < 0
96                 refer to pmErrStr(3).
97

SEE ALSO

99       PMAPI(3) and pmFreeEventResult(3).
100
101
102
103Performance Co-Pilot                  PCP              PMUNPACKEVENTRECORDS(3)
Impressum