.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SAR2PCP 1"
.TH SAR2PCP 1 "Performance Co-Pilot" "3.9.10" "Performance Co-Pilot"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
sar2pcp \- Import sar data and create a PCP archive
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBsar2pcp\fR \fIinfile\fR \fIoutfile\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBsar2pcp\fR is intended to read a binary System Activity Reporting
(sar) data file
as created by \fBsadc\fR(1) (\fIinfile\fR) and translate this into a Performance
Co-Pilot (\s-1PCP\s0) archive with the basename \fIoutfile\fR.
.PP
However, if \fIinfile\fR has the suffix \*(L".xml\*(R", then it will be considered
already in \s-1XML\s0 format and \fBsar2pcp\fR will operate directly on it.
.PP
The resultant \s-1PCP\s0 achive may be used with all the \s-1PCP\s0 client tools
to graph subsets of the data using \fBpmchart\fR(1),
perform data reduction and reporting, filter with
the \s-1PCP\s0 inference engine \fBpmie\fR(1), etc.
.PP
A series of physical files will be created with the prefix \fIoutfile\fR.
These are \fIoutfile\fR\fB.0\fR (the performance data),
\&\fIoutfile\fR\fB.meta\fR (the metadata that describes the performance data) and
\&\fIoutfile\fR\fB.index\fR (a temporal index to improve efficiency of replay
operations for the archive).  If any of these files exists already,
then \fBsar2pcp\fR will \fBnot\fR overwrite them and will exit with an error
message of the form
.PP
_\|_pmLogNewFile: \*(L"blah.0\*(R" already exists, not over-written
.PP
\&\fBsar2pcp\fR is a Perl script that uses the PCP::LogImport Perl wrapper
around the \s-1PCP \s0\fIlibpcp_import\fR
library, and as such could be used as an example to develop new
tools to import other types of performance data and create \s-1PCP\s0 archives.
A Python wrapper module is also available.
.SH "CAVEATS"
.IX Header "CAVEATS"
When not using the \s-1XML\s0 input option, \fBsar2pcp\fR requires \fIinfile\fR to
have been created by a version of \fBsadc\fR(1) from
<http://sebastien.godard.pagesperso\-orange.fr/>
which includes the \fBsadf\fR(1) utility
to translate \fIinfile\fR into an \s-1XML\s0 stream (any since version 6);
\&\fBsar2pcp\fR will automatically run \fBsadf\fR(1) and translate the resultant
\&\s-1XML\s0 into a \s-1PCP\s0 archive.
.PP
When using binary \fBsadc\fR files
it is important to ensure the installed \fBsadf\fR is compatible with the
version of \fBsadc\fR that originally generated the binary files.  Simply
assuming a newer installed version will work is unfortunately far too
optimistic, and nor should one assume that binary data from different
platforms (e.g. different endianness) will work \- these issues are due
to limitations in \fBsadc\fR and \fBsadf\fR, and not in \fBsar2pcp\fR itself.
.PP
Fortunately, the \fBsadf\fR message indicating that an incompatibility has
been detected is consistent across versions, and is always prefixed
.PP
Invalid system activity file
.PP
Using an \s-1XML \s0\fIinfile\fR has the advantage that the installed version
of \fBsadf\fR is completely bypassed.  \fBsar2pcp\fR undertakes to transform
any valid \s-1XML\s0 produced by any of the different variations of \fBsadf\fR
into a valid \s-1PCP\s0 archive.  Any version of \s-1PCP\s0 will be able to interpret
the archive files produced by any version of \fBsar2pcp\fR, and you are
also free to move the binary \s-1PCP\s0 archive between different platforms,
different hardware, even different operating systems \- it Just Works (\s-1TM\s0).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBpmie\fR(1),
\&\fBpmchart\fR(1),
\&\fBpmlogger\fR(1),
\&\fBpmlogextract\fR(1),
\&\fBpmlogsummary\fR(1),
\&\fBsadc\fR(1),
\&\fBsadf\fR(1),
\&\fBsar\fR(1),
\&\fBDate::Parse\fR(3pm),
\&\fBDate::Format\fR(3pm),
\&\fBPCP::LogImport\fR(3pm),
\&\fBXML::TokeParser\fR(3pm) and
\&\fB\s-1LOGIMPORT\s0\fR(3).