NAME

       pmParseTimeWindow, pmParseHighResTimeWindow - 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);
       int pmParseHighResTimeWindow(const char *swStart, const char *swEnd, const char *swAlign,
               const char *swOffset, const struct timespec *logStart,
               const struct timespec *logEnd, struct timespec *rsltStart,
               struct timespec *rsltEnd, struct timespec *rsltOffset, char **errMsg);

       cc ... -lpcp

DESCRIPTION

       pmParseTimeWindow   and   pmParseHighResTimeWindow   are   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 and pmParseHighResTimeWindow expect 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 archives as the source  of  performance  metrics,
       you  also  need to supply the time of the first archive entry as logStart, and the time of
       the last archive entry as logEnd.  See pmGetArchiveLabel(3) and pmGetArchiveEnd(3) for how
       to obtain values for these times.

       If  the  application  is  manipulating  multiple concurrent archives, then the caller must
       resolve how the default time window is to be defined (the union of the time  intervals  in
       all archives 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 PM_MAX_TIME_T.

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

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

DIAGNOSTICS

       If the conversion is successful, pmParseTimeWindow and pmParseHighResTimeWindow  return  1
       and  fill  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
       either pmParseTimeWindow or pmParseHighResTimeWindow returns 1.

       If  the conversion is successful, but the requested alignment could not be performed (e.g.
       the set of PCP archives is too short) the alignment is  ignored,  rsltStart,  rsltEnd  and
       rsltOffset  are filled in and pmParseTimeWindow and pmParseHighResTimeWindow return 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   and
       pmParseHighResTimeWindow return -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).