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