# pmparsetimewindow

## 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 timespec ***_logStart_**,**
                                 **const struct timespec ***_logEnd_**,**
                                 **struct timespec ***_rsltStart_**,**
                                 **struct timespec ***_rsltEnd_**,**
                                 **struct timespec ***_rsltOffset_**, char ****_errMsg_**);**
    
           **cc ... -lpcp**
    


## DESCRIPTION



           **pmParseTimeWindow** 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** expect to be called with the argument of the **-S**
           option as **swStart** , the argument of the **-T** option as **swEnd** , the ar‐
           gument of the **-A** option as **swAlign** , and the argument of the **-O** op‐
           tion 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_ com‐
           ponent set to **PM_MAX_TIME_T**.
    
           The **rsltStart** , **rsltEnd** and **rsltOffset** structures must be allocated
           before calling **pmParseTimeWindow**.
    
           You  also  need to set the current PCP reporting time zone to cor‐
           rectly reflect the **-z** and **-Z** command line parameters before  call‐
           ing  these routines.  See pmUseZone(3) and friends for information
           on how this is done.
    


## DIAGNOSTICS



           If the conversion is successful, **pmParseTimeWindow** 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**
           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** 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** re‐
           turn -1.  In this case, **errMsg** will point to an error message in a
           dynamically  allocated  buffer.  The caller is responsible for re‐
           leasing the buffer by calling free(3).
    


## COMPATIBILITY



           Prior to PCP 7.0 and _libpcp.so.4_ the _logStart_ , _logEnd_ ,  _rsltStart_ ,
           _rsltEnd_  and _rsltOffset_ arguments were struct timeval.  To support
           PMAPI transition, the old interface and semantics can be  used  if
           applications  are  linked  with  _libpcp.so.3_  or  recompiled  with
           **-DPMAPI_VERSION=2**.
    
           For a time in PCP 6.x there was a routine with the same  semantics
           as  the  current **pmParseTimeWindow** called **pmParseHighResTimeWindow**
           although this is now deprecated and compile-time support  for  **pm‐**
           **ParseHighResTimeWindow** will be removed in a future release.
    


* * *