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  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 PM_MAX_TIME_T.

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

       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 archive logs 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).