1PMFETCHARCHIVE(3)          Library Functions Manual          PMFETCHARCHIVE(3)
2
3
4

NAME

6       pmFetchArchive,  pmFetchHighResArchive  - get performance metric values
7       directly from archives
8

C SYNOPSIS

10       #include <pcp/pmapi.h>
11
12       int pmFetchArchive(pmResult **result);
13       int pmFetchHighResArchive(pmHighResResult **result);
14
15       cc ... -lpcp
16

DESCRIPTION

18       The pmFetchArchive and pmFetchHighResArchive APIs are variants  of  the
19       pmFetch(3)  and pmFetchHighRes(3) interfaces that may only be used when
20       the  current  Performance  Metrics  Application  Programming  Interface
21       (PMAPI) context is associated with a set of archives.
22
23       The result is instantiated with all of the metrics (and instances) from
24       the next archive record, consequently there is no notion of a  list  of
25       desired  metrics,  and the instance profile of the PMAPI context is ig‐
26       nored.
27
28       pmFetchArchive and pmFetchHighResArchive may return a result  in  which
29       numpmid  is  zero.   This  is a <mark> record that indicates a temporal
30       discontinuity in the time series of performance metrics.  This can hap‐
31       pen at the boundary between archives in a set or if the archive associ‐
32       ated with the current PMAPI context was created  using  pmlogextract(1)
33       to  concatenate two or more PCP archives, and the <mark> record marks a
34       point in time between the end of one input archive and the start of the
35       next input archive.
36
37       It  is  expected  that pmFetchArchive and pmFetchHighResArchive will be
38       used to create utilities that scan sets of  archives,  while  the  more
39       common access to the archives would be via the pmFetch and pmFetchHigh‐
40       Res interfaces.
41
42       To skip records within the set of archives, use pmSetMode(3) or  pmSet‐
43       ModeHighRes(3)  to  change the collection time within the current PMAPI
44       context, then call either pmFetchArchive or pmFetchHighResArchive.
45
46       Note that the result returned by both pmFetchArchive and pmFetchHighRe‐
47       sArchive  is  dynamically  allocated, and must be released using either
48       pmFreeResult(3) or pmFreeHighResResult(3), but not  free(3).   See  pm‐
49       Fetch(3), pmFetchHighRes(3), pmFreeResult(3) and pmFreeHighResResult(3)
50       for further details.
51
52       Both pmFetchArchive and pmFetchHighResArchive returns zero on success.
53

DIAGNOSTICS

55       PM_ERR_NOTARCHIVE
56              the current PMAPI context is not associated with a  set  of  ar‐
57              chives
58

SEE ALSO

60       PMAPI(3),   pmFetchHighRes(3),   pmSetModeHighRes(3),  pmFreeHighResRe‐
61       sult(3), pmFetch(3), pmFreeResult(3), pmNewContext(3), pmSetMode(3) and
62       pmTrimNameSpace(3).
63
64
65
66Performance Co-Pilot                  PCP                    PMFETCHARCHIVE(3)
Impressum