'\"macro stdmacro
.\"
.\" Copyright (c) 2022 Ken McDonell.  All Rights Reserved.
.\"
.\" 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 PMAREWRITEDATA 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmaRewriteData\f1 \- try to change the version of an archive data record
.SH "C SYNOPSIS"
.ft 3
#include <pcp/pmapi.h>
.br
#include <pcp/libpcp.h>
.br
#include <pcp/archive.h>
.sp
int pmaRewriteData(int \fIinvers\fP, int \fIoutvers\fP __int32_t *\fIrbuf\fP);
.sp
cc ... \-lpcp_archive \-lpcp
.ft 1
.SH CAVEAT
This documentation is intended for internal Performance Co-Pilot
(PCP) developer use.
.PP
These interfaces are not part of the PCP APIs that are guaranteed to
remain fixed across releases, and they may not work, or may provide
different semantics at some point in the future.
.SH DESCRIPTION
.de CR
.ie t \f(CR\\$1\fR\\$2
.el \fI\\$1\fR\\$2
..
A physical data record from a version
.I invers
archive is passed in via
.I rbuf
and this is reformatted if
required to produce the equivalent data record for a version
.I outvers
archive.
.PP
Archive data records provide the encoding of a
.B pmResult
for an archive data volume.
.PP
The only sane choice of
.I invers
and
.I outvers
today is
.B PM_LOG_VERS02
and
.B PM_LOG_VERS03
respectively,
which would be requesting a rewrite from archive version 2 format
to archive version 3 format
(as only versions 2 and 3 are currently supported).
.PP
If rewriting takes place the old
.I rbuf
will have been free'd and a new
.I rbuf
allocated with
.BR malloc (3).
It is the caller's responsibility to make sure
this potential free-and-allocate will be safe, e.g. no dangling references
into the contents of
.IR rbuf ,
or pass in a copy of
the record if it is precious.
.SH DIAGNOSTICS AND RETURN VALUES
In several places, fatal errors will trigger an error message and
force the application to exit.
.PP
If there is no defined translation from
.I invers
to
.I outvers
then
.B pmaRewriteData
returns
.B PM_ERR_APPVERSION
(a slight perversion of this error code).
.PP
If no rewrite is performed, the return value is 0, otherwise a return value
of 1 indicates a rewrite has taken place and
.I rbuf
has been reallocated.
.SH SEE ALSO
.BR free (3),
.BR malloc (3),
.BR PMAPI (3),
and
.BR pmaRewriteMeta (3).