NAME

       pmFetchArchive,  pmFetchHighResArchive  -  get  performance  metric  values  directly from
       archive logs

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  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  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 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  and  pmFetchHighResArchive  will be used to create
       utilities that scan sets of archive logs, while the more common  access  to  the  archives
       would be via the pmFetch and pmFetchHighRes interfaces.

       To skip records within the set of archive logs, 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 archive logs

SEE ALSO

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