NAME

       pmNewContext - establish a new PMAPI context


C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmNewContext(int type, const char *name)

       cc ... -lpcp


DESCRIPTION

       An  application  using the Performance Metrics Application
       Programming Interface (PMAPI) may manipulate several  con­
       current contexts, each associated with a source of perfor­
       mance metrics, e.g. pmcd(1) on some host,  or  an  archive
       log of performance metrics as created by pmlogger(1), or a
       standalone connection on the  local  host  that  does  not
       involve pmcd(1).

       pmNewContext  may be used to establish a new context.  The
       source of the metrics is identified by name,  and  may  be
       either  a host name (type is PM_CONTEXT_HOST), or the base
       name for the files of an  archive  log  (type  is  PM_CON­
       TEXT_ARCHIVE).   In  the latter case, name may also be the
       name of any component file of an archive,  e.g.  the  base
       name with the suffix .index, .meta, .0, etc.

       In  the  case  where  type  is  PM_CONTEXT_LOCAL,  name is
       ignored, and the context uses a standalone  connection  to
       the  PMDA methods used by pmcd(1).  When this type of con­
       text is used, the range of accessible performance  metrics
       is  constrained  to  those  from the operating system, and
       optionally the ``proc'' and ``sample'' PMDAs.

       The initial instance profile  is  set  up  to  select  all
       instances  in  all  instance  domains.   In the case of an
       archive, the initial collection time is also set to  zero,
       so  that an initial pmFetch(3) will result in the earliest
       set of metrics being returned from the archive.

       Once established, the association between a context and  a
       source  of  metrics  is fixed for the life of the context,
       however routines are provided to independently  manipulate
       both  the instance profile (see pmAddProfile(3) and pmDel­
       Profile(3)) and the  collection  time  for  archives  (see
       pmSetMode(3)).

       pmNewContext returns a handle that may be used with subse­
       quent calls to pmUseContext(3).

       The new context remains the current PMAPI context for  all
       subsequent  calls  across the PMAPI, until another call to

       changed with a call to pmDupContext(3) or pmUseContext(3),
       or destroyed using pmDestroyContext(3).

       When attempting to  connect  to  a  remote  pmcd(1)  on  a
       machine  that  is  booting, pmNewContext could potentially
       block for a long time until the  remote  machine  finishes
       its initialization.  pmNewContext will abort and return an
       error if the connection has  not  been  established  after
       some specified interval has elapsed.  The default interval
       is 5 seconds.  This may be modified by  setting  PMCD_CON­
       NECT_TIMEOUT  in  the environment to a real number of sec­
       onds for the desired timeout.   This  is  most  useful  in
       cases  where  the remote host is at the end of a slow net­
       work, requiring longer latencies to establish the  connec­
       tion correctly.


ENVIRONMENT

       PMCD_CONNECT_TIMEOUT
              Timeout  period (in seconds) for pmcd(1) connection
              attempts.

       PMCD_PORT
              TCP/IP port for connecting to pmcd(1), defaults  to
              4321.

       PMDA_LOCAL_PROC
              If set, then a context established with the type of
              PM_CONTEXT_LOCAL will have access to  the  ``proc''
              PMDA to retrieve performance metrics about individ­
              ual processes.

       PMDA_LOCAL_SAMPLE
              If set, then a context established with the type of
              PM_CONTEXT_LOCAL will have access to the ``sample''
              PMDA if  this  optional  PMDA  has  been  installed
              locally.

       PMDA_PATH
              When  searching for PMDAs to be loaded when type is
              PM_CONTEXT_LOCAL, the PMDA_PATH  environment  vari­
              able  may be used to define a search path of direc­
              tories to be used to locate the  PMDA  executables.
              The        default       search       path       is
              /var/pcp/lib:/usr/pcp/lib.


CAVEATS

       When using a type of PM_CONTEXT_LOCAL, the operating  sys­
       tem PMDA may export data structures directly from the ker­
       nel, which means that the pmNewContext caller should be an
       executable  program compiled for the same object code for­
       mat as the booted IRIX kernel.

       Applications that use  gethostbyname(3N)  should  exercise

       not be preserved across some PMAPI(4) calls.  In  particu­
       lar,  pmNewContext(3)  and  pmReconnectContext(3) both may
       call gethostbyname(3N) internally.


SEE ALSO

       pmAddProfile(3), PMAPI(3), pmDelProfile(3),  pmDestroyCon­
       text(3),  pmDupContext(3), pmGetConfig(3), pmReconnectCon­
       text(3), pmSetMode(3), pmUseContext(3), pmWhichContext(3),
       pcp.conf(4) and pcp.env(4).


DIAGNOSTICS

       PM_ERR_PERMISSION

              No permission to perform requested operation

       PM_ERR_CONNLIMIT

              PMCD connection limit for this host exceeded

       PM_ERR_NOCONTEXT

              Requested  context  type  was not PM_CONTEXT_LOCAL,
              PM_CONTEXT_HOST or PM_CONTEXT_ARCHIVE.


Man(1) output converted with man2html