pmdaSetFetchCallBack(3)

1PMDAFETCH(3)               Library Functions Manual               PMDAFETCH(3)
2
3
4

NAME

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

C SYNOPSIS

10       #include <pcp/pmapi.h>
11       #include <pcp/impl.h>
12       #include <pcp/pmda.h>
13
14       int pmdaFetch(int numpmid, pmID  *pmidlist,  pmResult  **resp,  pmdaExt
15       *pmda);
16
17       void  pmdaSetFetchCallBack(pmdaInterface  *dispatch,  pmdaFetchCallBack
18       callback);
19
20       cc ... -lpcp_pmda -lpcp
21

DESCRIPTION

23       pmdaFetch is a generic callback used by a PMDA(3) to  process  a  fetch
24       request  from  pmcd(1).  The request from pmcd is initiated by a client
25       calling pmFetch(3).
26
27       This is the only generic callback (see  PMDA(3))  that  is  incomplete,
28       requiring  a  callback  of it's own.  The additional callback should be
29       registered using pmdaSetFetchCallBack.
30
31       pmdaFetch will allocate and resize the resp result structure, to  store
32       values for the numpmid metrics listed in pmidlist.
33
34       For  each  instance  listed in the profile (see pmdaProfile(3)) of each
35       metric listed in pmidlist, the registered callback is required to  fill
36       a  pmAtomValue  structure  with the metric's value.  This value is then
37       copied into the pmResult structure.
38
39       For example, a PMDA has two metrics (A and B) and  an  instance  domain
40       (X)  with  two  instances (X1 and X2).  The instance domain and metrics
41       description tables (see pmdaInit(3)) could be defined as:
42
43            static pmdaInstid _X[] = {
44                { 0, "X1" }, { 1, "X2" }
45            };
46
47            static pmdaIndom indomtab[] = {
48            #define X_INDOM     0
49                { 0, 2, _X },
50            };
51
52            static pmdaMetric metrictab[] = {
53            /* A */
54                { (void *)0,
55                  { PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT,
56                    { 0,0,0,0,0,0} }, },
57            /* B */
58                { (void *)0,
59                  { PMDA_PMID(0,1), PM_TYPE_DOUBLE, X_INDOM, PM_SEM_INSTANT,
60                    { 0,1,0,0,PM_TIME_SEC,0} }, },
61            };
62
63       A callback for pmdaFetch could be defined as:
64
65            static int
66            myFetchCallBack(pmdaMetric *mdesc, unsigned int inst, pmdaAtomValue *atom)
67            {
68                __pmID_int    *idp = (__pmID_int *)&(mdesc->m_desc.pmid);
69
70                switch (idp->item) {
71                    case 0:
72                        atom->l = /* assign some value for metric A */;
73                        break;
74                    case 1:
75                        switch (inst) {
76                            case 0:
77                                atom->d = /* assign a value for metric B, instance X1 */;
78                                break;
79                            case 1:
80                                atom->d = /* assign a value for metric B, instance X2 */;
81                                break;
82                            default:
83                                return PM_ERR_INST;
84                        }
85                    default:
86                        return PM_ERR_PMID;
87                }
88                return 1;
89            }
90
91       The metric description mdesc and the instance identifier inst are  used
92       to  determine  which  metric  and  instance  is required.  The callback
93       should return 1 on success, 0 if the  metric  value  is  not  currently
94       available,  or  if  the  PMID  or  the  instance are not supported then
95       PM_ERR_PMID or PM_ERR_INST should be returned, respectively.
96

DIAGNOSTICS

98       The following error messages indicate that there is discrepancy between
99       the  namespace,  pmdaMetric and pmdaIndom tables passed to pmdaInit(3),
100       and the registered fetch callback:
101
102       pmdaFetch: Requested metric metric is not defined
103                      A requested metric metric is not listed in the  pmdaMet‐
104                      ric  table.   The namespace for this PMDA(3) may contain
105                      additional metrics.
106
107       pmdaFetch: PMID pmid not handled by fetch callback
108                      The fetch callback has returned PM_ERR_PMID.  This indi‐
109                      cates  that a metric may be listed in the pmdaMetric ta‐
110                      ble, but is not supported by the callback.
111
112       pmdaFetch: Instance inst of PMID pmid not handled by fetch callback
113                      The fetch callback has returned PM_ERR_INST.  This indi‐
114                      cates  that  an  instance  of  metric  is  listed in the
115                      pmdaIndom table, but is not supported by the callback.
116
117       pmdaFetch: Fetch callback error:
118                      The fetch callback  returned  a  result  other  than  0,
119                      PM_ERR_PMID or PM_ERR_INST.
120
121       pmdaFetch: Descriptor type (type) for metric pmid is bad
122                      The  data type type specified for the metric pmid in the
123                      pmdaMetric table is illegal.
124
125       pmdaFetch will return -errno if an error occurred while allocating  the
126       pmResult structure or copying the value from the pmAtomValue.
127

CAVEAT

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

NAME

C SYNOPSIS

DESCRIPTION

DIAGNOSTICS

CAVEAT

SEE ALSO