#------------------------------------------------------------------------------
#
#  NSSDC/CDF						CDFmerge online help.
#
#  Version 1.0, 25-Jul-06, Raytheon
#
#  Modification history:
#
#   V1.0  25-Jul-06, M Liu 	Original version.
#
#------------------------------------------------------------------------------
#ifos mac win
CDFmerge merges the data contents from two or more CDFs. 
The parameters/qualifiers dialog box displayed when CDFmerge is `executed'
contains the following controls.

Edit fields for...

  CDF1:                The pathname of the CDFs to be merged.  At the end of
  CDF2:                this field a button labeled "Select" is present.  When
  ....                 selected, a standard input file dialog is displayed
                       from which the CDF may be selected.

  Output:              The pathname of the output CDF to which the merged data
                       will be written.  At the end of this field a button
                       labeled "Select" is present.  When selected, a standard
                       output file dialog is displayed in which the output
                       file pathname may be specified.  If an extension is not
                       specified in this pathname, `.cdf.' is appended
                       automatically.  
                       
  Prefix:              The prefix, along with a file count, is added to each 
                       attribute and variable name so any data entity in the 
                       merged file can be easily identified where it is from. 
                       If the prefix is not specified, only the file count is 
                       added. 

Buttons for...

  Enter              Causes CDFmerge to merge CDFs based on the
                     parameters/qualifiers specified.

  Help               Causes this online help to be displayed.

#ifos mac
  Quit               Causes CDFmerge to terminate.  (CDFs are not
                     merged.)  This button is only present the
                     first time the parameters/qualifiers dialog
                     box is displayed.

#endos
  Cancel             Causes the parameters/qualifiers dialog box to
                     be closed.  (CDFs are not merged.)
#ifos mac
                     This button is only present after the first time the
                     parameters/qualifiers dialog box is displayed.
#endos
#else
#ifos vms
Usage:    $ CDFMERGE [ [/NOPREFIX] | [/PREFIXES=<prefix1,><prefix2,>...<prefixN>] ]
                     [/[NO]CDAWEB] [/MASTER=[[MASTER_CDF] | [MSTERT_EXT]] ]
                     [/[NO]LOG] [/[NO]DATAONLY] [/ABOUT] [/AUGMENT_LABEL]
                     <<CDF-PATH1> <CDF-PATH2> .. <CDF-PATHN> <OUT-CDF>> | 
                     </FILE=FILE> |
                     <<CDF-PATH1> <CDF-PATH2> .. <CDF-PATHN>*>

#endos
#ifos unix
Usage:    % cdfmerge [ [-noprefix] | [-prefixes <prefix1,><prefix2,>...<prefixN>] ]
                     [-[no]cdaweb] [-master [[master_cdf] | [mstert_ext]] ]
                     [-[no]log] [-[no]dataonly] [-about] [-augment_label]
                     <<cdf-path1> <cdf-path2> .. <cdf-pathN> <out-cdf>> | 
                     <-file file> |
                     <<cdf-path1> <cdf-path2> .. <cdf-pathN>*>

#endos
#ifos dos
Usage:    > cdfmerge [ [-noprefix] | [-prefixes <prefix1,><prefix2,>...<prefixN>] ]
                     [-[no]cdaweb] [-master [[master_cdf] | [mstert_ext]] ]
                     [-[no]log] [-[no]dataonly] [-about] [-augment_label]
                     <<cdf-path1> <cdf-path2> .. <cdf-pathN> <out-cdf>> | 
                     <-file file> |
                     <<cdf-path1> <cdf-path2> .. <cdf-pathN>*>
#endos

Purpose:       CDFmerge merges two or more CDFs. The CDF files to be merged 
               can be entered in the command line. Alternatively, 
               a text file containing the path names for the source files and 
               the optional output file, one file name per line. The last CDF 
               name in the commnad list or text file is used for the output
               file if the "-master" (or /MASTER onVMS) is not specified.

Parameter(s):  <cdf-path1>
               <cdf-path2>
               .....
               <cdf-pathN>
                  The pathnames of the source CDFs to be merged (do not 
                  enter an extension). At least two (2) source files are required.

               <out-cdf>**
                  The pathname of the output CDF that has data from all
                  source CDFs. This is the last one in the parameter list. 
                  Any rVariables in the source files will be converted to
                  zVariables. The first source file dictates how the merged
                  file is to be created: its majority (row/column), encoding, 
                  format (single/multiple) and compression are to be used
                  for the output file. 

                  *Note: All CDFs are used for input if the "-master" (or
                         /MASTER on VMS) option, described later, is specified.

                  **Note: Don't provide this output CDF if the "-master" (or 
                          /MASTER on VMS) option, described later, is specified.
                          The output file name will be constructed from the
                          master file.

