---
name: "pmiPutAtomValueHandle"
section: "3"
platform: "linux"
package: "pcp"
version: "7.2.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pmiPutAtomValueHandle"
---

# pmiPutAtomValueHandle(3)

add a value for a metric-instance pair via a handle

## NAME

**pmiPutAtomValueHandle**, **pmiPutValueHandle** - add a value for a metric-instance pair via a handle

## C SYNOPSIS

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

**int pmiPutAtomValueHandle(int** *handle***, pmAtomValue \****atom***);**\
 **int pmiPutValueHandle(int** *handle***, const char \****value***);**

**cc ... -lpcp\_import -lpcp**

## Perl SYNOPSIS

**use PCP::LogImport;**

**pmiPutValueHandle($***handle***, $***value***);**

## Python SYNOPSIS

**from pcp import pmi**

**log.pmiPutValueHandle(***handle***,** *value***)**

## DESCRIPTION

As part of the Performance Co-Pilot Log Import API (see [**LOGIMPORT**(3)](/LOGIMPORT/3.md)), **pmiPutAtomValueHandle** and **pmiPutValueHandle** add a single value to the current output record for a given metric and instance, using the *handle* defined by an earlier call to [**pmiGetHandle**(3)](/pmiGetHandle/3.md).

With **pmiPutAtomValueHandle** the *atom* passes the binary value directly using a union of types.

In the case of **pmiPutValueHandle** the *value* should be in a format consistent with the metric's type as defined in the call to [**pmiAddMetric**(3)](/pmiAddMetric/3.md).

No data will be written until [**pmiWrite**(3)](/pmiWrite/3.md) is called, so multiple calls to **pmiPutAtomValueHandle**, **pmiPutValueHandle** or [**pmiPutValue**(3)](/pmiPutValue/3.md) are typically used to accumulate data values for several metric-instance pairs before calling [**pmiWrite**(3)](/pmiWrite/3.md).

## DIAGNOSTICS

**pmiPutAtomValueHandle** and **pmiPutValueHandle** return zero on success else a negative value that can be turned into an error message by calling [**pmiErrStr**(3)](/pmiErrStr/3.md).

## SEE ALSO

[**LOGIMPORT**(3)](/LOGIMPORT/3.md), [**pmiErrStr**(3)](/pmiErrStr/3.md), [**pmiGetHandle**(3)](/pmiGetHandle/3.md), [**pmiPutResult**(3)](/pmiPutResult/3.md), [**pmiPutValue**(3)](/pmiPutValue/3.md), [**pmiPutText**(3)](/pmiPutText/3.md), [**pmiPutLabel**(3)](/pmiPutLabel/3.md) and [**pmiWrite**(3)](/pmiWrite/3.md).