NAME

       pmParseTimeWindow - parse time window command line arguments

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 interpretation 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  interval 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 corresponding command line option was not present.

       If the application is using a set of  PCP  archive  logs  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  intervals  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 aligned on the next second for example),  while  logEnd  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.

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 alignment could not be performed (e.g.
       the set of PCP archive logs 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 a dynamically allocated buffer.  The  caller  is  responsible  for
       releasing the buffer by calling free(3).

       If  the argument strings could not be parsed, pmParseTimeWindow returns -1.  In this case,
       errMsg will point to an error message in a dynamically allocated buffer.   The  caller  is
       responsible for releasing the buffer by calling free(3).

SEE ALSO

       free(3),    PMAPI(3),   pmGetArchiveEnd(3),   pmGetArchiveLabel(3),   pmNewContextZone(3),
       pmNewZone(3), pmParseInterval(3) and pmUseZone(3).