---
name: "pmsetmode"
section: "3"
platform: "linux"
package: "libpcp3-dev"
version: "4.3.2+really4.3.1-0.1"
release: "Debian 10 (Buster)"
platforms: ["linux"]
url: "https://new.carta.tech/pmSetMode"
---

# pmsetmode(3)

set collection time parameters for the current PMAPI context

Part of [pmSetMode(3)](/pmSetMode/3.md).

## 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)](/pmFetch/3.md), [**pmFetchArchive**(3)](/pmFetchArchive/3.md), [**pmLookupDesc**(3)](/pmLookupDesc/3.md), [**pmGetInDom**(3)](/pmGetInDom/3.md), [**pmLookupInDom**(3)](/pmLookupInDom/3.md) and [**pmNameInDom**(3)](/pmNameInDom/3.md).

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)](/pmFetch/3.md), 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)](/pmFetch/3.md), 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 set of archives 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)](/pmFetch/3.md) 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 set of archive logs is found, then [**pmFetch**(3)](/pmFetch/3.md) returns the special error indicator, **PM\_ERR\_EOL**.

For *mode*s other than **PM\_MODE\_LIVE**, after each successful  [**pmFetch**(3)](/pmFetch/3.md), the time origin is reset to the timestamp returned via the *pmResult* structure from [**pmFetch**(3)](/pmFetch/3.md).

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)](/pmFetch/3.md) fails because the time origin is outside the range defined by the records in a set of archive logs, i.e. returns **PM\_ERR\_EOL**.

By default *delta* is interpreted as milliseconds (but see the LARGE DELTA VALUES section below).

Using these *mode* options, an application can implement replay, playback, fast forward, reverse, etc. for performance metric values held in the set of archive logs by alternating calls to **pmSetMode** and [**pmFetch**(3)](/pmFetch/3.md).

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.

## EXAMPLES

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);
}
```

## LARGE DELTA VALUES

Because *delta* is an *int* and treated as milliseconds by default there is a limit on the maximum absolute value of *delta* that can be specified with this default interpretation, namely about 24 days if a signed *int* has 31 bits of precision. To accommodate longer values of *delta* the high-order bits of the *mode* parameter is also used to optionally set the units of time for the *delta* parameter. To specify the units of time use the **PM\_XTB\_SET** macro with one of the values **PM\_TIME\_NSEC**, **PM\_TIME\_MSEC**, **PM\_TIME\_SEC**, etc. to set the *mode* as follows:

PM\_MODE\_INTERP \| PM\_XTB\_SET(PM\_TIME\_XXXX)

The following code shows how this could be done if the desired *delta* is initially encoded in *interval* (a struct timeval).

```
struct timeval interval;
int mode;
mode = ...
if (abs(interval.tv_sec / (3600*24)) <= 24) {
    /* default encoding of milliseconds is fine */
    mode = PM_MODE_INTERP;
    delta = interval.tv_sec * 1000 + (interval.tv_usec + 500)/ 1000;
}
else {
    /* encode delta in units of seconds */
    mode = PM_MODE_INTERP | PM_XTB_SET(PM_TIME_SEC);
    delta = interval.tv_sec + (interval.tv_usec + 500000)/ 1000000;
}
```

For millisecond encoding of *delta*, using **PM\_XTB\_SET(PM\_TIME\_MSEC)** is functionally equivalent to not using **PM\_XTB\_SET** at all.

## SEE ALSO

[**PMAPI**(3)](/PMAPI/3.md), [**pmFetch**(3)](/pmFetch/3.md), [**pmFetchArchive**(3)](/pmFetchArchive/3.md), [**pmGetInDom**(3)](/pmGetInDom/3.md), [**pmLookupDesc**(3)](/pmLookupDesc/3.md), [**pmLookupInDom**(3)](/pmLookupInDom/3.md) and [**pmNameInDom**(3)](/pmNameInDom/3.md).

## DIAGNOSTICS

- **PM\_ERR\_MODE**

  The *mode* parameter is invalid