Product SiteDocumentation Site

3.8. PMAPI Procedural Interface

The following sections describe all of the PMAPI functions that provide access to the PCP infrastructure on behalf of a client application:
  • PMAPI Name Space services
  • PMAPI metric description services
  • PMAPI instance domain services
  • PMAPI context services
  • PMAPI timezone services
  • PMAPI metrics services
  • PMAPI fetchgroup services
  • PMAPI record-mode services
  • PMAPI archive-specific services
  • PMAPI time control services
  • PMAPI ancillary support services

3.8.1. PMAPI Name Space Services

The functions described in this section provide Performance Metrics Application Programming Interface (PMAPI) Name Space services.

3.8.1.1.  pmGetChildren Function

int pmGetChildren(const char*name, char***offspring)
Python:
[name1, name2...] = pmGetChildren(name)
Given a full pathname to a node in the current PMNS, as identified by name, return through offspring a list of the relative names of all the immediate descendents of name in the current PMNS. As a special case, if name is an empty string, (that is, "" but not NULL or (char *)0), the immediate descendents of the root node in the PMNS are returned.
For the python bindings a tuple containing the relative names of all the immediate descendents of name in the current PMNS is returned.
Normally, pmGetChildren returns the number of descendent names discovered, or a value less than zero for an error. The value zero indicates that the name is valid, and associated with a leaf node in the PMNS.
The resulting list of pointers (offspring) and the values (relative metric names) that the pointers reference are allocated by pmGetChildren with a single call to malloc, and it is the responsibility of the caller to issue a free(offspring) system call to release the space when it is no longer required. When the result of pmGetChildren is less than one, offspring is undefined (no space is allocated, and so calling free is counterproductive).
The python bindings return a tuple containing the relative names of all the immediate descendents of name, where name is a full pathname to a node in the current PMNS.

3.8.1.2.  pmGetChildrenStatus Function

int pmGetChildrenStatus(const char *name, char ***offspring, int **status)
Python:
([name1, name2...],[status1, status2...]) = pmGetChildrenStatus(name)
The pmGetChildrenStatus function is an extension of pmGetChildren that optionally returns status information about each of the descendent names.
Given a fully qualified pathname to a node in the current PMNS, as identified by name, pmGetChildrenStatus returns by means of offspring a list of the relative names of all of the immediate descendent nodes of name in the current PMNS. If name is the empty string (””), it returns the immediate descendents of the root node in the PMNS.
If status is not NULL, then pmGetChildrenStatus also returns the status of each child by means of status. This refers to either a leaf node (with value PMNS_LEAF_STATUS) or a non-leaf node (with value PMNS_NONLEAF_STATUS).
Normally, pmGetChildrenStatus returns the number of descendent names discovered, or else a value less than zero to indicate an error. The value zero indicates that name is a valid metric name, being associated with a leaf node in the PMNS.
The resulting list of pointers (offspring) and the values (relative metric names) that the pointers reference are allocated by pmGetChildrenStatus with a single call to malloc, and it is the responsibility of the caller to free(offspring) to release the space when it is no longer required. The same holds true for the status array.
The python bindings return a tuple containing the relative names and statuses of all the immediate descendents of name, where name is a full pathname to a node in the current PMNS.

3.8.1.3.  pmGetPMNSLocation Function

int pmGetPMNSLocation(void)
Python:
int loc = pmGetPMNSLocation()
If an application needs to know where the origin of a PMNS is, pmGetPMNSLocation returns whether it is an archive (PMNS_ARCHIVE), a local PMNS file (PMNS_LOCAL), or a remote PMCD (PMNS_REMOTE). This information may be useful in determining an appropriate error message depending on PMNS location.
The python bindings return whether a PMNS is an archive cpmapi.PMNS_ARCHIVE, a local PMNS file cpmapi.PMNS_LOCAL, or a remote PMCD cpmapi.PMNS_REMOTE. The constants are available by importing cpmapi.

3.8.1.4.  pmLoadNameSpace Function

