'\"macro stdmacro
.\"
.\" Copyright (c) 2000 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 PMLOADNAMESPACE 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmLoadNameSpace\f1 \- load a local PMNS for an application
.SH "C SYNOPSIS"
.ft 3
#include <pcp/pmapi.h>
.sp
int pmLoadNameSpace(const char *\fIfilename\fP);
.sp
cc ... \-lpcp
.ft 1
.SH DESCRIPTION
If the application wants to force using a local Performance Metrics
Name Space (PMNS) instead of a distributed PMNS then it
must load the PMNS using
.B pmLoadNameSpace
or
.BR pmLoadASCIINameSpace (3).
If the application is to use a distributed PMNS, then it should NOT
make a call to load the PMNS explicitly.
.PP
Most applications using a
Performance Metrics Application Programming Interface (PMAPI)
context
(of any type, so PM_CONTEXT_HOST or PM_CONTEXT_ARCHIVE or PM_CONTEXT_LOCAL)
should not need to call
.BR pmLoadNameSpace .
.PP
The
.I filename
argument designates the PMNS of interest.
For applications not requiring a tailored PMNS,
the special value
.B PM_NS_DEFAULT
may be
used for
.IR filename ,
to force the default local PMNS to be loaded.
.PP
The default local PMNS is found in the file
.I $PCP_VAR_DIR/pmns/root
unless the environment variable
.B PMNS_DEFAULT
is set, in which case the value is assumed to be the pathname
to the file containing the default local PMNS.
.PP
Externally a PMNS is stored in an ASCII format as
described in
.BR PMNS (5).
However, note that
.B pmLoadNameSpace
assumes
.I filename
does not contain any C-style comments, pre-processor directives or
macros; if this is not the case,
.BR pmLoadASCIINameSpace (3)
should be used instead.
.PP
As of Version 3.10.3 of PCP, by default,
multiple names in the PMNS
.B are
allowed to be
associated with a single Performance
Metrics Identifier (PMID) and this is unconditionally allowed
by
.BR pmLoadNameSpace .
.BR pmLoadASCIINameSpace (3)
provides an alternative interface with user-defined control
over the handling of duplicate names for the same PMID in the PMNS.
.PP
.B pmLoadNameSpace
returns zero on success.
.SH DIAGNOSTICS
Syntax and other errors in the parsing of the PMNS are reported
on
.I stderr
with a message of the form ``Error Parsing ASCII PMNS: ...''.
.PP
.B PM_ERR_DUPPMNS
.IP
It is an error to try and load more than one PMNS, or to call
either
.B pmLoadNameSpace
and/or
.BR pmLoadASCIINameSpace (3)
more than once.
.PP
.B PM_ERR_PMNS
.IP
Syntax error in the PMNS file.
.SH FILES
.IP \f2$PCP_VAR_DIR/pmns/root\f1 2.5i
the default local PMNS, when the environment variable
.B PMNS_DEFAULT
is unset
.SH "PCP ENVIRONMENT"
Environment variables with the prefix
.B PCP_
are used to parameterize the file and directory names
used by PCP.
On each installation, the file
.I /etc/pcp.conf
contains the local values for these variables.
The
.B $PCP_CONF
variable may be used to specify an alternative
configuration file,
as described in
.BR pcp.conf (5).
Values for these variables may be obtained programmatically
using the
.IR pmGetConfig (3)
function.
.SH SEE ALSO
.BR PMAPI (3),
.BR pmGetConfig (3),
.BR pmLoadASCIINameSpace (3),
.BR pmTrimNameSpace (3),
.BR pcp.conf (5),
.BR pcp.env (5)
and
.BR PMNS (5).