# pmnscomp

## NAME



           **pmnscomp** - compile an ASCII performance metrics namespace into
           binary format.
    


## SYNOPSIS



           **pmnscomp**[**-d**] [**-f**] [**-n** _namespace_] [**-v** _version_] _outfile_
    


## DESCRIPTION



           **pmnscomp** compiles a Performance Metrics Name Space (PMNS) in ASCII
           format into a more efficient binary representation.
           pmLoadNameSpace(3) is able to load this binary representation
           significantly faster than the equivalent ASCII representation.
    
           If _outfile_ already exists **pmnscomp** will exit without overwriting
           it.
    
           By convention, the name of the compiled namespace is that of the
           root file of the ASCII namespace, with **.bin** appended.  For
           example, the root of the default PMNS is a file named **root** and the
           compiled version of the entire namespace is **root.bin**.
    
           The options are;
    
           **-d** By default the PMNS to be compiled is expected to contain at
                most one name for each unique Performance Metric Identifier
                (PMID).  The **-d** option relaxes this restriction and allows
                the compilation of a PMNS in which multiple names may be
                associated with a single PMID.  Duplicate names are useful
                when a particular metric may be logically associated with
                more than one group of related metrics, or when it is desired
                to create abbreviated aliases to name a set of frequently
                used metrics.
    
           **-f** Force overwriting of an existing _outfile_ if it already
                exists.
    
           **-n** Normally **pmnscomp** operates on the default PMNS, however if
                the **-n** option is specified an alternative namespace is loaded
                from the file _namespace._
    
           **-v** By default, **pmnscomp** writes a version **2** compiled namespace.
                If _version_ is **1** then **pmnscomp** will write a version **1**
                namespace which is similar to version **2** , without the extra
                integrity afforded by checksums.  Note that PCP version 2.0
                or later can handle both versions **1** and **2** of the binary PMNS
                format.
    
           The default input 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 input PMNS.
    


## CAVEAT



           Once the writing of the new _outfile_ has begun, the signals SIGINT,
           SIGHUP and SIGTERM will be ignored to protect the integrity of the
           new file.
    


## DIAGNOSTICS



           Cannot open ``xyz'' - the filename for the root of the PMNS that
           was passed to pmLoadNameSpace(3) is bogus.
    
           Illegal PMID - either one of the three PMID components (see
           pmns(5)) is not an integer, or the value for one of the components
           is negative, or too large.
    
           Expected ... - specific syntax errors when a particular type of
           lexical symbol was expected and not found; the messages are
           intended to be self-explanatory.
    
           Internal botch - implementation problem for the parser ...
    
           Duplicate name ``abc'' in subtree for ``pqr.xyz'' - for each non-
           leaf node, the names of all immediate descendents must be unique.
    
           No name space entry for ``root'' - the special non-leaf node with
           a pathname of ``root'' defines the root of the PMNS, and must
           appear somewhere in the PMNS specification.
    
           Multiple name space entries for ``root'' - more than one ``root''
           node does not make sense!
    
           Disconnected subtree (``abc.xyz.def'') in name space - the
           pathname for this non-leaf node does not correspond to any
           pathname in the PMNS, hence this non-leaf node is ``orphaned'' in
           the PMNS.
    
           Cannot find definition for non-terminal node ``xyz'' in name space
           - a non-terminal node is named as part of its parent's
           specification, but is never defined.
    
           Duplicate metric id (xxx) in name space for metrics ``abc'' and
           ``xyz'' - each PMID must be unique across the PMNS.
    


## FILES



           _$PCP_VAR_DIR/pmns/*_
                  default PMNS specification files
           _$PCP_VAR_DIR/pmns/root.bin_
                  compiled version of the default PMNS, when the environment
                  variable **PMNS_DEFAULT** is unset
           _$PCP_VAR_DIR/pmns/stdpmid_
                  some standard macros for PMID generation
    


## PCP ENVIRONMENT



           Environment variables with the prefix **PCP_** are used to
           parameterize the file and directory names used by PCP.  On each
           installation, the file _/etc/pcp.conf_ contains the local values for
           these variables.  The **$PCP_CONF** variable may be used to specify an
           alternative configuration file, as described in pcp.conf(5).
    


* * *