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 semantics 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 values recorded for times in the
       proximity of the time origin.  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.

       If the mode is PM_MODE_BACK then, the situation is the same as for PM_MODE_FORW, except a pmFetch(3) will
       be serviced 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 qualifying 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 indicator, 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 origin (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
       performance 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 metrics; 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; /* or use pmGetArchiveEnd(&mtime) */
            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

Performance Co-Pilot                                   PCP                                          PMSETMODE(3)