# pmnsmerge

## NAME



           **pmnsmerge** - merge multiple versions of a Performance Co-Pilot PMNS
    


## SYNOPSIS



           **$PCP_BINADM_DIR/pmnsmerge**[**-adfxv**] [**-D** _debug_] _infile_ [...]
           _outfile_
    


## DESCRIPTION



           **pmnsmerge** merges multiple instances of a Performance Metrics Name
           Space (PMNS), as used by the components of the Performance Co-
           Pilot (PCP).
    
           Each _infile_ argument names a file that includes the root of a
           PMNS, of the form
    
                     root {
                         /* arbitrary stuff */
                     }
    
           The order in which the _infile_ files are processed is determined by
           the presence or absence of embedded control lines of the form
    
           #define _DATESTAMP _YYYYMMDD_
    
           Files without a control line are processed first and in the order
           they appear on the command line.  The other files are then
           processed in order of ascending _DATESTAMP.
    
           The **-a** option suppresses the argument re-ordering and processes
           all files in the order they appear on the command line.
    
           The merging proceeds by matching names in PMNS, only those **new**
           names in each PMNS are considered, and these are added after any
           existing metrics with the longest possible matching prefix in
           their names.  For example, merging these two input PMNS
    
                     root {                    root {
                                                   surprise  1:1:3
                         mine       1:1:1          mine      1:1:1
                         foo                       foo
                                                   yawn
                         yours      1:1:2
                     }                         }
                     foo {                     foo {
                         fumble     1:2:1
                                                   mumble    1:2:3
                         stumble    1:2:2          stumble   1:2:2
                     }                         }
                                               yawn {
                                                   sleepy    1:3:1
                                               }
    
           Produces the resulting PMNS in _out_.
    
                     root {
                         mine      1:1:1
                         foo
                         yours     1:1:2
                         surprise  1:1:3
                         yawn
                     }
                     foo {
                         fumble    1:2:1
                         stumble   1:2:2
                         mumble    1:2:3
                     }
                     yawn {
                         sleepy    1:3:1
                     }
    
           To avoid accidental over-writing of PMNS files, _outfile_ is
           expected to not exist when **pmnsmerge** starts.  The **-f** option allows
           an existing _outfile_ to be unlinked (if possible) and truncated
           before writing starts.
    
           Normally duplicate names for the same Performance Metric
           Identifier (PMID) in a PMNS are allowed.  The **-d** option is the
           default option and is included for backwards compatibility.  The
           **-x** option reverses the default and **pmnsmerge** will report an error
           and exit with a non-zero status if a duplicate name is found for a
           PMID in any of the _input_ PMNS files or in the merged _output_ PMNS.
    
           The **-v** option produces one line of diagnostic output as each
           _infile_ is processed.
    
           Once all of the merging has been completed, **pmnsmerge** will attempt
           to load the resultant namespace using pmLoadASCIINameSpace(3) - if
           this fails for any reason, _outfile_ will still be created, but
           **pmnsmerge** will report the problem and exit with non-zero status.
    
           Using **pmnsmerge** with a single _input_ argument allows that PMNS file
           to be checked.  In addition to syntactic checking, specifying **-x**
           will also enable a check for duplicate names for all PMIDs.
    


## OPTIONS



           The available command line options are:
    
           **-a** Process files in command line order.
    
           **-d** , **--dupok**
                Allow duplicate metric names per PMID.  This is the default.
    
           **-f** , **--force**
                Overwrite output file if it already exists.
    
           **-v** , **--verbose**
                Verbose input processing.
    
           **-x** , **--nodups**
                Do not allow duplicate metric names per PMID.
    
           **-?** , **--help**
                Display usage message and exit.
    


## CAVEATS



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


## 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).
    


## DEBUGGING OPTIONS



           The **-D** or **--debug** option enables the output of additional
           diagnostics on _stderr_ to help triage problems, although the
           information is sometimes cryptic and primarily intended to provide
           guidance for developers rather end-users.  _debug_ is a comma
           separated list of debugging options; use pmdbg(1) with the **-l**
           option to obtain a list of the available debugging options and
           their meaning.
    


* * *