pmiStart
establish a new LOGIMPORT context
- Provided by: libpcp4-dev (Version: 7.2.1-2build1)
- Source: pcp
- Report a bug
establish a new LOGIMPORT context
#include <pcp/pmapi.h>
#include <pcp/import.h>
int pmiStart(const char *archive, int flags);
cc ... -lpcp_import -lpcp
use PCP::LogImport;
pmiStart($archive, $flags);
from pcp import pmi
log = pmi.pmiLogImport(archive, flags)
As part of the Performance Co-Pilot Log Import API (see LOGIMPORT(3)), pmiStart creates a new context. Each context maintains the following state and metadata:
The flags argument is a bitwise-OR of zero or more of the following constants:
PMI_APPEND and PMI_INHERIT may be used together. The inherited metric and instance-domain definitions are carried into the new context, and when the archive is opened on the first pmiWrite(3) call, each inherited descriptor is checked against what is already on disk: compatible descriptors are silently skipped (no duplicate written); incompatible ones are rejected with an appropriate error (e.g. PM_ERR_LOGCHANGETYPE). When the previous context was writing to the same archive, every inherited descriptor already exists on disk so the combination is effectively a no-op beyond convenience.
If flags is zero, or neither PMI_INHERIT nor PMI_APPEND is set, the new context is created with no metadata and a new archive will be created from scratch.
Since no physical files for the output PCP archive will be created until the first call to pmiWrite(3) or pmiPutResult(3), archive could be NULL to create a convenience context that is populated with metadata to be inherited by subsequent contexts.
The return value is a context identifier that could be used in a subsequent call to pmUseContext(3) and the new context becomes the current context which persists for all subsequent calls up to either another pmiStart call or a call to pmiUseContext(3) or a call to pmiEnd(3).
When creating a new archive (neither PMI_APPEND nor any other flag that implies file creation), it is an error if the physical files archive.0 and/or archive.index and/or archive.meta already exist, but this is not discovered until the first attempt is made to output some data by calling pmiWrite(3) or pmiPutResult(3), so pmiStart always returns a positive context identifier.
When PMI_APPEND is set and the archive files do not exist, pmiStart silently falls back to creating a new archive, making it safe to use PMI_APPEND unconditionally on the first invocation of a data collector.
LOGIMPORT(3), PMAPI(3), pmiAddInstance(3), pmiAddMetric(3), pmiEnd(3), pmiErrStr(3), pmiGetHandle(3), pmiPutLabel(3), pmiPutResult(3), pmiPutText(3), pmiPutValue(3), pmiPutValueHandle(3), pmiSetHostname(3), pmiSetTimezone(3), pmiSetVersion(3), pmiUseContext(3) and pmiWrite(3).