NAME

       pmUnpackEventRecords - unpack event records

C SYNOPSIS

       #include <pcp/pmapi.h>

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

       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.

       pmUnpackEventRecords 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  pmResult  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 pmResult structures.

       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 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 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.

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

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 structure is
                 negative, or the number of missed event records in the pmEventArray 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).