NAME

       pmUnpackEventRecords - unpack event records

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmUnpackEventRecords(pmValueSet *vsp, int idx, pmResult ***rap);

       int pmUnpackHighResEventRecords(pmValueSet *vsp, int idx, pmHighResResult ***hrap);

       cc ... -lpcp

DESCRIPTION

       Event records are encoded as a packed array of records within a pmResult using a container
       metric with a value of type PM_TYPE_EVENT , and a pmHighResResult when using a  metric  of
       type PM_TYPE_HIGHRES_EVENT.

       pmUnpackEventRecords  and  pmUnpackHighResEventRecords may be used to unpack event records
       from a metric value identified by vsp and idx.  If the metric has a  singular  value,  idx
       should  be  0,  else  the  ordinal instance value identified by idx will be unpacked, i.e.
       vsp->vlist[idx].  The unpacked records are turned into either pmResult or  pmHighResResult
       structures,  one  per event record and one metric per event parameter, and rap is returned
       as a pointer to an array (NULL pointer terminated) of pointers to the result structures.

       The  only  difference  between  the  two  result  types  is  the  timestamp   scale;   the
       pmHighResResult  allows  for nanosecond precision, whereas pmResult allows for microsecond
       resolution.

       Some control information from  the  packed  event  records  is  unpacked  into  additional
       ``anonymous'' metrics as follows:

       1.  If   the   event   record   has   a  non-zero  flags  value,  then  the  corresponding
           pmResult/pmHighResResult will have the flags value encoded with the additional  metric
           event.flags that is inserted ahead of all other event parameters.

       2.  If  the  event  record  flag  is  set  to PM_EVENT_FLAG_MISSED, then the corresponding
           pmResult/pmHighResResult will have one metric event.missed with a  value  that  equals
           the  number  of event records ``missed'' because either the PMDA could not keep up, or
           the PMAPI client did not collect the event records fast enough.

       pmUnpackEventRecords returns the number of pmResult structures as the return value,  which
       is  >=  0  for  success.   Similarly,  pmUnpackHighResEventRecords  returns  the number of
       pmHighResResult structures as the return value, which is >= 0 for success.

       rap and the associated pmResult structures may be freed  using  the  convenience  function
       pmFreeEventResult(3).

       Similarly,  the  hrap and the associated pmHighResResult structures may be freed using the
       convenience function pmFreeHighResEventResult.

RETURN VALUE

       The following errors are possible:

       PM_ERR_CONV
                 The values associated with vsp are not encoded using the format  PM_VAL_DPTR  or
                 PM_VAL_SPTR,  or  the  flags  at  the head of the event record has an unexpected
                 value.

       PM_ERR_INST
                 The value associated with vsp is not singular as expected.

       PM_ERR_TYPE
                 vsp is not a value of type PM_TYPE_EVENT.

       PM_ERR_TOOSMALL
                 The value identified by vbp is not legal because the value length is  less  than
                 the  minimum  size, or the number of event records encoded in the (value header)
                 pmEventArray/pmEventHighResArray structure is negative, or the number of  missed
                 event records in the array is negative.

       PM_ERR_TOOBIG
                 Either  vsp  indicates more than one value is present (all the event records are
                 expected to be packed in a single metric value), or  when  unpacking  the  event
                 records,  the  processing  continues  past  the  end  of  the  enclosing  value.
                 Indicates corruption of the packed event record.

       PM_ERR_TYPE
                 Event parameters must have one of the arithmetic types, else  PM_TYPE_AGGREGATE,
                 PM_TYPE_STRING or PM_TYPE_AGGREGATE_STATIC.

       other values < 0
                 refer to pmErrStr(3).

SEE ALSO

       PMAPI(3) and pmFreeEventResult(3).