#ifos vms
               /FILE=<file>
#else
               -file "<file>"
#endos
                  Specifies the file that contains the names of the source CDFs
                  and the output, merged file. This is an alternative way of 
                  entering the (long) source and destination files at the
                  command line. Each text entry in this file represents a CDF 
                  file. Depending on whether the "-master" (or /MASTER on VMS)
                  option, described later, is specified, the entered files
                  can be used differently. If the "-master" option is not
                  specified, all, but the very last one, entries in the file 
                  are the names of the source CDFs for input. The last entry is 
                  designated as the output name for the merged CDF file. However,
                  if the "-master" option is specified, all entries are considered as
                  input CDF files and its output file name is constructed from the
                  master file. 
              
                  Variables in a source CDF when merging into the output file are,
                  by default, are renamed with a prefix of "file" and a number,
                  representing its sequence in the list. The default prefix
                  can be replaced by the user provided symbols, one symbol for
                  each source file. This symbol can be added as the second item
                  in each entry for the source CDFs. A blank is required to 
                  separate the source file name and the designated prefix. 
                  At least three entries, two for the input and one for the 
                  output, should be in the file.

#ifos vms
Qualifier(s):  /PREFIXES=(<prefix1,><prefix2,>...<prefixN>)
#else
Qualifier(s):  -prefixes "<prefix1,><prefix2,>...<prefixN>"
#endos
                  Specifies whether the user provided prefixes are used to be
                  added to the name of each variable in the merged file.
                  If this option is specified, prefixes, separated by a ",",
                  should match to the number of source CDFs, one prefix is
                  required for each corresponding source CDF file. The prefix
                  is limited to a length of 20 characters long. User defined
                  prefix followed by a underscore (_) is added at the beginning
                  of each variable name in the merged file.
                  If the option is not specified, variables from a source file
                  are prefixed with "file", followed by a number that 
                  represents the file number in the source CDF file list and
                  a underscore when they are merged into the output file. 
                  If this option is used, the following 
                  "noprefix" should not specified. If the "file" parameter is
                  used and it has prefixes, then this option is ignored.

#ifos vms
               /NOPREFIX
#else
               -noprefix
#endos
                  Specifies whether no prefix should be added to the name of
                  each variable in the merged file. If this option is 
                  specified, variable names form each source CDF are used 
                  for the merged file. It is assumed that there should be
                  no duplicate names in the source CDFs. If there is a
                  duplication, the merge process will abort. This option
                  can not be used with previous "prefixes" option.

#ifos vms
               /[NO]CDAWEB
#else
               -[no]cdaweb
#endos
                  Specifies to create a merged file that is ISTP/CDAweb CDF
                  compliant.  The ISTP/CDAweb guideline is available at
                  http://spdf.gsfc.nasa.gov/istp_guide/istp_guide.html.
                  The 'epoch' variable is a mandatory variable in the
                  ISTP/CDAweb guideline.  Thus, the duplication of this
                  variable is allowed in the input CDFs.  The duplication of
                  the variable named "RANGE_EPOCH" (in any upper/lower case
                  combination) is also allowed.
                  The default is nocdaweb.

#ifos vms
               /MASTER=(<MASTER_CDF>|<MASTER_TEXT>)
#else
               -master (<master_cdf>|<master_text>)
