NAME

       pmFetchArchive - get performance metrics directly from a set if archive logs

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmFetchArchive(pmResult **result);

       cc ... -lpcp

DESCRIPTION

       pmFetchArchive  is  a  variant  of  pmFetch(3) that may only be used when the current Performance Metrics
       Application Programming Interface (PMAPI) context is associated with a set of archive logs.

       The result is instantiated with all of  the  metrics  (and  instances)  from  the  next  archive  record,
       consequently  there  is  no  notion  of  a list of desired metrics, and the instance profile of the PMAPI
       context is ignored.

       pmFetchArchive may return a result in which numpmid is zero.  This is a <mark> record  that  indicates  a
       temporal  discontinuity  in  the  time  series  of  performance metrics.  This can happen at the boundary
       between archive logs in a set or if the archive log associated with the current PMAPI context was created
       using pmlogextract(1) to concatenate two or more PCP archive logs, and the <mark> record marks a point in
       time between the end of one input archive and the start of the next input archive.

       It is expected that pmFetchArchive would be used to create utilities that  scan  sets  of  archive  logs,
       while the more common access to the archives would be via the pmFetch(3) interface.

       To skip records within the set of archive logs, use pmSetMode(3) to change the collection time within the
       current PMAPI context, then call pmFetchArchive.

       Note that the result returned by pmFetchArchive is dynamically allocated,  and  must  be  released  using
       pmFreeResult(3), not free(3).  See pmFetch(3) and pmFreeResult(3) for further details.

       pmFetchArchive returns zero on success.

SEE ALSO

       PMAPI(3), pmFetch(3), pmFreeResult(3), pmNewContext(3), pmSetMode(3) and pmTrimNameSpace(3).

DIAGNOSTICS

       PM_ERR_NOTARCHIVE
              the current PMAPI context is not associated with a set of archive logs