.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" 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 "CFETOOLUPDATE 8"
.TH CFETOOLUPDATE 8 "2004-09-21" "perl v5.8.4" "User Contributed Perl Documentation"
.SH "NAME"
cfetoolupdate \- Update the database with a new value
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBcfetool\fR \fBupdate\fR \fIname\fR
\&\fB\-\-value\fR|\fB\-V\fR\ \fIvalue\fR
[\fB\-\-path\fR|\fB\-p\fR\ \fIdirectory\ name\fR]
[\fB\-\-time\fR|\fB\-t\fR\ \fIseconds\fR]
[\fB\-\-daily\fR|\fB\-d\fR]
[\fB\-\-weekly\fR|\fB\-w\fR]
[\fB\-\-yearly\fR|\fB\-y\fR]
[\fB\-\-cfenvd\fR|\fB\-c\fR]
[\fB\-\-histograms\fR|\fB\-H\fR]
[\fB\-\-verbose\fR|\fB\-v\fR]
[\fB\-\-help\fR|\fB\-h\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Takes a new value and uses it to update the database specified by \fIname\fR,
located at the path specified by the \fB\-p\fR argument, or the current working
directory if the \fB\-p\fR argument is omitted. The value will be associated with
the current time, unless the \fB\-t\fR option is given. In order for cfetool to
function properly, this command should be issued at least once during each
interval specified by the \fB\-\-step\fR option of \f(CW\*(C`cfetool create\*(C'\fR.
.PP
The \fB\-d\fR, \fB\-w\fR and \fB\-y\fR options specify the databases to update. If all
three options are omitted, only the weekly database will be updated.  
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-\-value\fR|\fB\-v\fR \fIvalue\fR" 4
.IX Item "--value|-v value"
Specifies a new value to update the database with.
.IP "\fB\-\-path\fR|\fB\-p\fR \fIdirectory name\fR" 4
.IX Item "--path|-p directory name"
The directory in which the database specified by \fIname\fR can be found.
.IP "\fB\-\-time\fR|\fB\-t\fR" 4
.IX Item "--time|-t"
The time the value was collected, in seconds since epoch (January 1st, 1970).
If this argument is omitted, the current time will be used.
.IP "\fB\-\-daily\fR|\fB\-d\fR" 4
.IX Item "--daily|-d"
Update the daily averages database. 
.IP "\fB\-\-weekly\fR|\fB\-w\fR" 4
.IX Item "--weekly|-w"
Update the weekly averages database.
.IP "\fB\-\-yearly\fR|\fB\-y\fR" 4
.IX Item "--yearly|-y"
Update the yearly averages database.
.IP "\fB\-\-cfenvd\fR|\fB\-c\fR" 4
.IX Item "--cfenvd|-c"
Communicate with cfengine. If this option is specified, cfetool will define
classes understandable by cfagent. For more information, refer to the
documentation for \fBcfenvd\fR.
.IP "\fB\-\-histograms\fR|\fB\-H\fR" 4
.IX Item "--histograms|-H"
Collect histogram information about the probability distribiution of
fluctuations about the mean value over all times of day. Cfetool won't
write anything to this file for the first four weeks, as it has to have
reliable mean values in order to accurately calculate it.
.IP "\fB\-\-verbose\fR|\fB\-v\fR" 4
.IX Item "--verbose|-v"
Print details of the command's execution to the standard output stream.
.IP "\fB\-\-help\fR|\fB\-h\fR" 4
.IX Item "--help|-h"
Print a short help message and then exit.
.SH "OUTPUT"
.IX Header "OUTPUT"
Before exiting, \f(CW\*(C`cfetool update\*(C'\fR will print one line to the standard output
stream in the following format:
.PP
yrly=\fIynum\fR,wkly=\fIwnum\fR,dly=\fIdnum\fR
.PP
\&\fIynum\fR, \fIwnum\fR and \fIdnum\fR will be either the number 0 if the corresponding
database was not updated, or a code indicating the state of the given statistic,
as compared to an average of equivalent earlier times, as specified below:
.PP
.Vb 27
\& code    high|low|normal   meaning
\& -------------------------------------------------------------
\&  \-2     -                 no sigma variation
\& -------------------------------------------------------------
\&  \-4     low               within noise threshold, and within
\&  \-5     normal              2 standard deviations from
\&  \-6     high                expected value
\& -------------------------------------------------------------
\& \-14     low               microanomaly: within noise
\& \-15     normal              threshold, but 2 or more standard
\& \-16     high                deviations from expected value
\& -------------------------------------------------------------
\& \-24     low               normal; within 1 standard deviation
\& \-25     normal              from the expected value
\& \-26     high                
\& -------------------------------------------------------------
\& \-34     low               dev1; more than 1 standard 
\& \-35     normal              deviation from the expected
\& \-36     high                value
\& ------------------------------------------------------------
\& \-44     low               dev2; more than 2 standard
\& \-45     normal              deviations from the expected
\& \-46     high                value
\& -------------------------------------------------------------
\& \-54     low               anomaly; more than 3 standard
\& \-55     normal              deviations from the expected
\& \-56     high                value
.Ve
.PP
Where \*(L"low\*(R" indicates that the current value is below both the expected value
for the current time position, and the global average value. \*(L"high\*(R" indicates
that the current value is above those values. \*(L"normal\*(R" indicates that the
current value is within the range of expected values.
.PP
\&\f(CW\*(C`cfetool update\*(C'\fR also exits with a code corresponding to the above table. If
more than one database is being updated, the most negative result from the
updates is returned, and the individual results must be obtained from the
standard output stream, as described above.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
.Vb 2
\&  % cfetool update temperature \-\-path /my/path \-\-value 14.5 \-\-histograms
\&  yrly=0,wkly=-6,dly=0
.Ve
.PP
Updates the weekly temperature database and histogram files located in
\&\fB/my/path/\fR with the value 14.5 using the current time as the update time. The
output indicates that only a weekly database was updated, and the new value
given was within cfetool's noise threshold, and also within 2 standard
deviations of the previous average stored in the database.
.SH "AUTHORS"
.IX Header "AUTHORS"
The code and documentation were contributed by Stanford Linear Accelerator
Center, a department of Stanford University.
This documentation was written by
.IP "Elizabeth Cassell <e_a_c@mailsnare.net> and" 4
.IX Item "Elizabeth Cassell <e_a_c@mailsnare.net> and"
.PD 0
.IP "Alf Wachsmann <alfw@slac.stanford.edu>" 4
.IX Item "Alf Wachsmann <alfw@slac.stanford.edu>"
.PD
.SH "COPYRIGHT AND DISCLAIMER"
.IX Header "COPYRIGHT AND DISCLAIMER"
.Vb 3
\& Copyright 2004 Alf Wachsmann <alfw@slac.stanford.edu> and
\&                Elizabeth Cassell <e_a_c@mailsnare.net>
\& All rights reserved.
.Ve