#endos
                  Specifies to use the value of the global attributes
                  from the master_cdf file or master_text,
                  instead of getting the value of the global attributes
                  from the input CDFs. The attributes are also used to
                  construct the merged file name. 

                  The given master file name is checked
                  first to see if it is a master CDF file (master_CDF).
                  If it is not a CDF file, then it is treated as a mater 
                  text file (master_text).  

                  If a global attributed named "File_naming_convention" exists
                  in the master_CDF or master_text, its value and pattern 
                  are used to construct the leading portion of the output file 
                  name. Also, a time stamp and data version are added to the 
                  output file name. The Epoch or Range_epoch data from the source
                  CDFs are checked to determine the time stamp and the attribute
                  Data_version is used for the data version. 

                  If the attribute "File_naming_convention" does not exist, then
                  the "Logical_file_id" attribute is used to construct the output 
                  file name.  The time stamp portion of the file name is updated 
                  from the source CDFs's Epoch/Range_epoch data.  If this 
                  attribute doesn't exist, the program will search for the 
                  existence of the following attributes, in their respective order,
                  and construct an output file name: "Source_name", "Descriptor",
                  "Data_type", along with the time stamp coming
                  from the input CDFs and "Data_version". If any of the attribute 
                  "Source_name", "Descriptor", or "Data_type" is missing, or its
                  entry doesn't exist, an error is given as the output file name
                  can not be determined.

                  Syntax for <master_text>:
                     Global attribute name on a separate line followed by a
                     colon (:).  The value(s) of the global attribute are
                     specified on separate line(s), one global attribute entry
                     per line, immediately after the global attribute name.
                     The following example illustrates how to specify/override
                     the value of the Logical_file_id, Logical_source, and
                     Instrument_type global attributes:

                        Line 1)  Logical_file_id:
                        Line 2)     tha_l1_fgm_20060816_v01
                        Line 3)
                        Line 4)  Logical_file_source:
                        Line 5)     tha_l1_fgm
                        Line 6)
                        Line 7)  Instrument_type:
                        Line 8)     FGE
                        Line 9)     FGM


                  If this option is used, the "-output" (or /OUTPUT on VMS) 
                  option is ignored. Also, with this master option, the 
                  "-dataonly" (or /DATAONLY on VMS) option, described later,
                  is automatically turned on.

#ifos vms
               /[NO]DATAONLY
#else
               -[no]dataonly
#endos
                  Specifies whether or not variable data of same variable name
                  from the source CDFs is merged into one. This option mainly 
                  deals with source CDFs that are a group of files that are 
                  similar in data contents, e.g., having a portion of different
                  time-sequence data, and have no sparse-records. If this 
                  option is selected, then the merged file will not have a 
                  separate variable for each variable in the source CDFs. 
                  Variables with same names from the source CDFs will have be
                  combined into one, keeping the same name without prefix in 
                  the merged file. The merged file will have the meta-data, 
                  i.e., global and variable attributes, from the that of the 
                  first source CDF.  The variable data of the same name are 
                  combined in the same sequence as the source CDFs are 
                  presented.  Arrange the source files in a proper sequence if
                  they are sequence-sensitive.  The default is nodataonly.

#ifos vms
               /[NO]LOG
#else
               -[no]log
#endos
                  Specifies whether or not messages are displayed indicating
                  the progress of CDF merging. The default is nolog.

#ifos vms
               /ABOUT
#else
               -about
#endos
                  Shows the library version that was used to create this tool
                  program.

#ifos vms         
               /AUGMENT_LABEL 
#else
               -augment_label
#endos               
                  Specifies whether variable attribute "AUGMENT_LABL" is to
                  be created and set to "TRUE" for all variables.
                     
#ifos vms
Example(s):    $ CDFMERGE/LOG TEST1 TEST2 OUTTEST
               $ CDFMERGE/PREFIXES=ID1,ID2,ID3 CDFF1 CDFF2 CDFF3 MERGEDFILE
               $ CDFMERGE/LOG /DATAONLY /FILE=FILELIST
               $ CDFMERGE/LOG /NOPREFIX /MASTER=MYMASTER.CDF INTEST1 INTEST2 INTEST3
               $ CDFMERGE/LOG /NOPREFIX /MASTER=AMASTER.TXT INCDF1 INCDF2 INCDF3
#endos
#ifos unix
Example(s):    % cdfmerge -log test1 test2 outtest
               % cdfmerge -prefixes ID1,ID2,ID3 cdff1 cdff2 cdff3 mergedFile
               % cdfmerge -log -dataonly -file filelist
               % cdfmerge -log -noprefix -master mymaster.cdf intest1 intest2 intest3
               % cdfmerge -log -noprefix -master amaster.txt incdf1 incdf2 incdf3
#endos
#ifos dos
Example(s):    > cdfmerge -log test1 test2 outtest
               > cdfmerge -prefixes ID1,ID2,ID3 cdff1 cdff2 cdff3 mergedFile 
               > cdfmerge -log -dataonly -file filelist
               > cdfmerge -log -noprefix -master mymaster.cdf intest1 intest2 intest3
               > cdfmerge -log -noprefix -master amaster.txt incdf1 incdf2 incdf3
#endos
#endos