# pmloadasciinamespace

## NAME



           **pmLoadASCIINameSpace** - establish a local PMNS for an application
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
    
           **int pmLoadASCIINameSpace(const char ***_filename_**, int** _dupok_**);**
    
           **cc ... -lpcp**
    


## DESCRIPTION



           If  the  application wants to force using a local Performance Met‐
           rics Name Space (PMNS) instead of a distributed PMNS then it  must
           load  the  PMNS  using **pmLoadASCIINameSpace** or pmLoadNameSpace(3).
           If the application wants to use a distributed PMNS, then it should
           NOT make a call to load the PMNS explicitly.
    
           Most applications using a Performance Metrics Application Program‐
           ming Interface (PMAPI) context (of any type, so PM_CONTEXT_HOST or
           PM_CONTEXT_ARCHIVE or PM_CONTEXT_LOCAL) should not  need  to  call
           **pmLoadASCIINameSpace**.
    
           The _filename_ argument designates the PMNS of interest.  For appli‐
           cations not requiring a tailored PMNS, the special value **PM_NS_DE‐**
           **FAULT** may be used for _filename_ , to force the default local PMNS to
           be loaded.
    
           The default local PMNS is found in the file _$PCP_VAR_DIR/pmns/root_
           unless the environment variable **PMNS_DEFAULT** is set, in which case
           the value is assumed to be the pathname to the file containing the
           default local PMNS.
    
           **pmLoadASCIINameSpace** is  a variant of pmLoadNameSpace(3) in which
           the _dupok_ argument may be used to control the handling of multiple
           names in the PMNS that may be associated with a single Performance
           Metric Identifier (PMID).  A value of 0 disallows duplicates,  any
           other value allows duplicates and the latter is the default behav‐
           iour of pmLoadNameSpace(3) as of Version 3.10.3 of PCP.
    
           The other difference is that when **pmLoadASCIINameSpace** is used and
           _filename_  is  **not** PM_NS_DEFAULT, the PMNS file will always be pre‐
           processed with pmcpp(1) as described in PMNS(5).   This  allows  a
           PMNS  file that contains C-style comments, preprocessor directives
           or macros to be processed correctly before the PMNS is parsed.
    
           **pmLoadASCIINameSpace** returns zero on success.
    


## DIAGNOSTICS



           Syntax and other errors in the parsing of the PMNS are reported on
           _stderr_ with a message of the  form  ``Error  Parsing  ASCII  PMNS:
           ...''.
    
           **PM_ERR_DUPPMNS**
    
                  It  is  an  error  to try to load more than one PMNS, or to
                  call either **pmLoadASCIINameSpace** and/or  pmLoadNameSpace(3)
                  more than once.
    
           **PM_ERR_PMNS**
    
                  Syntax error in an ASCII format PMNS.
    


## FILES



           _$PCP_VAR_DIR/pmns/root_   the default local PMNS, when the environ‐
                                    ment variable **PMNS_DEFAULT** is unset
    


## PCP ENVIRONMENT



           Environment variables with the prefix **PCP_** are used to parameter‐
           ize the file and directory names used by PCP.  On each installa‐
           tion, the file _/etc/pcp.conf_ contains the local values for these
           variables.  The **$PCP_CONF** variable may be used to specify an al‐
           ternative configuration file, as described in pcp.conf(5).  Values
           for these variables may be obtained programmatically using the
           pmGetConfig(3) function.
    


* * *