CSVPNG V1.0-147                                         11-Jul-2008

     Copyright 2002-2008 Hewlett-Packard Development Company, L.P.

CSVPNG generates PNG format graphs from CSV Files. It can also be used to extract
selected columns of data to new CSV files.

It was developed to facilitate automated graphing and analysis of OpenVMS T4
performance data but can be used for many types of CSV data. ECP data on
OpenVMS and Perfmon Windows data have been successfully used. T4 is a tool
developed by OpenVMS Engineering which converts the Monitor utility output
to Comma Separated Value format files. Using CSVPNG, the CSV files are
processed on the OpenVMS system and graphs meeting predefined filters are
generated. CSVPNG is available for Alpha and Integrity versions of OpenVMS, as 
well as for Windows, HP-UX, or Linux systems where it can be used for interactive 
analysis or manipulation of CSV data.

To use the OpenVMS version you must first define a 'foreign command' as follows:

$CSVPNG :== $<disk:><dir>CSVPNG_ALPHA.EXE

If processing very large CSV files on an OpenVMS system you may need to increase
PGFLQUOTA to about 800000.

For CSV files spanning extremely long lines, or with hundreds of parameters, it may 
be necessay to define some environmental variables. Default values are:

Maximum line length of parameter names line in Format 1 CSV file: MAXLINE=220000
Maximum line length of parameter names lines in Format 2 CSV file: MAXF2LEN=15000
Maximum line length of data rows in CSV file: MAXDATA=50000
Maximum number of rows in CSV file: MAXINTERVALS=50000

To specify the number of Format 2 parameter headings per line in output CSV files,
an environmental variable, MAXF2OUTPAR (default 6), can be used.

Examples:

On DOS: SET MAXLINE=300000, SET MAXDATA=75000, SET MAXINTERVALS=100000, SET MAXF2OUTPAR=1
On OpenVMS the syntax is: $define MAXLINE 300000

Note: You may exceed the memory available in your computer if high values are used
for all environmental variables.

The general format of a CSVPNG command is:

   csvpng [options] <csv file 1> [csv file2] ...

At least one CSV file must be specified. If more than one file is specified,
the matching parameters from all the files are shown on the same chart. The
files may be specified in any order but CSVPNG will reorder the input files
in chronological order.

Options may be specified using either '-', '--' or '/' as a prefix. If an option
requires a value, use '=' to specify. A space is not allowed immediately following
the'='. On Linux, you cannot use '/' so use '--' instead.

The generated charts are .PNG files and a HTML file, CSVPNG.HTM, is generated
which will display all the graphs. On a Windows system, view CSVPNG.HTM in a
browser to see the charts. On OpenVMS, view the html file using a suitable
browser, e.g. Mozilla, or via a web browser from another system.

Options:

Note: -- may be used instead of /


/?    Displays usage text.
-?


/append[=outputfile]
-A[=outputfile]

      Concatenates two or more CSV files. This is useful to create a continuous
      history from daily T4 files. The input files must have the same number of
      columns. No charts are created.

      Up to 200 files can be appended but the practical limit may be lower
      depending on file sizes and your system's memory.

      Example: csvpng t4_1.csv t4_2.csv /para=all/append=t4_3.csv

      See also /merge which can also be used to append files.


/average[=val][:0]
-a[val][:0]

      Moving Average. This specifies the moving average window size (in
      minutes) to use. The moving average line will be shown on the chart in
      red. The peak period is shown (shaded) in the CSVPNG output. Typical
      values to use for moving average are 10 or 60 mins. Append ':0' to
      suppress the full line graph and show only the Moving Average graph.

      If /average is used without specifying a value, the average is plotted.

      /average cannot be used with overlay or multifile charts.

      If the /extract qualifier is also used, a new CSV file is generated with
      the moving average values.

      To specify the moving average value in seconds just add  's', for example
      /av=30s means 30 seconds.


/axis[=val]

      X-axis value. If this option is used, the values of the column specified will
      be used for the X-axis instead of the sample times. If /axis=row is used, the
      row numbers will be used on the X-axis.


/bar_chart

     Generate a bar_chart instead of the default line chart.


