PMNEWCONTEXT(3) 					     Library Functions Manual						   PMNEWCONTEXT(3)

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 concurrent contexts, each
       associated with a source of performance metrics, e.g. pmcd(1) on some host, or an archive log of performance metrics as created	by  pmlog-
       ger(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 common to all of the physical files of an archive log (type is PM_CONTEXT_ARCHIVE).

       For a type of PM_CONTEXT_HOST, in addition to identifying a host the name may also be used to encode additional optional information in the
       form  of  a  pmcd(1)  port  number,  a  pmproxy(1)  hostname and a proxy port number. For example the name "app23:14321,4321@firewall.exam-
       ple.com:11111" specifies a connection on port 14321 (or port 4321 if 14321 is unavailable) to pmcd(1) on the host app23 via port  11111	to
       pmproxy(1) on the host firewall.example.com.

       For  a type of PM_CONTEXT_ARCHIVE, name may also be the name of any of the physical files of an archive, e.g.  myarchive.meta (the metadata
       file) or myarchive.index (the temporal index) or myarchive.0 (the first data volume of the archive) or  myarchive.0.bz2	or  myarchive.0.bz
       (the first data volume compressed with bzip2(1)) or myarchive.0.gz or myarchive.0.Z or myarchive.0.z (the first data volume compressed with
       gzip(1)), myarchive.1 or myarchive.3.bz2 or myarchive.42.gz 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 context is used, the range of accessible performance metrics is constrained to those from the operating system,
       and optionally the ``proc'', ``sample'' and ``ib'' PMDAs.

       In the case where type is PM_CONTEXT_HOST, additional flags can be added to the type to indicate if the connection  to  pmcd(1)	should	be
       encrypted  (PM_CTXFLAG_SECURE),	deferred  (PM_CTXFLAG_SHALLOW)	and if the file descriptor used to communicate with pmcd(1), should not be
       shared across contexts (PM_CTXFLAG_EXCLUSIVE).  These final two context flags are now deprecated and ignored.

       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 pro-
       vided to independently manipulate both the instance profile (see pmAddProfile(3) and pmDelProfile(3)) and the collection time for  archives
       (see pmSetMode(3)).

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

       The new context remains the current PMAPI context for all subsequent calls across the PMAPI, until another call to pmNewContext(3) is made,
       or the context is explicitly 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_CONNECT_TIMEOUT in the envi-
       ronment	to  a  real number of seconds for the desired timeout.	This is most useful in cases where the remote host is at the end of a slow
       network, requiring longer latencies to establish the connection correctly.

ENVIRONMENT

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

       PMCD_PORT
	      TCP/IP port(s) for connecting to pmcd(1), historically was 4321 and more recently the officially registered port 44321; in the  cur-
	      rent  release,  pmcd listens on both these ports as a transitional arrangement.  If used, should be set to a comma-separated list of
	      numerical port numbers.

       PMDA_PATH
	      When searching for PMDAs to be loaded when type is PM_CONTEXT_LOCAL, the PMDA_PATH environment variable may  be  used  to  define  a
	      search path of directories to be used to locate the PMDA executables.  The default search path is $PCP_SHARE_DIR/lib:/usr/pcp/lib.

CAVEATS

       When  using a type of PM_CONTEXT_LOCAL, the operating system PMDA may export data structures directly from the kernel, which means that the
       pmNewContext caller should be an executable program compiled for the same object code format as the booted kernel.

       In addition, applications using a PM_CONTEXT_LOCAL context must be single-threaded because the various DSO PMDAs may  not  be  thread-safe.
       This restriction is enforced at the PMAPI(3), where routines may return the error code PM_ERR_THREAD if the library detects calls from more
       than one thread.

       Applications that use gethostbyname(3N) should exercise caution because the static fields in struct hostent may	not  be  preserved  across
       some PMAPI(3) calls.  In particular, pmNewContext(3) and pmReconnectContext(3) both may call gethostbyname(3N) internally.

SEE ALSO

       pmcd(1),  pmproxy(1),  pmAddProfile(3),	PMAPI(3),  pmDelProfile(3),  pmDestroyContext(3), pmDupContext(3), pmGetConfig(3), pmReconnectCon-
       text(3), pmSetMode(3), pmUseContext(3), pmWhichContext(3), pcp.conf(5) and pcp.env(5).

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.

Performance Co-Pilot							PCP							   PMNEWCONTEXT(3)