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/impl.h>
11       #include <pcp/import.h>
12
13       int pmiStart(const char *archive, int inherit);
14
15       cc ... -lpcp_import -lpcp
16

Perl SYNOPSIS

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

DESCRIPTION

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

DIAGNOSTICS

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

SEE ALSO

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