NAME

       pmUseContext - change current PMAPI context

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmUseContext(int handle);

       cc ... -lpcp

DESCRIPTION

       An application using the Performance Metrics Application Programming Interface (PMAPI) may
       manipulate several concurrent contexts, each  associated  with  a  source  of  performance
       metrics,  e.g.  pmcd(1)  on  some host, or an archive of performance metrics as created by
       pmlogger(1).

       Calling pmUseContext causes the current PMAPI context to be set to the context  identified
       by  handle.   The  value  of  handle  must  be  one  returned  from  an  earlier  call  to
       pmNewContext(3) or pmDupContext(3).

       Below the PMAPI, all contexts used by an application are  saved  in  their  most  recently
       modified  state, so pmUseContext restores the context to the state it was in the last time
       the context was used, not the state of the context when it was established.

DIAGNOSTICS

       PM_ERR_NOCONTEXT

              handle does not identify a valid PMAPI context

SEE ALSO

       PMAPI(3), pmDestroyContext(3), pmDupContext(3), pmNewContext(3) and pmWhichContext(3).