/border[=val]
-b[=val]

      Border. If /bo is used, the charts will have a gray border. The optional
      value specifies the chart background: 0 black, 1 white, 2 grey.

      Note: A new feature introduced in V1.0-70 generates 'sparkline' graphs
      when /bo=8 or /bo=9 is used. These are simple charts with no legend and
      are intended to show all charts from a T4 CSV in a compact form. Use
      with /wi=400 and /hei=25 for best results. /bo=8 shows the chart label in
      the html file, which allows searching the document for the text, while
      /bo=9 has the label embedded in the chart.


/caption="text":xy
-k="text":xy

      Caption. Use this option to specify a line of text to be written at
      the top of the chart. A maximum of 80 characters can be used.
      The font size and color can be controlled using this convention:
      Append :xy to the text string where 'x' is a code for Font size and
      y is a code for Font color. Available codes are:

      Font size: (T)iny, (S)mall, (L)arge [default], (M)ediumBold, (G)iant
      Font color: (R)ed [default], (B)lack, (G)reen, (Y)ellow, bl(U)e

      For example:

        /caption="This is a sample Caption using Large Red Font":LR
        /caption="This is a sample Caption using tiny blue Font":TU


/colors=<color sequence>

      Specify the colors of graph lines for overlay and multifile charts. The
      allowable colors are black,blue,brown,cyan,gold,green,khaki,maroon,magenta,
      orange,navy,purple,red,salmon,yellow,white,liteblue,grey.

      Example: '/colors=black,red,green,brown' specifies the colors of the first
      4 graphs on an overlay chart.

      Graph line colors may also be specified in the csvpng.cfg default file.

      The default colors used by csvpng are from the Excel color palatte and
      are RGB codes: 000080 FF00FF FF8040 008000 800080 800000 008080 0000FF 00CCFF
      CCFFFF CCFFCC FFFF99 99CCFF FF99CC CC99FF


/constant[=val]
-j[=val]

      Exclude charts with constant data less than 'val'. If no value is specified
      with /constant, a value of 1 is used. If this parameter is not used, all 
      charts with constant data are excluded. Use this qualifier if you want to 
      chart some parameters which are constant throughout the sampling period.

      This option replaces /j


/correlate=val[:th]
-c=val[:th]

      Correlate. The parameter corresponding to the value supplied is
      checked for correlation with all the parameters specified by /para.
      Optionally, the correlation threshold can be specified by adding
      :<threshold>. The default correlation threshold is .65.
      Example: /cor=3:.75 would check parameter 3 from the CSV file against
      the parameters specified by /par using a threshold of .75. A list of the
      parameters meeting the correlation criteria is written to CORREL.LIS.

      To check correlation of all parameters use /cor=0 or /cor=ALL. For example,
      to check for exact correlation of all parameters use /cor=ALL:1 /par=ALL.


/dataline=<num>

      Use this option to specify the first dataline. Use this for non-standard
      T4 CSV files which CSVPNG would be unable to determine where the datalines start.


/decimals=n
-D=n

      Specifies the precision to use when writing out floating point numbers
      in output CSV files. By default, numbers will be rounded to 2 decimal
      places. /decimals=-1 will leave fp numbers unaltered. /dec=0 will round
      to the nearest integer.

	     This also controls the precision of the minimum, average, maximum values
      displayed in CSVPNG output.


/directory=value
-C=value

     Specifies an output directory to use for the output files.
     If the directory does not exist, it is created.


/displaynum=n
-B=n

      Specifies the number of charts to display per row in the HTM file.
      By default, just 1 chart is shown per row. You also need to specify
      the /width option to use a reasonable number for the number of charts.


/dotcolors=<color sequence>

      Specify the colors of dots for overlay and multifile charts. The
      allowable colors are black,blue,brown,cyan,gold,green,khaki,maroon,
      magenta,orange,navy,purple,red,salmon,yellow,white,liteblue,grey.

      Example: /dotcolors=black,red,green,brown specifies the colors of the
      dots for the first 4 graphs on an overlay chart.

      White (transparent) line color and colored dots can be used to just show the
      data points. See also /colors.

      If /dotcolors is not used, the dotcolors are the same as the graph lines.


/dots[=size]
-d[=size]

      Dots. Prints a dot at each data point. The size of the dot can be
      set by using /do=<val>, The default is a small dot (val=1). The color of
      the dot can be specified by using the /dotcolors option.

      Example: /do=2  gives a round dot of 2 pixels radius
               /do=3  gives a slightly bigger dot of 3 pixels radius

/duplicates
-U

      Can only be used with /merge. Matching parameters in the input files
      are renamed to unique names by appending a number.


