NAME

       pmParseTimeWindow  -  parse time window command line argu­
       ments


C SYNOPSIS

       #include <pcp/pmapi.h>

       int  pmParseTimeWindow(const  char  *swStart,  const  char
       *swEnd,  const  char *swAlign, const char *swOffset, const
       struct timeval *logStart, const  struct  timeval  *logEnd,
       struct timeval *rsltStart, struct timeval *rsltEnd, struct
       timeval *rsltOffset, char **errMsg)

       cc ... -lpcp


DESCRIPTION

       pmParseTimeWindow is designed to encapsulate the interpre­
       tation  of the -S, -T, -A and -O command line options used
       by Performance Co-Pilot (PCP)  applications  to  define  a
       time  window of interest.  The time window is defined by a
       start time and an end time that constrains the time inter­
       val  during  which  the  PCP application will retrieve and
       display performance metrics.  In the absence of the -O and
       -A  options  to  specify an initial sample time origin and
       time alignment  (see  below),  the  PCP  application  will
       retrieve the first sample at the start of the time window.

       The syntax and meaning of the various argument formats for
       these options is described in PCPIntro(1).


USAGE

       pmParseTimeWindow  expects  to be called with the argument
       of the -S option as swStart, the argument of the -T option
       as  swEnd,  the  argument of the -A option as swAlign, and
       the argument of the -O option as swOffset.  Any or all  of
       these  parameters  may be NULL to indicate that the corre­
       sponding command line option was not present.

       If the application is using  a  PCP  archive  log  as  the
       source of performance metrics, you also need to supply the
       time of the first archive log entry as logStart,  and  the
       time  of  the  last  archive  log  entry  as  logEnd.  See
       pmGetArchiveLabel(3) and  pmGetArchiveEnd(3)  for  how  to
       obtain values for these times.

       If  the  application  is  manipulating multiple concurrent
       archive logs, then the caller must resolve how the default
       time window is to be defined (the union of the time inter­
       vals in all archive logs is a likely interpretation).

       If the application is using a  live  feed  of  performance
       data,  logStart  should  be the current time (but could be

       should have its tv_sec component set to INT_MAX.

       The  rsltStart,  rsltEnd and rsltOffset structures must be
       allocated before calling pmParseTimeWindow.

       You also need to set the current PCP reporting  time  zone
       to correctly reflect the -z and -Z command line parameters
       before calling pmParseTimeWindow.   See  pmUseZone(3)  and
       friends for information on how this is done.


SEE ALSO

       PMAPI(3), pmGetArchiveEnd(3), pmGetArchiveLabel(3), pmNew­
       ContextZone(3),   pmNewZone(3),   pmParseInterval(3)   and
       pmUseZone(3).


DIAGNOSTICS

       If the conversion is successful, pmParseTimeWindow returns
       1 and fills in rsltStart, rsltEnd and rsltOffset with  the
       start,  end,  and offset times for the time window defined
       by the input parameters.   The  errMsg  parameter  is  not
       changed when pmParseTimeWindow returns 1.

       If  the conversion is successful, but the requested align­
       ment could not be performed (e.g. the PCP archive  log  is
       too  short)  the  alignment is ignored, rsltStart, rsltEnd
       and rsltOffset are filled in and pmParseTimeWindow returns
       0.   In  this case, errMsg will point to a warning message
       in an internal static buffer.  This buffer should  not  be
       freed.

       If  the  argument  strings  could  not be parsed, pmParse­
       TimeWindow returns -1.  In this case, errMsg will point to
       an error message in a static internal buffer.


Man(1) output converted with man2html