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