NAME
pmdaFetch, pmdaSetFetchCallBack - fill a pmResult struc
ture 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 pro
cess 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 addi
tional callback should be registered using pmdaSetFetch
CallBack.
pmdaFetch will allocate and resize the resp result struc
ture, to store values for the numpmid metrics listed in
pmidlist.
For each instance listed in the profile (see pmdaPro
file(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[] = {
{ (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 dis
crepancy 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
rics.
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
call back
The fetch callback has returned
PM_ERR_INST. This indicates that an
instance of metric is listed in the pmdaIn
dom 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 spec
ified in the call to pmdaDSO(3) or pmdaDaemon(3).
SEE ALSO
pmcd(1), PMAPI(3), PMDA(3), pmdaDaemon(3), pmdaDSO(3),
pmdaInit(3) and pmFetch(3).
Man(1) output converted with
man2html