NAME

       pmFetchArchive, - get performance metric values directly from archives

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmFetchArchive(pmResult **result);

       cc ... -lpcp

DESCRIPTION

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

       The  result  is instantiated with all of the metrics (and instances) from the next archive record, conse‐
       quently 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 be‐
       tween archives in a set or if the archive associated with the current PMAPI context was created using pm‐
       logextract(1) to concatenate two or more PCP archives, and the <mark> record marks a point  in  time  be‐
       tween the end of one input archive and the start of the next input archive.

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

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

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

       pmFetchArchive returns zero on success.

DIAGNOSTICS

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

COMPATIBILITY

       Prior to PCP 7.0 the timestamp field in the pmResult struct was a struct timeval.  To support PMAPI tran‐
       sition,  the  old  interface  and  semantics can be used if applications are recompiled with -DPMAPI_VER‐
       SION=2.

       For a time in PCP 6.x there was a routine with the same semantics as the  current  pmFetchArchive  called
       pmFetchHighResArchive,  and a struct with the same definition as the current pmResult struct called pmRe‐
       sultHighRes, although both are now deprecated and compile-time support for pmFetchHighResArchive and  pm‐
       ResultHighRes will be removed in a future release.

SEE ALSO

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

Performance Co-Pilot                                   PCP                                     PMFETCHARCHIVE(3)