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
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
(typeis PM_CONTEXT_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 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
deferred (PM_CTXFLAG_SHALLOW) and if the file descriptor, used to
communicate with pmcd(1), should not be shared across contexts
(PM_CTXFLAG_EXCLUSIVE).
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 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
environment 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
current 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 IRIX kernel.
Applications that use gethostbyname(3N) should exercise caution because
the static fields in struct hostent may not be preserved across some
PMAPI(4) calls. In particular, pmNewContext(3) and
pmReconnectContext(3) both may call gethostbyname(3N) internally.
SEE ALSO
pmAddProfile(3), PMAPI(3), pmDelProfile(3), pmDestroyContext(3),
pmDupContext(3), pmGetConfig(3), pmReconnectContext(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.