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

NAME

6       pmFetchArchive,  pmFetchHighResArchive  - get performance metric values
7       directly from archive logs
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 archive logs.
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 archive logs in a set or if the archive log
32       associated with the current PMAPI context was  created  using  pmlogex‐
33       tract(1)  to  concatenate  two or more PCP archive logs, and the <mark>
34       record marks a point in time between the end of one input  archive  and
35       the start of the next input archive.
36
37       It  is  expected  that pmFetchArchive and pmFetchHighResArchive will be
38       used to create utilities that scan sets of archive logs, 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 archive logs, use pmSetMode(3) or pm‐
43       SetModeHighRes(3)  to  change  the  collection  time within the current
44       PMAPI  context,  then  call  either  pmFetchArchive  or  pmFetchHighRe‐
45       sArchive.
46
47       Note that the result returned by both pmFetchArchive and pmFetchHighRe‐
48       sArchive is dynamically allocated, and must be  released  using  either
49       pmFreeResult(3)  or  pmFreeHighResResult(3),  but not free(3).  See pm‐
50       Fetch(3), pmFetchHighRes(3), pmFreeResult(3) and pmFreeHighResResult(3)
51       for further details.
52
53       Both pmFetchArchive and pmFetchHighResArchive returns zero on success.
54

DIAGNOSTICS

56       PM_ERR_NOTARCHIVE
57              the  current  PMAPI  context is not associated with a set of ar‐
58              chive logs
59

SEE ALSO

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