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       ·  Metrics and instance domains, as defined by pmiAddMetric(3).
37
38       ·  Instances for each instance domain, as defined by pmiAddInstance(3).
39
40       ·  Handles  as  defined  by  pmiGetHandle(3).  Each handle is a metric-
41          instance pair, and each metric-instance pair may have an  associated
42          value in each record written to the output PCP archive.
43
44       ·  An optional set of data values for one or more metric-instance pairs
45          (ready for the next record to be written to the output PCP  archive)
46          as defined by calls to pmPutValue(3) or pmPutValuehandle(3).
47
48       If inherit is true, then the new context will inherit any and all meta‐
49       data (metrics, instance domains, instances and handles) from  the  cur‐
50       rent  context,  otherwise  the new context is created with no metadata.
51       The basename for the output  PCP  archive,  the  source  hostname,  the
52       source  timezone  and  any data values from the current context are not
53       inherited.  If this is the first call to pmiStart the metadata will  be
54       empty independent of the value of inherit.
55
56       Since  no  physical  files  for  the output PCP archive will be created
57       until the first call to pmiWrite(3) or pmiPutRecord(3),  archive  could
58       be NULL to create a convenience context that is populated with metadata
59       to be inherited by subsequent contexts.
60
61       The return value is a context identifier that could be used in a subse‐
62       quent  call  to pmUseContext(3) and the new context becomes the current
63       context which persists for all subsequent calls up  to  either  another
64       pmiStart call or a call to pmiUseContext(3) or a call to pmiEnd(3).
65

DIAGNOSTICS

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

SEE ALSO

74       LOGIMPORT(3),     pmiAddInstance(3),     pmiAddMetric(3),    pmiEnd(3),
75       pmiErrStr(3), pmiGetHandle(3), pmiPutResult(3), pmiPutValue(3), pmiPut‐
76       ValueHandle(3),  pmiSetHostname(3), pmiSetTimezone(3), pmiUseContext(3)
77       and pmiWrite(3).
78
79
80
81Performance Co-Pilot                                               PMISTART(3)
Impressum