---
name: "pmReceiveStore"
section: "3"
platform: "linux"
package: "libpcp3-dev"
version: "3.3.3-squeeze3"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/pmReceiveStore"
---

# pmReceiveStore(3)

modify values of performance metrics

## NAME

**pmStore**, **pmRequestStore**, **pmReceiveStore** - modify values of performance metrics

## C SYNOPSIS

**#include \<pcp/pmapi.h\>**

```
int pmStore(const pmResult *result)
int pmRequestStore(int ctx, const pmResult *result)
int pmReceiveStore(int ctx)
```

**cc ... -lpcp**

## DESCRIPTION

In some special cases it may be helpful to modify the current values of performance metrics, e.g. to reset a counter to zero, or to modify a \`\`metric'' which is a control variable for some agent collecting performance metrics.

The routine **pmStore** is a lightweight inverse of [**pmFetch**(3)](/pmFetch/3.md).

The caller must build the *pmResult* data structure (of course, this could have been returned from an earlier [**pmFetch**(3)](/pmFetch/3.md) call) and then call **pmStore**.

It is an error to pass a request to **pmStore** in which the *numval* field within any of the **pmValueSet** structure has a value less than one.

The current Performance Metrics Application Programming Interface (PMAPI) context must be one with a host as the source of metrics, and the current value of the nominated metrics will be changed, i.e. **pmStore** cannot be used to make retrospective changes to information in either the archive logs, or in the recent past for real-time sources of metrics.

The return code from **pmStore** is zero for success.

**pmRequestStore** and **pmReceiveStore** are used by applications which must  communicate with the PMCD asynchronously. These functions take explict context handle *ctx* which must refer to a host context (i.e. created by passing **PM\_CONTEXT\_HOST** to **pmNewContext**). **pmRequestStore** sends request to store data in *result* in the metrics and returns without waiting for the response, **pmReceiveStore** reads confirmation from PMCD. It is the responsibility of the application to make sure the data are ready before calling **pmReceiveStore** to avoid blocking.

## SEE ALSO

[**PMAPI**(3)](/PMAPI/3.md), [**pmFetch**(3)](/pmFetch/3.md) and [**pmSetMode**(3)](/pmSetMode/3.md).

## DIAGNOSTICS

- **PM\_ERR\_GENERIC**

  At least one of the modifications was rejected. No other status is available from below the PMAPI (this is the lightweight part of the functionality!).  In cases where the outcome of **pmStore** for individual metrics is important, the caller should make one call to **pmStore** for each metric. On the other hand, a bulk modification can be performed in a single **pmStore** call for situations in which the outcome is not critical.

- **PM\_ERR\_NOTHOST**

  The current PMAPI context is an archive rather than a host, or it is a host that is not set to the current time, i.e. has been \`\`rewound'' to the recent past using [**pmSetMode**(3)](/pmSetMode/3.md).

- **PM\_ERR\_TOOSMALL**

  The number of metrics specified in *result* is less than one.

- **PM\_ERR\_VALUE**

  One or more of the *pmValueSet*s in *result* has a *numval* field with a value less than one.

- **PM\_ERR\_CTXBUSY**

  Context is currently in use by another asynchronous call.