/extract[=file][:n]
-e[=file][:n]

      Extract. The parameters specified by /par, and matching the range
      specified by /tim, are written to the specified file. If no file
      specification is given, T4_OUT.CSV is used.

      If a value 'n' is specified, only every 'n'th record will be output.

      If /av=n is also used, the average of 'n' records will be written to the
      new CSV file. Note this average feature does not work with /x because no
      calculations are done when /x is used.

      See also /x


/fill
-f

      Fills in the area under each graph with a solid color.


/format=<1 or 2>
-F=<1 or 2>

      Writes the output CSV file in Format type 1 or 2. If /format is not used,
      type 1 is assumed.

      Ignored unless used with /extract, /x, or /merge


/headerline=<num>

       Specify which line is the column headings line. This may be necessary for
       non-standard CSV files. Normally CSVPNG relies on finding " Time" in the
       first token of a line to recognise the column headings line.


/height=height
-h=height

      Specifies the required chart height in pixels.


/help
-?

      Displays CSVPNG Help information.


/history[=<day>]
-G[=<day>]

      Shows the CSVPNG commands for the specified day. The default is today's
      file. Specify the history file as 'CSVPNG_ddmmyyyy.HIS' or just 'ddmmyyy'.
      If a wildcard character is used, a list of matching history files is
      displayed. If a number is also specified, the matching command from the
      history file will be executed. Additional options may be added to the
      requested command.

      Use /nohistory to prevent writing a command to the history file.

      Examples:

      /history shows today's csvpng history.
      /his=* or /his=csvpng_*.his shows a list of all available .HIS files.
      /his=11032006 or /his=csvpng_11032006.his shows that days history file.
      /his=csvpng_11032006.his 3 executes the 3rd command in the history file.
      /his=csvpng_11032006.his l will execute the last command from the history file.
      /his=2 /verbose would execute the 2nd command in todays' history file and add
      the additional option /verbose.


/horizontal[=n]
-H[=n]

      Specifies the number of horizontal grid lines to use. The default is 10.

/i
-i

      Same as /nologs.

      Suppress writing the .lis files and updating the history file.


/ignore
-I

      Ignores time periods with missing samples. By default CSVPNG charts the
      entire time period of the CSV file and areas with missing data are shown
      grayed-out. Using /ignore, only the data areas are graphed.


/j[=val]

      Same as /constant


/lines[=value]
-l[=value]

      Prints grid lines on the chart and shows a vertical scale. If a value
      (in minutes) is not specified, an appropriate default is used depending on
      the chart time range.

      Examples:

      /li=60 gives vertical lines every 60 minutes.


/merge[=file][/duplicates]
-m[=file] [-U]

      Combine parameters from two or more CSV files. The output CSV file will
      contain parameters from all the specified CSV files with the values for
      matching parameters added, unless /duplicates is specified. If /duplicates
      is used, the matching parameters are renamed to a unique name by appending
      '_n' where 'n' is 1, 2, 3, ...

      No charts are generated when /merge is used.

      If the input file shave identical parameters and are from different time 
      periods, /append will automatically be used. 

      See also /sample and /append

/nocharts
(no '-' equivalent)

      Suppresses the generation of the charts.


/nofloat
(no '-' equivalent)

      Treats fp numbers as integers. Use this qualifier if the data\n");
      has very large fp numbers.\n\n");


/noheader
(no '-' equivalent)

      No headers will be written to output CSV file. This is useful if you want to
      manually concatenate CSV files.


/nohistory
(no '-' equivalent)

      Don't write the command to the history file.


/nohorizontal
(no '-' equivalent)

      Suppresses horizontal grid lines when used with /lines.


/nologs
-i

      Suppresses writing the informational output files. The PARAM.LIS,
      T4_LOG.LIS and T4_PEAK files are not created and the command history
      file will not be created or updated.


/normalize
-n

      For Overlay charts, displays each graph normalized.


/novertical
(no '-' equivalent)

      Suppresses vertical grid lines when used with /lines.


/output=<htmfile>
-u=<htmfile>

      The output html file will be named <htmfile> and the .PNG files will be named,
      <filename>_<paramnum>.png.


/overlay[=val]
-o[=val]

      The selected parameters will be printed on one chart. A maximum of
      20 parameters may be used. If no value is used, the chart legend
      will be at the side. If val=1, the legend will be placed at the
      bottom of the chart. Do not use this option with multifile charts,
      they are automatically overlaid.


