'\"macro stdmacro
.\"
.\" Copyright (c) 2010 Ken McDonell.  All Rights Reserved.
.\" Copyright (c) 2018 Red Hat.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMIPUTRESULT 3 "" "Performance Co-Pilot"
.SH NAME
\f3pmiPutResult\f1,
\f3pmiPutHighResResult\f1 \- add a data record to a LOGIMPORT archive
.SH "C SYNOPSIS"
.ft 3
.ad l
.hy 0
#include <pcp/pmapi.h>
.br
#include <pcp/import.h>
.sp
int pmiPutResult(const pmResult_v2 *\fIresult\fP);
.br
int pmiPutHighResResult(const pmResult *\fIresult\fP);
.sp
cc ... \-lpcp_import \-lpcp
.hy
.ad
.ft 1
.SH "Python SYNOPSIS"
.ft 3
.ad l
.hy 0
from pcp import pmi
.sp
log.put_result(\fIresult\fP)
.br
log.put_highres_result(\fIresult\fP)
.hy
.ad
.ft 1
.SH DESCRIPTION
As part of the Performance Co-Pilot Log Import API (see
.BR LOGIMPORT (3)),
these routines provide an interface for developers familiar with the internal
PCP data structures to create output archives directly.
.PP
By building a
.B pmResult
data structure directly and calling one of these routines, the developer
avoids the separate
.BR pmiPutValue (3)
and/or
.BR pmiPutValueHandle (3)
calls followed by
.BR pmiHighResWrite (3)
for each record written to the archive.
.PP
.B pmiPutHighResResult
is the preferred interface.
It accepts a
.B pmResult
with a
.B struct timespec
timestamp, giving nanosecond resolution and Y2038-safe 64-bit seconds.
.PP
.B pmiPutResult
accepts the older
.B pmResult_v2
type with a
.B struct timeval
timestamp (microsecond resolution).
.PP
Any metrics and instances appearing in
.I result
must have been defined by prior calls to
.BR pmiAddMetric (3)
and
.BR pmiAddInstance (3).
Both routines will arrange for any new metadata (metrics and/or instance
domain changes) covered by
.I result
to be written to the PCP archive.
.PP
Because of the complexity of the
.B pmResult
data structure, neither routine is available in the Perl
interface to the LOGIMPORT services.
.SH DIAGNOSTICS
Both routines return zero on success else a negative value that can be
turned into an error message by calling
.BR pmiErrStr (3).
.SH SEE ALSO
.BR LOGIMPORT (3),
.BR PMAPI (3),
.BR pmiAddInstance (3),
.BR pmiAddMetric (3),
.BR pmiErrStr (3),
.BR pmiPutValue (3),
.BR pmiPutText (3),
.BR pmiPutLabel (3),
.BR pmiPutValueHandle (3),
.BR pmiSetTimezone (3),
.BR pmiHighResWrite (3)
and
.BR pmiWrite (3).