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

NAME

6       pmiStart - establish a new LOGIMPORT context
7

C SYNOPSIS

9       #include <pcp/pmapi.h>
10       #include <pcp/import.h>
11
12       int pmiStart(const char *archive, int inherit);
13
14       cc ... -lpcp_import -lpcp
15

Perl SYNOPSIS

17       use PCP::LogImport;
18
19       pmiStart($archive, $inherit);
20

DESCRIPTION

22       As  part of the Performance Co-Pilot Log Import API (see LOGIMPORT(3)),
23       pmiStart creates a new context.  Each context maintains  the  following
24       state and metadata:
25
26       •  The  base name (archive) for the physical  files that constitute the
27          output PCP archive.
28
29       •  The source hostname for the data that will be written to the PCP ar‐
30          chive.   Defaults  to  the hostname of the localhost, but can be set
31          using pmiSetHostname(3).
32
33       •  The source timezone for the PCP archive.  Defaults to  the  timezone
34          of the localhost, but can be set using pmiSetTimezone(3).
35
36       •  The  output archive version number for the PCP archive.  Defaults to
37          the traditional version 2 format, but can be  set  using  pmiSetVer‐
38          sion(3).
39
40       •  Metrics and instance domains, as defined by pmiAddMetric(3).
41
42       •  Instances for each instance domain, as defined by pmiAddInstance(3).
43
44       •  Handles  as defined by pmiGetHandle(3).  Each handle is a metric-in‐
45          stance pair, and each metric-instance pair may  have  an  associated
46          value in each record written to the output PCP archive.
47
48       •  An optional set of data values for one or more metric-instance pairs
49          (ready for the next record to be written to the output PCP  archive)
50          as defined by calls to pmPutValue(3) or pmPutValuehandle(3).
51
52       If inherit is true, then the new context will inherit any and all meta‐
53       data (metrics, instance domains, instances and handles) from  the  cur‐
54       rent  context,  otherwise  the new context is created with no metadata.
55       The basename for the output  PCP  archive,  the  source  hostname,  the
56       source  timezone  and  any data values from the current context are not
57       inherited.  If this is the first call to pmiStart the metadata will  be
58       empty independent of the value of inherit.
59
60       Since  no physical files for the output PCP archive will be created un‐
61       til the first call to pmiWrite(3) or pmiPutRecord(3), archive could  be
62       NULL to create a convenience context that is populated with metadata to
63       be inherited by subsequent contexts.
64
65       The return value is a context identifier that could be used in a subse‐
66       quent  call  to pmUseContext(3) and the new context becomes the current
67       context which persists for all subsequent calls up  to  either  another
68       pmiStart call or a call to pmiUseContext(3) or a call to pmiEnd(3).
69

DIAGNOSTICS

71       It  is  an  error  if the physical files archive.0 and/or archive.index
72       and/or archive.meta already exist, but this is not discovered until the
73       first  attempt  is  made  to output some data by calling pmiWrite(3) or
74       pmiPutRecord(3), so pmiStart always returns a positive context  identi‐
75       fier.
76

SEE ALSO

78       LOGIMPORT(3),     pmiAddInstance(3),     pmiAddMetric(3),    pmiEnd(3),
79       pmiErrStr(3), pmiGetHandle(3), pmiPutResult(3), pmiPutValue(3), pmiPut‐
80       ValueHandle(3),   pmiPutText(3),   pmiPutLabel(3),   pmiSetHostname(3),
81       pmiSetTimezone(3), pmiSetVersion(3), pmiUseContext(3) and pmiWrite(3).
82
83
84
85Performance Co-Pilot                                               PMISTART(3)
Impressum