'\"macro stdmacro
.\"
.\" Copyright (c) 2000-2004 Silicon Graphics, Inc.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMUSECONTEXT 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmUseContext\f1 \- change current PMAPI context
.SH "C SYNOPSIS"
.ft 3
#include <pcp/pmapi.h>
.sp
int pmUseContext(int \fIhandle\fP);
.sp
cc ... \-lpcp
.ft 1
.SH 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. \c
.BR pmcd (1)
on some host, or an archive of performance metrics as created by
.BR pmlogger (1).
.PP
Calling
.B pmUseContext
causes the
current PMAPI context to be set to
the context identified by
.IR handle .
The value of
.I handle
must be one returned from an earlier call to
.BR pmNewContext (3)
or
.BR pmDupContext (3).
.PP
Below the PMAPI, all contexts used by an application are saved in their most
recently modified state, so
.B 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.
.SH DIAGNOSTICS
.B PM_ERR_NOCONTEXT
.IP
.I handle
does not identify a valid PMAPI context
.SH SEE ALSO
.BR PMAPI (3),
.BR pmDestroyContext (3),
.BR pmDupContext (3),
.BR pmNewContext (3)
and
.BR pmWhichContext (3).