int pmLoadNameSpace(const char *filename)
Python:
int status = pmLoadNameSpace(filename)
In the highly unusual situation that an application wants to force using a local Performance Metrics Name Space (PMNS), the application can load the PMNS using pmLoadNameSpace.
The filename argument designates the PMNS of interest. For applications that do not require a tailored Name Space, the special value PM_NS_DEFAULT may be used for filename, to force a default local PMNS to be established. Externally, a PMNS is stored in an ASCII format.
The python bindings load a local tailored Name Space from filename.

Note

Do not use this routine in monitor tools. The distributed PMNS services avoid the need for a local PMNS; so applications should not use pmLoadNameSpace. Without this call, the default PMNS is the one at the source of the performance metrics (PMCD or an archive).

3.8.1.5.  pmLookupName Function

int pmLookupName(int numpmid, char *namelist[], pmID pmidlist[])
Python:
c_uint pmid [] = pmLookupName("MetricName")
c_uint pmid [] = pmLookupName(("MetricName1", "MetricName2", ...))
Given a list in namelist containing numpmid full pathnames for performance metrics from the current PMNS, pmLookupName returns the list of associated PMIDs through the pmidlist parameter. Invalid metrics names are translated to the error PMID value of PM_ID_NULL.
The result from pmLookupName is the number of names translated in the absence of errors, or an error indication. Note that argument definition and the error protocol guarantee a one-to-one relationship between the elements of namelist and pmidlist; both lists contain exactly numpmid elements.
The python bindings return an array of associated PMIDs corresponding to a tuple of MetricNames. The returned pmid tuple is passed to pmLookupDescs and pmFetch.

3.8.1.6.  pmNameAll Function

int pmNameAll(pmID pmid, char ***nameset)
Python:
[name1, name2...] = pmNameAll(pmid)
Given a performance metric ID in pmid, pmNameAll determines all the corresponding metric names, if any, in the PMNS, and returns these through nameset.
The resulting list of pointers nameset and the values (relative names) that the pointers reference are allocated by pmNameAll with a single call to malloc. It is the caller's responsibility to call free and release the space when it is no longer required.
In the absence of errors, pmNameAll returns the number of names in nameset.
For many PMNS instances, there is a 1:1 mapping between a name and a PMID, and under these circumstances, pmNameID provides a simpler interface in the absence of duplicate names for a particular PMID.
The python bindings return a tuple of all metric names having this identical pmid.

3.8.1.7.  pmNameID Function

int pmNameID(pmID pmid, char **name)
Python:
"metric name" = pmNameID(pmid)
Given a performance metric ID in pmid, pmNameID determines the corresponding metric name, if any, in the current PMNS, and returns this through name.
In the absence of errors, pmNameID returns zero. The name argument is a null byte terminated string, allocated by pmNameID using malloc. It is the caller's responsibility to call free and release the space when it is no longer required.
The python bindings return a metric name corresponding to a pmid.

3.8.1.8.  pmTraversePMNS Function

int pmTraversePMNS(const char *name, void (*dometric)(const char *))
Python:
int status = pmTraversePMNS(name, traverse_callback)
The function pmTraversePMNS may be used to perform a depth-first traversal of the PMNS. The traversal starts at the node identified by name --if name is an empty string, the traversal starts at the root of the PMNS. Usually, name would be the pathname of a non-leaf node in the PMNS.
For each leaf node (actual performance metrics) found in the traversal, the user-supplied function dometric is called with the full pathname of that metric in the PMNS as the single argument; this argument is a null byte-terminated string, and is constructed from a buffer that is managed internally to pmTraversePMNS. Consequently, the value is valid only during the call to dometric--if the pathname needs to be retained, it should be copied using strdup before returning from dometric; see the strdup(3) man page.
The python bindings perform a depth first traversal of the PMNS by scanning namespace, depth first, and call a python function traverse_callback for each node.

3.8.1.9.  pmUnloadNameSpace Function

int pmUnloadNameSpace(void)
Python:
pmUnLoadNameSpace("NameSpace")
If a local PMNS was loaded with pmLoadNameSpace, calling pmUnloadNameSpace frees up the memory associated with the PMNS and force all subsequent Name Space functions to use the distributed PMNS. If pmUnloadNameSpace is called before calling pmLoadNameSpace, it has no effect.
As discussed in Section 3.8.1.4, “ pmLoadNameSpace Function” there are few if any situations where clients need to call this routine in modern versions of PCP.