/parameters=params
-p=param

      CSV Parameters. If 0 or 'ALL', all parameters from the file(s) will
      be graphed. If /par is not specified at all, you will be shown all the
      parameter headings in the file and asked to choose. A list of
      parameter numbers may be entered, e.g. /par=3,4,5,6. A numeric parameter
      range may also be entered, e.g. /par=100-300.

      Parameters may also be entered as strings. e.g. if /par=disk is entered,
      all parameters with 'disk' in the name will be graphed. A number of
      strings may be entered, e.g. /par="cpu 00",disk.

      Wildcards are also supported, e.g. /par="*cpu 0? idle*" will match all
      idle parameters for cpu 01, 02, 03, etc. '*' matches multiple characters
      and '?' matches a single character'.

      If a string is preceded by '-' all parameters containing that string will
      be excluded. If preceded by '+' all parameters containing the string will
      be included. Use quotes with multi-word strings.

      The list of parameters used is written to the file PARAM.LIS. If
      /par=PARAM.LIS is used, the parameters from that file will be used.


/pdf[=filename][:d]
-Q[=filename][:d]

      Specifies that HTMLDOC be called to convert the HTM file to PDF.
      If no file name is specified, the name of the HTM file will be used.

      If ':d' is appended, the HTM and PNGs will be deleted.

      The HTMLDOC executable must be in the current path. On MSDOS use
      SET PATH=%PATH%;C:\<dir> to add the htmldoc directory to the path.
      On OpenVMS, setup a global symbol for htmldoc:
      htmldoc :== $<disk>:[<dir>]htmldoc_alpha.exe

      If the default htmldoc qualifiers are not satisfactory, you can override
      using an environmental variable, HTMLDOCENV.

      For example, on MSDOS:

           set HTMLDOCENV=--browserwidth 1000

      on OpenVMS:

           $ define HTMLDOCENV "--browserwidth 1000"


/percentile[=m:n][:0]
-P[=m:n][:0]

      Displays the 'm'th and 'n'th Percentile values for each parameter as well
      as the Median.

      The chart will show the percentile and median values unless ':0' is added.

      Examples: /percent=20:90, /percent=2.5:97.5


/quiet
-q

      Quiet mode. The charts are generated but very little output is shown on
      the screen.


/range=timerange
-trange

      Only graph the records in the specified time range. The range should be
      specified as /range=hh:mm,hh:mm or hh:mm:ss,hh:mm:ss or, if the records are
      not from the same day, use /range=dd-mmm-yyyy:hh:mm,dd-mmm-yyyy:hh:mm

      If the csv file spans a number of daya and the timerange is specified
      without the date portion, records matching the time from all days will be
      used.

      Replaces /timerange

/rename=<new pattern>
-R<new pattern>

      Use with /param=<wildcard expression> to rename column headers.
      The wildcard pattern for /par should contain * to match strings. The rename
      expression will substitute the 'nth' string if "&n" is used.

      Examples:

         csvpng t4_file.csv /par="[*]*" /rename="&2" will strip-off the leading
         [<string>] from each parameter.
         The keyword $NODE can be used to insert the host name, e.g.
         csvpng t4_file.csv /par="[*]*" /rename="$NODE&2"


/rules[=file]
-r[file]

      Specify a Rules file to use. Default is T4RULES.LIS. See below for
      details of rules file format.


/sample=<n>

     It specifies the sample interval to use for the output file.
     This can be different from the sample interval in the input files.
     If the input files have a smaller sample interval, the values are
     averaged and missing input rows will be written to the merged file
     with zero values.

     Example: csvpng <file1> <file2> ... /merge=<outputcsv> /merge=60 /pa=0

     This will use a 60 second interval in the output file, regardless of the
     intervals in the input files.


/scale=<min>:<max>
-Z<min>:<max>

      Specifies the minimum values to use for the Y-axis scale.
      Use 'min' or 'max' to use the actual parameter minimum or maximum values.
      Examples: /scale=0:100, /scale=10:max, /scale=min:10000, /scale=min:max

      Note: /scale will replace /zero which is similar but only allows the
      minimum y-axis to be set to zero.


/sd

      Displays the Standard Deviation of each parameter in the output listing.


