NAME

       pmFetchArchive,  pmFetchHighResArchive  -  get  performance  metric  values  directly from
       archives

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmFetchArchive(pmResult **result);
       int pmFetchHighResArchive(pmHighResResult **result);

       cc ... -lpcp

DESCRIPTION

       The pmFetchArchive and pmFetchHighResArchive APIs  are  variants  of  the  pmFetch(3)  and
       pmFetchHighRes(3)  interfaces  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,  consequently  there  is  no notion of a list of desired metrics, and the instance
       profile of the PMAPI context is ignored.

       pmFetchArchive and pmFetchHighResArchive 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 archives in a set or if  the
       archive  associated  with  the  current PMAPI context was created using pmlogextract(1) to
       concatenate two or more PCP archives, 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  and  pmFetchHighResArchive  will be used to create
       utilities that scan sets of archives, while the more common access to the  archives  would
       be via the pmFetch and pmFetchHighRes interfaces.

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

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

       Both pmFetchArchive and pmFetchHighResArchive returns zero on success.

DIAGNOSTICS

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

SEE ALSO

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