# pmunpackeventrecords

## NAME



           **pmUnpackHighResEventRecords** , **pmUnpackEventRecords** - unpack event
           records
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
    
           **int pmUnpackHighResEventRecords(pmValueSet ***_vsp_**, int** _idx_**,**
                                           **pmResult *****_hrap_**);**
           **int pmUnpackEventRecords(pmValueSet ***_vsp_**, int** _idx_**,**
                                    **pmResult_v2 *****_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_HIGHRES_EVENT** and a _pmResult_v2_ when using a metric with a
           value of type **PM_TYPE_EVENT**.
    
           **pmUnpackHighResEventRecords** and  **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 either
           _pmResult_  or  _pmResult_v2_ structures, one per event record and one
           metric per event parameter, and _hrap_  or  _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 _pmResult_ allows for nanosecond precision, whereas _pmRe‐_
           _sult_v2_ 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 cor‐
               responding _pmResult_ /_pmResult_v2_ will have the flags value en‐
               coded 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_ /_pmResult_v2_ 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.
    
           **pmUnpackHighResEventRecords** returns the number of _pmResult_ struc‐
           tures as the return value, which is >= 0 for success.  Similarly,
           **pmUnpackEventRecords** returns the number of _pmResult_v2_ structures
           as the return value, which is >= 0 for success.
    
           _hrap_ and the associated _pmResult_ structures may be freed using the
           convenience function pmFreeHighResEventResult(3).
    
           Similarly, _rap_ and the associated _pmResult_v2_ 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_HIGHRES_EVENT** for
                  **pmUnpackHighResEventRecords** or **PM_TYPE_EVENT** for **pmUnpack‐**
                  **EventRecords**.
    
           PM_ERR_TOOSMALL
                  The value identified by _vsp_ is not legal because the value
                  length is less than the minimum size, or the number of
                  event records encoded in the (value header) _pmHighResEven‐_
                  _tArray_ /_pmEventArray_ 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_AGGRE‐**
                  **GATE_STATIC**.
    
           other values < 0
                  refer to pmErrStr(3).
    


* * *