/sort=<value>[:a or :d]
-S<value>[:a or :d]

      Sorts the parameters by Minimum, Average, Maximum, Median, p1, p2 values.
      p1 and p2 are the percentiles specified with the /percentile qualifier.
      example usage: /sort=average will sort the order of the parameter listing,
      and the order of the displayed charts, according to the average value.

      The default sort is 'descending', but an 'ascending' sort can be specified
      by appending ':a', for example: /sort=median:a


/sparklines
(no '-' equivalent)

      Generates simple small charts.


/stack
-s

      For Overlay or Multifile charts, stack each parameter.


/thickness=<value>

      Specifies the line thickness of graph lines. A value of 0 is the default
      and gives thin lines, Use 1 or higher for thicker lines.


/timerange=range
-t=range

      Replaced by /range


/top[=n]
-Tn

      Displays the top 'n' parameters, specified by /para, and sorts them in
      descending order by average size. To sort by minimum, maximum, median,
      or the percentile values specified by /perc, use one of 'min,max,med,p1,p2'
      with /sort.

      All other matching parameter values will be summed and classified as 'others'.

      If no value is specified with /top, a default of 6 is used.

	     If :a is added to the /sort option, the 'top' values displayed will be the
      'bottom' values.

      If /extract=<file> is used, the columns in the output CSV file will be
      sorted in 'top' order.


/trimzeros[=outfile]
-K[outfile]

      Excludes parameters which have all zero data from the output file.

      Examples:

       /param=all /trimzeros=trimmed.csv t4_file.csv

       writes all non-zero parameters to the output file.

       /param=10-50 /trimzeros=trimmed.csv t4_file.csv

     writes parameters #10 through #50 to the output file but excludes
     any non-zero parameters.


/verbose
-V
      Displays additional debug messages.


/version
--version
      Shows the version of CSVPNG.


/width=value
-wvalue

      Specifies the chart width in pixels.


/x[=file][:n]
-x[file][:n]

      Same as /extract but exits immediately without creating graphs.
      You cannot use /average=n with /x


/y[=file]
-y[file]

      Writes a list of specified parameter names to specified file.


/zero[=value]
-z[value]

      Makes the charts zero based. This is the default for overlay
      charts and multifile charts.

      If value is supplied, the Y-scale will be from 0 to the specified value.

      Note: /zero will be removed in a future release. Use /scale instead.


If no parameter or qualifier is used, you are prompted for a CSV file and
size of chart required. This is intended to be a 'novice' mode. To avail of
all the possible options, specify the commands on the command line.

A number of CSV files may be supplied on the command line. Wildcard file
specifications can be used, e.g. T4_ALP*.CSV. If more than one CSV file is
specified, the charts for all systems will be overlaid. The CSV files ideally
should be from the same time period and from the same cluster but CSVPNG
attempts to match parameters from all supplied files. The CSV files can
be specified in a file with file type .LIS. e.g. to graph parameters from 6
cluster nodes, create a file, CSV.LIS, with the names of the six T4 CSV files,
(one per line) and use CSV.LIS as the file parameter for CSVPNG.

Note that the parameters from the first CSV file specified are used for the
parameters to chart. e.g. if file1 has 100 parameters and file2 has 120
parameters only the 100 parameters from file1 are used.

Default values for some qualifiers can be specified in CSVPNG.CFG.
Allowable entries in CSVPNG.CFG:

average[=n]
correlate[=n]
height=<nnn>
width=<nnn>
lines
border[=n]
dots[=n]
zero
caption="default caption"
captionsize=<x>   ; x can be any of T, S, M, L, G
captioncolor=<y>  ; y can be any of R, G, B, Y, U
colors=<color sequesnce> ; example: =red,green,blue,black,...

lines starting with ';' in CSVPNG.CFG are ignored


Some example CSVPNG commands:

CSVPNG /pa=all /wi=600 /hei=300 /li /bo T4_MCSILO_24JUN2002_1155_2000.CSV
generates a chart 600 x 300 pixels, with grid lines and border. All parameters
in the file are graphed.

