PMDAFETCH

Section: C Library Functions (3) Updated: SGI Local index Up

NAME

pmdaFetch, pmdaSetFetchCallBack - fill a pmResult structure with the requested metric values

C SYNOPSIS

#include <pcp/pmapi.h>
#include <pcp/impl.h>
#include <pcp/pmda.h>
int pmdaFetch(int numpmid, pmID *pmidlist, pmResult **resp, pmdaExt *pmda);
void pmdaSetFetchCallBack(pmdaInterface *dispatch, pmdaFetchCallBack callback);

cc ... -lpcp_pmda -lpcp

DESCRIPTION

pmdaFetch is a generic callback used by a PMDA(3) to process a fetch request from pmcd(1). The request from pmcd is initiated by a client calling pmFetch(3).

This is the only generic callback (see PMDA(3)) that is incomplete, requiring a callback of it's own. The additional callback should be registered using pmdaSetFetchCallBack.

pmdaFetch will allocate and resize the resp result structure, to store values for the numpmid metrics listed in pmidlist.

For each instance listed in the profile (see pmdaProfile(3)) of each metric listed in pmidlist, the registered callback is required to fill a pmAtomValue structure with the metric's value. This value is then copied into the pmResult structure.

For example, a PMDA has two metrics (A and B) and an instance domain (X) with two instances (X1 and X2). The instance domain and metrics description tables (see pmdaInit(3)) could be defined as:

static pmdaInstid _X[] = {
    { 0, "X1" }, { 1, "X2" }
};

static pmdaIndom indomtab[] = {
#define X_INDOM 0
    { 0, 2, _X },
};

static pmdaMetric metrictab[] = {
/* A */
    { (void *)0, 
      { PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT, 
        { 0,0,0,0,0,0} }, },
/* B */
    { (void *)0, 
      { PMDA_PMID(0,1), PM_TYPE_DOUBLE, X_INDOM, PM_SEM_INSTANT, 
        { 0,1,0,0,PM_TIME_SEC,0} }, },
};

A callback for pmdaFetch could be defined as:

static int
myFetchCallBack(pmdaMetric *mdesc, unsigned int inst, pmdaAtomValue *atom)
{
    __pmID_int    *idp = (__pmID_int *)&(mdesc->m_desc.pmid);

    switch (idp->item) {
        case 0:
            atom->l = /* assign some value for metric A */;
            break;
        case 1:
            switch (inst) {
                case 0:
                    atom->d = /* assign a value for metric B, instance X1 */;
                    break;
                case 1:
                    atom->d = /* assign a value for metric B, instance X2 */;
                    break;
                default:
                    return PM_ERR_INST;
            }
        default:
            return PM_ERR_PMID;
    }
    return 1;
}

The metric description mdesc and the instance identifier inst are used to determine which metric and instance is required. The callback should return 1 on success, 0 if the metric value is not currently available, or if the PMID or the instance are not supported then PM_ERR_PMID or PM_ERR_INST should be returned, respectively.

DIAGNOSTICS

The following error messages indicate that there is discrepancy between the namespace, pmdaMetric and pmdaIndom tables passed to pmdaInit(3), and the registered fetch callback:

pmdaFetch: Requested metric metric is not defined: A requested metric metric is not listed in the pmdaMetric table. The namespace for this PMDA(3) may contain additional metrics.
pmdaFetch: PMID pmid not handled by fetch callback: The fetch callback has returned PM_ERR_PMID. This indicates that a metric may be listed in the pmdaMetric table, but is not supported by the callback.
pmdaFetch: Instance inst of PMID pmid not handled by fetch callback: The fetch callback has returned PM_ERR_INST. This indicates that an instance of metric is listed in the pmdaIndom table, but is not supported by the callback.
pmdaFetch: Fetch callback error:: The fetch callback returned a result other than 0, PM_ERR_PMID or PM_ERR_INST.
pmdaFetch: Descriptor type (type) for metric pmid is bad: The data type type specified for the metric pmid in the pmdaMetric table is illegal.

pmdaFetch will return -errno if an error occurred while allocating the pmResult structure or copying the value from the pmAtomValue.

CAVEAT

The PMDA must be using PMDA_INTERFACE_2 or later, as specified in the call to pmdaDSO(3) or pmdaDaemon(3).

This document was created by man2html, using the manual pages.
Time: 21:52:36 GMT, April 16, 2011