.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" 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" ''
'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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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 "SHEET2PCP 1"
.TH SHEET2PCP 1 "Performance Co-Pilot" "3.3.2" "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"
sheet2pcp \- Import spreadsheet data and create a PCP archive
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBsheet2pcp\fR \fIinfile\fR \fImapfile\fR \fIoutfile\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBsheet2pcp\fR is intended to read a data spreadsheet (\fIinfile\fR)
translate this into a Performance
Co-Pilot (\s-1PCP\s0) archive with the basename \fIoutfile\fR.
.PP
The input spreadsheet can be in any of the common formats, provided
the appropriate Perl modules have been installed (see the \fB\s-1CAVEATS\s0\fR
section below).  The spreadsheet must be \*(L"normalized\*(R"
so that each row contains data for the same time interval, and one
of the columns contains the date and time for the data in each
row.
.PP
The resultant \s-1PCP\s0 archive 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
The \fImapfile\fR controls the import process and defines the data
mapping from the spreadsheet columns onto the \s-1PCP\s0 data model.  The file
is written in \s-1XML\s0 (Version 1.0) and conforms to the syntax defined in the
\&\fB\s-1MAPPING\s0 \s-1CONFIGURATION\s0\fR section below.
.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 \fBsheet2pcp\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
\&\fBsheet2pcp\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.
.SH "MAPPING CONFIGURATION"
.IX Header "MAPPING CONFIGURATION"
The \fImapfile\fR contains specifications in standard \s-1XML\s0 1.0 format.
.PP
The whole specification is wrapped in a \fB<sheet>\fR ... \fB</sheet>\fR
element.
The  \fBsheet\fR tag supports the following optional attributes:
.IP "\fBheading\fR" 10
.IX Item "heading"
Specifies the number of
heading rows to skip at the start of the spreadsheet before processing data.
Example: heading=\*(L"1\*(R".
.IP "\fBhostname\fR" 10
.IX Item "hostname"
Set the source hostname in the \s-1PCP\s0 archive (the
default is to use the hostname of the local host).
Example: hostname=\*(L"some.where.com\*(R".
.IP "\fBtimezone\fR" 10
.IX Item "timezone"
Set the source timezone in the \s-1PCP\s0 archive (the
default is to use \s-1UTC\s0).
Example: timezone=\*(L"+1100\*(R".
.IP "\fBdatefmt\fR" 10
.IX Item "datefmt"
The format of the date imported from the spreadsheet may be specified
as a concatenation of
values that specify the
order of the year (\fBY\fR), month (\fBM\fR) and day (\fBD\fR) fields in a date.
The supported variants are \fB\s-1DMY\s0\fR (the default),
\&\fB\s-1MDY\s0\fR and \fB\s-1YMD\s0\fR.
Example: datefmt=\*(L"\s-1YMD\s0\*(R".
.PP
Thereafter follow one or more metric specifications of
the form \fB<metric>\fR\fImetricname\fR\fB</metric>\fR.  The \fBmetric\fR
tag supports the following optional attributes:
.IP "\fBpmid\fR" 10
.IX Item "pmid"
The Performance Metrics Identifier (\s-1PMID\s0), specified as 3 numbers
separated by a periods (.) to
set the \fBdomain\fR, \fBcluster\fR and \fBitem\fR fields of the \s-1PMID\s0, see \fB\s-1PMNS\s0\fR(4)
for more details of PMIDs.  If omitted, the \s-1PMID\s0 will be automatically
assigned by \fBpmiAddMetric\fR(3) and this would be the most common case.
The value \fB\s-1PM_ID_NULL\s0\fR may be used to explicitly nominate
the default behaviour.
Examples: pmid=\*(L"60.0.2\*(R", pmid=\*(L"\s-1PM_ID_NULL\s0\*(R".
.IP "\fBindom\fR" 10
.IX Item "indom"
Each metric may have one or more values associated with it.  If there is only
ever one value, the metric is singular and \fBindom\fR should be set to \fB\s-1PM_INDOM_NULL\s0\fR
which is the default case when the \fBindom\fR attribute is omitted.
Otherwise \fBindom\fR should be specified as 2 numbers separated by periods (.)
to set the \fBdomain\fR and \fBordinal\fR fields of the Instance Domain.  More than
one metric can share the same Instance Domain when the metrics have defined
values over similar sets of instances, e.g. all the metrics for each network
interface.  It is standard practice for the \fBdomain\fR field to be the
same for the \fBpmid\fR and the \fBindom\fR; if the \fBpmid\fR attribute is missing,
then the \fBdomain\fR field for the \fBindom\fR should be the reserved domain
\&\fB\s-1PMI_DOMAIN\s0\fR.
Examples: indom=\*(L"\s-1PM_INDOM_NULL\s0\*(R", indom=\*(L"60.3\*(R", indom=\*(L"\s-1PMI_DOMAIN\s0.4\*(R".
.IP "\fBunits\fR" 10
.IX Item "units"
The scale and dimension of the metric values along the axes of space, time
and count (events, messages, packets, etc.) is specified with a 6\-tuple.
These values are passed to the \fBpmiUnits\fR(3) function to generate a
\&\fIpmUnits\fR structure.  Refer to \fBpmLookupDesc\fR(3) for a full description
of all the fields of this structure.
The default is to assign no scale or dimension to the metric, i.e. units=\*(L"0,0,0,0,0,0\*(R".
Examples: units=\*(L"0,1,0,0,PM_TIME_MSEC,0\*(R" (milliseconds),
units=\*(L"1,\-1,0,PM_SPACE_MBYTE,PM_TIME_SEC,0\*(R" (Mbytes/sec),
units=\*(L"0,1,\-1,0,PM_TIME_USEC,PM_COUNT_ONE\*(R" (microseconds/event).
.IP "\fBtype\fR" 10
.IX Item "type"
Defines the data type for the metric.
Refer to \fBpmLookupDesc\fR(3) for a full description
of the possible type values; the default is \fB\s-1PM_TYPE_FLOAT\s0\fR.
Examples: type=\*(L"\s-1PM_TYPE_32\s0\*(R", type=\*(L"\s-1PM_TYPE_U64\s0\*(R", type=\*(L"\s-1PM_TYPE_STRING\s0\*(R".
.IP "\fBsem\fR" 10
.IX Item "sem"
Defines the semantics of the metric.
Refer to \fBpmLookupDesc\fR(3) for a full description
of the possible values; the default is \fB\s-1PM_SEM_INSTANT\s0\fR.
Examples: sem=\*(L"\s-1PM_SEM_COUNTER\s0\*(R", type=\*(L"\s-1PM_SEM_DISCRETE\s0\*(R".
.PP
The remaining specifications define the data columns \fBin order\fR using
\&\fBexactly\fR one \fB<datetime>\fR\fB</datetime>\fR element,
one or more \fB<data>\fR\fImetricspec\fR\fB</data>\fR elements
and
one or more \fB<skip>\fR\fB</skip>\fR elements.
.PP
The \fB<datetime>\fR element defines the column in which a date and time will
be found to form the timestamp in the \s-1PCP\s0 archive for all the data in
each row of the \s-1PCP\s0 archive.
.PP
For the \fB<data>\fR element,
a \fImetricspec\fR
consists of a metric name (as defined in an earlier \fB<metric>\fR
element), optionally followed by an instance name that is enclosed by square brackets,
e.g. <data>hinv.ncpu</data>, <data>kernel.all.load[1 minute]</data>.
.PP
The \fBskip\fR tag defines the column that should be skipped when preparing
data for the \s-1PCP\s0 archive.
.SS "\s-1EXAMPLE\s0"
.IX Subsection "EXAMPLE"
The \fImapfile\fR ...
.PP
.Vb 11
\&    <?xml version="1.0" encoding="UTF\-8"?>
\&    <sheet heading="1">
\&        <!\-\- simple example \-\->
\&        <metric pmid="60.0.2" indom="60.0" units="0,1,0,0,PM_TIME_MSEC,0"
\&            type="PM_TYPE_U64" sem="PM_SEM_COUNTER">
\&        kernel.percpu.cpu.sys</metric>
\&        <datetime></datetime>
\&        <skip></skip>
\&        <data>kernel.percpu.cpu.sys[cpu0]</data>
\&        <data>kernel.percpu.cpu.sys[cpu1]</data>
\&    </sheet>
.Ve
.PP
could be used for a spreadsheet in which the first few rows are ...
.PP
.Vb 4
\&    Date;"Status";"SysTime \- 0";"SysTime \- 1";
\&    26/01/2001 14:05:22;"Some Busy";0.750;0.133
\&    26/01/2001 14:05:37;"OK";0.150;0.273
\&    26/01/2001 14:05:52;"All Busy";0.733;0.653
.Ve
.SH "CAVEATS"
.IX Header "CAVEATS"
Only the first sheet from \fIinfile\fR will be processed.
.PP
Additional Perl modules must be installed for the various spreadsheet formats,
although these are checked for ar run-time so only the modules required for
the specific types of spreadsheets you wish to process need be installed:
.IP "\fB*.csv\fR" 6
.IX Item "*.csv"
Spreadsheets in the Comma Separated Values (\s-1CSV\s0) format require \fBText::CSV_XS\fR(3pm).
.IP "\fB*.sxc\fR or \fB*.ods\fR" 6
.IX Item "*.sxc or *.ods"
OpenOffice documents require \fBSpreadsheet::ReadSXC\fR(3pm), which in turn
requires \fBArchive::Zip\fR(3pm).
.IP "\fB*.xls\fR" 6
.IX Item "*.xls"
Classical Microsoft Office documents require \fBSpreadsheet::ParseExcel\fR(3pm),
which in turn requires \fBOLE::Storage_Lite\fR(3pm).
.IP "\fB*.xlsx\fR" 6
.IX Item "*.xlsx"
Microsoft OpenXML documents require \fBSpreadsheet::XLSX\fR(3pm).  \fBsheet2pcp\fR
does not appear to work with OpenXML documents saved from OpenOffice.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBArchive::Zip\fR(3pm),
\&\fBDate::Format\fR(3pm),
\&\fBDate::Parse\fR(3pm),
\&\fBlogimport\fR(3),
\&\fBOLE::Storage_Lite\fR(3pm),
\&\fBPCP::LogImport\fR(3pm),
\&\fBpmchart\fR(1),
\&\fBpmiAddMetric\fR(3), 
\&\fBpmie\fR(1),
\&\fBpmiUnits\fR(3),
\&\fBpmlogger\fR(1),
\&\fBpmLookupDesc\fR(3),
\&\fB\s-1PMNS\s0\fR(4),
\&\fBSpreadsheet::ParseExcel\fR(3pm),
\&\fBSpreadsheet::ReadSXC\fR(3pm),
\&\fBSpreadsheet::XLSX\fR(3pm),
\&\fBText::CSV_XS\fR(3pm)
and
\&\fBXML::TokeParser\fR(3pm).