'/pa=0' or '/pa=all' will chart all parameters
'/pa=cache' will chart all parameters containing 'cache' (not case sensitive)
'/pa=[MON.DISK]' will chart all parameters containing '[MON.DISK]'
'/pa="cpu 00" ' will chart all parameters containing 'cpu 00'
'/pa=-[MON.DISK]' will chart all parameters except those containing '[MON.DISK]'
'/pa=5,6,7,8' will chart parameters 5, 6, 7, and 8
'/pa=+idle,+0,+cpu,-01' will select all parameters with the +, excluding those
 containing 01.


 History File:

 When CSVPNG is run it checks to see if a history file for that
 day exists. The format is CSVPNG_ddmmyyyy.HIS. If it does not exist, it is
 created and every CSVPNG command is added to the .HIS file prefixed with a
 number, starting at 1 and incrementing for every command. To rerun a command
 from the history file type CSVPNG n, where n is a number in the history file.
 Use CSVPNG l to execute the latest command.

 When /nologs is used, the command will not be added to the history file.

 See also /history.

 Calculated Parameters:

 CSVPNG can do some 'column arithmetic'. For example, columns can be added or
 subtracted to form a new parameter. To use this feature, create a .LIS file
 containing parameter names and use this format to calculate new parameters
 (either ',' or '|' may be used as a delimiter between fields):

 [CALC], <param 1>, <op1>, <param 2>, <op2>, <param 3>,...,<new parameter name>

 <param 'n'> should be a column name (or partial name with wildcard) from the 
 CSV file or may be a constant value. The special codes, $CPUS, $MEMORY, may 
 be used for the number of Cpus in the system and the physical memory.

 <op'n'> must be one of: + - / *

 <new parameter name> is the name of the new parameter to be created.

 The key words, $CPUS and $MEMORY, can be used in the [CALC] line to refer to
 the Number of Cpus in the system and the total physical memory.

 Up to 5 parameters and 4 operators may be used.

 For example:

 create a file CALC.LIS

 [CALC], 100, -, *Cpu 00 Idle*, Calculated Cpu 00 Busy
 [CALC], $MEMORY, -, *Free List Size, Memory Utilization

 and specify the .LIS with the /pa qualifier.

 A calculated parameter may be used in a later [CALC] line.

 Calculated parameters will be written to the new CSV file generated by /ex or
 /x

 Wildcard characters can also be used in [CALC] expressions. The character '*'
 is used to match any number of characters. pattern-match a portion of a
 parameter and store the result in a variable which can be used to name a
 new parameter. This can be used to sum a number of similar parameters
 grouped by one of the matching patterns. This is useful for EVA data where
 there may be hundreds of virtual disks with several parameters for each
 disk. The new parameters created are specified in the [CALC] expression,
 using &'n' as a placeholder for the matched pattern. 'n' is the number of
 the '*' matching pattern.

 example:
 [CALC], *vdisk(*\*)*Read*hit*, Read Hit Operations for &3

 The above expression will filter all parameters using the wildcard expression
 and the third matching string is used in the new parameters names.


 Renaming Parameters:

 Column headings in a CSV file can be renamed using a [RENAME] expression.

 Format of [RENAME] expression:

 [RENAME], <wild card expression>, <new parameter expression>

 The <wild card expression> uses '*' characters to match any number of
 characters. The <new parameter expression> uses the strings '&1' to '&5'
 to insert the first through fifth matched strings. '&1' means the text
 matched by the first '*'. '&2' uses the text matched by the second '*'.
 '?' can be used as a wildcard to match exactly one character but the
 matching character cannot be inserted into the new expression.

 example:
 [RENAME], "*VDisk*\*\*", "&4\&5"

 The above expression will rename all parameters matching the wild-card
 expression and rename each parameter using the 4th and 5th matched strings.
 If there are duplicate new parameter names, the column number is appended
 to the name to make it unique.

 The [RENAME] expression can be specified directly with the /pa qualifier, or
 a number of [RENAME] expressions can be specified in a file (which must have
 a filetype of .LIS) which is used with /pa.

 examples:

  CSVPNG T4_NODE_10DEC2003_1456_2000.CSV /pa="[RENAME],[*]*,&2"

  CSVPNG T4_NODE_10DEC2003_1456_2000.CSV /pa=tmp.lis

  where tmp.lis consists of lines such as these:

  [RENAME],[*]*Idle,&2Idle
  [RENAME],[MON.STAT]*,&1

T4 Rules:

 CSVPNG can be used to trigger rules based on T4 data. To use this feature,
 create a file using the following guidelines:

 Lines starting with ';' are ignored. Use '|' or ',' to separate each field.

 Each line should have this format:

 Type 1 Rule:

   Field 1  | Field 2 | Field 3 |    Field 4              | Field 5
 Param. name|operator |threshold|number of minutes to test|Caption for Chart

