NAME

       pmSetMode - set collection time parameters for the current
       PMAPI context


C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmSetMode(int mode, const struct  timeval  *when,  int
       delta)

       cc ... -lpcp


DESCRIPTION

       pmSetMode  is  used  to  define the collection time and/or
       mode for accessing performance metrics  and  meta-data  in
       the  current  Performance  Metrics Application Programming
       Interface (PMAPI) context.  This mode affects  the  seman­
       tics  of subsequent calls to the following PMAPI routines:
       pmFetch(3),      pmFetchArchive(3),       pmLookupDesc(3),
       pmGetInDom(3), pmLookupInDom(3) and pmNameInDom(3).

       If  mode  is PM_MODE_LIVE then all information is returned
       from the active pool of performance metrics as of the time
       that  the PMAPI call is made, and the other two parameters
       to pmSetMode are ignored.   PM_MODE_LIVE  is  the  default
       mode  when  a new PMAPI context of type PM_CONTEXT_HOST is
       created.

       If the mode is not PM_MODE_LIVE, then the  when  parameter
       defines  a  time  origin,  and  all requests for meta-data
       (metric descriptions and  instance  identifiers  from  the
       instance  domains)  will be processed to reflect the state
       of the meta-data as of the time origin, i.e.  we  use  the
       last  state  of  this  information at, or before, the time
       origin.

       If the  mode  is  PM_MODE_INTERP  then,  in  the  case  of
       pmFetch(3),  the underlying code will use an interpolation
       scheme to compute the values of the metrics from the  val­
       ues  recorded  for times in the proximity of the time ori­
       gin.  A mode of PM_MODE_INTERP may only be  used  with  an
       archive context.

       If   the  mode  is  PM_MODE_FORW  then,  in  the  case  of
       pmFetch(3), the collection of recorded metric values  will
       be  scanned  in a forwards direction in time, until values
       for at least one of the requested metrics is located after
       the  time origin, and then all requested metrics stored in
       the log or archive at that time will be returned with  the
       corresponding  timestamp.  A mode of PM_MODE_FORW may only
       be used with an archive context.

       same as for PM_MODE_FORW, except a pmFetch(3) will be ser­
       viced by scanning the collection of recorded metrics in  a
       backwards  direction  in  time for metrics before the time
       origin.  A mode of PM_MODE_BACK may only be used  with  an
       archive context.

       If the mode is PM_MODE_FORW or PM_MODE_BACK, and no quali­
       fying metrics can be found in the requested  direction  of
       searching  before  the  end or start of the archive log is
       found, then pmFetch(3) returns the special  error  indica­
       tor, PM_ERR_EOL.

       For  modes  other than PM_MODE_LIVE, after each successful
       pmFetch(3), the time origin  is  reset  to  the  timestamp
       returned via the pmResult structure from pmFetch(3).

       The pmSetMode parameter delta defines an additional number
       of time units that should be used to adjust the time  ori­
       gin  (forwards  or  backwards),  after the new time origin
       from the pmResult has  been  determined.   This  automatic
       adjustment of the time origin only occurs when the mode is
       PM_MODE_INTERP, and the adjustment is applied, even if the
       pmFetch(3)  fails  because  the time origin is outside the
       range defined by the  records  in  an  archive  log,  i.e.
       returns  PM_ERR_EOL.   The  high-order  bits  of  the mode
       parameter is also used to optionally set the units of time
       for  the  delta  field.  To  specify the units of time use
       PM_XTB_SET macro with  one  of  the  values  PM_TIME_NSEC,
       PM_TIME_MSEC, PM_TIME_SEC, etc.  as follows:

            PM_MODE_INTERP | PM_XTB_SET(PM_TIME_XXXX)

       If  no  units  are  specified  the default is to interpret
       delta as milliseconds.

       Using these mode options,  an  application  can  implement
       replay,  playback, fast forward, reverse, etc. for perfor­
       mance metric values held in the archive log by alternating
       calls to pmSetMode and pmFetch(3).

       As a special case, if when is NULL then the mode and delta
       arguments are used as described  above,  but  the  current
       time in the archive is not altered.

       For  example,  the  following code fragment may be used to
       dump just those values recorded in an archive  in  correct
       temporal  sequence, for a selected set of performance met­
       rics; this uses the default collection time mechanisms.

            pmNewContext(PM_CONTEXT_ARCHIVE, "myarchive");
            while (pmFetch(npmid, pmidlist, &result) != PM_ERR_EOL) {
                /*
                 * process real metric values as of result->timestamp

                . . .
                pmFreeResult(result);
            }

       Alternatively, to replay interpolated metrics from the log
       in reverse chronological order, at 10 second intervals (of
       recorded time), the following code fragment could be used.

            struct timeval mytime;

            mytime.tv_sec = 0x7fffffff;
            pmSetMode(PM_MODE_BACK, &mytime, 0);
            pmFetchArchive(&result);
            mytime = result->timestamp;
            pmFreeResult(result);
            pmSetMode(PM_MODE_INTERP | PM_XTB_SET(PM_TIME_SEC), &mytime, -10);

            while (pmFetch(numpmid, pmidlist, &result) != PM_ERR_EOL) {
                /*
                 * process interpolated metric values as of
                 * result->timestamp
                 */
                . . .
                pmFreeResult(result);
            }


SEE ALSO

       PMAPI(3),  pmFetch(3),  pmFetchArchive(3),  pmGetInDom(3),
       pmLookupDesc(3), pmLookupInDom(3) and pmNameInDom(3).


DIAGNOSTICS

       PM_ERR_MODE
              The mode parameter is invalid


Man(1) output converted with man2html