NAME

       pmval - performance metrics value dumper


SYNOPSIS

       pmval  [-dgrz]  [-A  align]  [-a  archive]  [-h  host] [-i
       instances] [-n pmnsfile] [-O offset] [-p port] [-S  start­
       time]  [-s  samples] [-T endtime] [-t interval] [-w width]
       [-Z timezone] metricname


DESCRIPTION

       pmval prints current or archived values for the  nominated
       performance  metric.   The  metric of interest is named in
       the metricname argument, subject to instance qualification
       with the -i flag as described below.

       Unless directed to another host by the -h option, or to an
       archive by the -a option, pmval will contact  the  Perfor­
       mance Metrics Collector Daemon (PMCD) on the local host to
       obtain the required information.

       When processing an archive, pmval may relinquish  its  own
       timing  control, and operate as a ``slave'' of a pmtime(1)
       process that uses a GUI dialog to provide timing  control.
       In this case, either the -g option should be used to start
       pmval as the sole slave of a new pmtime(1)  instances,  or
       -p should be used to attach pmval to an existing pmtime(1)
       instance via the IPC channel identified by the port  argu­
       ment.

       The -S, -T, -O and -A options may be used to define a time
       window to restrict the samples retrieved, set  an  initial
       origin  within  the  time window, or specify a ``natural''
       alignment of the sample times; refer to PCPIntro(1) for  a
       complete description of these options.

       Options which control the source, timing and layout of the
       information reported by pmval are as follows:

       -a   Performance metric values are retrieved from the Per­
            formance  Co-Pilot  (PCP) archive log file identified
            by the base name archive.

       -d   When replaying from an archive, this option  requests
            that   the  prevailing  real-time  delay  be  applied
            between samples (see -t) to effect  a  pause,  rather
            than  the  default  behaviour  of  replaying  at full
            speed.

       -g   Start pmval as the slave of a new  pmtime(1)  process
            for  replay  of  archived  performance data using the
            pmtime(1)  graphical  user  interface.   Note:   This
            option is supported on Irix only.

            the nominated host machine.

       -i   instances is a list of one or more instance names for
            the   nominated   performance  metric  -  just  these
            instances will be retrieved and reported (the default
            is to report all instances).  The list must be a sin­
            gle argument, with elements of the list separated  by
            commas and/or white space.

       -n   Normally  pmval  operates  on the default Performance
            Metrics Name Space (PMNS), however if the  -n  option
            is  specified an alternative namespace is loaded from
            the file pmnsfile.

       -p   Attach pmval to an existing  pmtime(1)  time  control
            process  instance  via  the IPC channel identified by
            the port argument.  This option is normally only used
            by  other  tools,  e.g.   pmview(1), when they launch
            pmval with synchronized  time  control.   Note:  This
            option is suppored on Irix only.

       -r   Print  raw  values  for  cumulative  counter metrics.
            Normally cumulative counter metrics are converted  to
            rates.   For  example, disk transfers are reported as
            number of disk transfers per second during  the  pre­
            ceding  sample interval, rather than the raw value of
            number  of  disk  transfers  since  the  machine  was
            booted.   If  you specify this option, the raw metric
            values are printed.

       -s   The argument samples defines the number of samples to
            be  retrieved and reported.  If samples is 0 or -s is
            not specified, pmval will sample and report  continu­
            ously (in real time mode) or until the end of the PCP
            archive (in archive mode).

       -t   The default update interval may be set  to  something
            other  than the default 1 second.  The interval argu­
            ment follows the syntax described in PCPIntro(1), and
            in  the simplest form may be an unsigned integer (the
            implied units in this case are seconds).

       -w   Set the width of each column of output  to  be  width
            columns.  If not specified columns are wide enough to
            accommodate the  largest  value  of  the  type  being
            printed.

       -Z   By  default,  pmval reports the time of day according
            to the local timezone on the system  where  pmval  is
            run.   The -Z option changes the timezone to timezone
            in the format  of  the  environment  variable  TZ  as
            described in environ(5).

            at the host that is the  source  of  the  performance
            metrics,  as  identified  via  either  the  -h  or -a
            options.

       The following symbols may occasionally appear, in place of
       a  metric  value, in pmval output:  A question mark symbol
       (?) indicates that a value is no longer available for that
       metric  instance.  An exclamation mark (!)  indicates that
       a 64-bit counter wrapped during the sample.

       The output from pmval is directed to standard output.


FILES

       $PCP_VAR_DIR/pmns/*
                 default PMNS specification files


PCP ENVIRONMENT

       Environment variables with the prefix  PCP_  are  used  to
       parameterize the file and directory names used by PCP.  On
       each installation, the  file  /etc/pcp.conf  contains  the
       local  values for these variables.  The $PCP_CONF variable
       may be used to specify an alternative configuration  file,
       as described in pcp.conf(4).


SEE ALSO

       PCPIntro(1), pmcd(1), pmchart(1), pmdumplog(1), pminfo(1),
       pmlogger(1), pmtime(1), pcp.conf(4) and pcp.env(4).


DIAGNOSTICS

       All are generated on standard error and are intended to be
       self-explanatory.


CAVEATS

       pmval  attempts to display non-integer numeric values in a
       way that does not distort the inherent  precision  (rarely
       more  than  4 significant digits), and tries to maintain a
       tabular format in the output.  These goals  are  sometimes
       in conflict.

       The following table describes the formats used for differ­
       ent ranges of numeric values for any  metric  that  is  of
       type  PM_TYPE_FLOAT  or PM_TYPE_DOUBLE, or any metric that
       has the semantics of a counter (for  which  pmval  reports
       the rate converted value):

                   | Format   |     Value Range      |
                   +----------+----------------------+
                   |        ! | No values available  |
                   |9.999E-99 | < 0.1                |
                   |   0.0    | 0                    |
                   |   9.9999 | > 0 and <= 0.9999    |
                   |   9.999  | > 0.9999 and < 9.999 |
                   |  99.99   | > 9.999 and < 99.99  |
                   | 999.9    | > 99.99 and < 999.9  |
                   |9999.     | > 999.9 and < 9999   |
                   |9.999E+99 | > 9999               |
                   +----------+----------------------+


Man(1) output converted with man2html