or

 Type 2 Rule:

   Field 1  | Field 2 | Field 3 |    Field 4              | Field 5
 Param. name|operator |threshold|either Avg, Min, Max     |Caption for Chart

Both rule types can also have an optional Field 6 specifying a file with
rule details.

Field 1 should contain a parameter name or partial name (case insensitive)

Field 2 must be one of the operators '<' '>' or '='.

Field 3 must be a number: the threshold value to test for.

Field 4 can be a number (Type 1 Rule) or 'Avg', 'Max', 'Min', case insensitive
(Type 2 rule).

For a Type 1 rule, the rule is fired if the threshold value is exceeded for the
specified number of minutes (period).
For a Type 2 rule, the Average, Maximum, or Minimum value of the parameter is
tested against the threshold value.

Field 5 is the caption you want displayed on the chart if the rule fires. You
can use the keywords $P1 and $P2 as placeholders for the Threshold and Period
of a type 1 rule.

If the Rules file has an optional 6th parameter, for example,|RULE01.HTM, this
will be added as a clickable link to a new browser window with the file contents.
The .htm file could be a text file with <pre> and </pre> tags

Examples:

Cpu 00 Idle|<|20|5|CPU 00 Idle %% was less than 20%% for more than 5 mins.
Split|>|3|A|Average Split Transfer Rate average was greater than 3
como| >| 1| a| On average more than 1 process in COMO state
Read Hit Latency|>|2500|5|Read from Cache > $P1 usecs|RULE02.HTM

Use the option /ru=<filename) to specify the Rules file to use. If no file is
specified with /ru, the default file used is T4RULES.LIS.

When a rule fires, the chart is drawn showing the threshold line and, for Type
1 rules, where the threshold was exceeded.

An additional HTML file is generated called T4RULES.HTM showing only the fired
charts. Also, the fired parameter numbers are written to a file T4RULESPAR.LIS.

Some examples of entries in T4RULES.LIS:

Cpu 00 Idle|<|20|5|CPU 00 Idle % was less than 20% for more than 5 minutes
split|>|3|A|Average Split Transfer Rate average was greater than 3
como| >| 1| a| On average more than 1 process in COMO state


HTMLDOC

A useful tool for use with CSVPNG is HTMLDOC which generates a PDF document
from the CSVPNG.HTM file. The PDF includes the charts so the .PNG files may
be deleted. HTMLDOC is an open source tool (GPL license). See
http://osx.freshmeat.net/projects/htmldoc/. HTMLDOC has been ported to
OpenVMS and is on the V7 Freeware CD:
http://h71000.www7.hp.com/freeware/freeware70/htmldoc/

To convert CSVPNG.HTM (and the associated .PNG charts) to PDF use this command:

htmldoc --webpage -f csvpng.pdf csvpng.htm

--------------------------------------------------------------------------------

The format of a T4 CSV file can be:

Format 1:
  The first four lines are header data:

  line1:   Header information containing T4 revision info and system information.
  line2:   Collection date  (optional line)
  line3:   Start time       (optional line)
  line4:   Parameter Headings (comma separated).

  The remaining lines are the comma separated values. The first column is the
sample time. Each line represents a sample, typically 60 seconds apart.

or
Format 2:
  line1:   Header information containing T4 revision info and system information.
  line2:   $$$ START COLUMN HEADERS $$$
  line3:   parameter headings (comma separated)
   .
   .
   .
  line'n': $$$ END COLUMN HEADERS $$$

Here is a simple example of a format 1 T4 CSV file:

EMPIRE, T4EXTR Version: T4 Version : V3.2-15 ... 01-Oct-2002,OpenVMS V7.2-2
 7-NOV-2002,  7-NOV-2002,  7-NOV-2002,
10:43, 10:43, 10:43
[MON]Sample Time,[MON.SYST]Direct I/O Rate,[MON.PAGE]Free List Size
 7-NOV-2002 10:44:00.16,81,2121
 7-NOV-2002 10:45:00.19,79,2122
 7-NOV-2002 10:46:00.22,19,2123
 7-NOV-2002 10:47:00.26,3,2124
 7-NOV-2002 10:48:00.29,0,2125
 7-NOV-2002 10:49:00.30,0,2126
 7-NOV-2002 10:50:00.32,20,2137

Feedback and comments are welcome!

pat.moran@hp.com
