HEADERMOD

modifies/creates a Midas file header

<FILE>                Name of file
<key 1..N>            Key=Value pairs to change

Used to modify those MIDAS file header sector words that describe the logical
contents of the file.  Only the parameters specified in the command line will
be changed.  No default header values will be assigned.

The header is not modified if the write protect field is set to YES. In this
case, the file must be UNPROTECTed first using the UNPROTECT function in FILE.

The STATUS command can be used to view or retrieve values in the header.

This command is invoked with positionally independent (PI) parameters using
the TAG=VALUE syntax.  Java reflection is used to find any matching "set" method
in the DataFile class. One-character abbreviations are NOT allowed, due to
resulting ambiguities and confusion, with the one special syntax exception
being C(#) for COMPONENT(#).  Common tags in the DataFile class are:

 TAG        Longname     Description
  ------------------------------------------------------------------------------
  TYPE      TYPE         File Type
  FORM      FORMAT       Format
  XU        XUNITS       X or Abscissa units
                          (For a complete list see nxm.sys.inc.Units)
  XS        XSTART       X or Abscissa start
  XD        XDELTA       X or Abscissa delta
  FS        FRAMESIZE    Frame size (type 2000)
  YU        YUNITS       Y or Secondary units
                          (For a complete list see nxm.sys.inc.Units)
  YS        YSTART       Y or Secondary start
  YD        YDELTA       Y or Secondary delta
  COMM      COMMENT      Set the COMMENT keyword
  TC        TIMECODE     Timecode (TIMECODE Header field only)
  SIZE      SIZE         Size in logical elements
  DS                     Not currently supported
  DATASTART DATASTART    Data start in bytes (usually 512, unless detached)
  DR        DATAREP      Data representation
  HR        HEADREP      Header representation
  ......................................
  T                     *NOT SUPPORTED* (use TYPE=)
  F                     *NOT SUPPORTED* (use FORM=)
  REP                   *NOT SUPPORTED* (use DR= or HR=)

  HEADERMOD can be used to create a type 3000 or 5000 file from a macro or
  the command line, by applying the /CREATE switch.

  For Type 3000 and 6000, the following must be defined:
    RL          Record length in bytes
    NSR         Number of subrecords
    SR(n)       Subrecord specs    = (NAME,FORMAT,OFFSET)
                  - NAME is an ASCII string up to 4 characters.
                  - FORMAT is standard 2-char digraph
                  - OFFSET is in bytes from the beginning of the record
                    (the first field often starts at 0, for example)
    SR          Short-hand record set using SR=(NAME/FORMAT,...) syntax

  For Type 5000, the following must be defined:
    RL          Record length in bytes
    NC          Number of components
    C(n)        Component specs    = (NAME,FORMAT,TYPE,UNITS)
                  - NAME is an ASCII string up to 4 characters.
                  - FORMAT is standard 2-char digraph
                  - TYPE is the numeric component-type code or name
                    See nxm.sys.inc.Units.java for a complete list.
                  - UNITS is the numeric units code or name
                    See nxm.sys.inc.Units.java for a complete list.
    COMPONENTS  Short-hand component set using = (NAME/FORMAT/TYPE/UNITS,...)
    RF          Reference Frame can be "ECR", "ECI", "TOP", or "TOPOCENT".
                Anything else is considered to be a file describing a
                custom reference frame.
    FR          Frame of Reference (alias for RF= for X-Midas compatibility)
    QUADWORD(i) Quadword Value:
                  QUADWORD(0)  - Reference frame      (set via RF=)
                  QUADWORD(1)  - Altitude
                  QUADWORD(2)  - Latitude
                  QUADWORD(3)  - Longitude
                  QUADWORD(4)  - Azimuth
                  QUADWORD(5)  - Elevation
                  QUADWORD(6)  - Roll
                  QUADWORD(7)  - unused
                  QUADWORD(8)  - unused
                  QUADWORD(9)  - Epoch Year           (set using TIMEX command)
                  QUADWORD(10) - Epoch Sec of Year    (set using TIMEX command)
                  QUADWORD(11) - Epoch GHA (radians)  (set using TIMEX command)
    QW(i)       One-based version of QUADWORD(..) for X-Midas compatibility
                where QW(i)=QUADWORD(i-1).

  The /DETACH switch will flag the header as being detached. This header can
  then be attached to a foreign file to make it a Midas viewable file (if
  structure is correct - see ATTACH).

  Using the /DETACH switch has the same effect as using the filename qualifier
  DETACHED=1. See examples below. Note the results of using different values
  for the DETACHED filename qualifier:

    DETACHED=0 => header is not detached
    DETACHED=1 => header is detached and *.det file will be in the same
                  directory as *.tmp file
    DETACHED=<N> where N is between 1 and 127 =>*.det file found in AUX=<N>
                 (X-Midas only)
    DETACHED=<ext> where <ext> is a file name extension =>*.<ext> file found in
                   same directory as *.tmp file (NeXtMidas only)

    NOTE: DETACHED=1 and DETACHED=TRUE are not the same as the second one
          creates a *.true file rather than *.tmp.


Examples:
  1. To change the frame size of a 2000 file to 2048:
       nM> HEADERMOD MYFILE FS=2K

  2. To change the type to 5009 and the name and units code of the 2nd component
       nM> HEADERMOD MYFILE TYPE=5009 C(2)=(TDOA,,,1)

  3. To create a non-homogeneous Type 3000 file with a 16-byte ASCII field
     "LABL" followed by double precision fields "ABSC" and "ORD":

       nM> HEADERMOD/CREATE file SR=(LABL/2A,ABSC/SD,ORD/SD)

     Here the offsets are computed automatically but they may also be
     user-specified.  If formats are not specified they are defaulted to SF.
     To create the same file "the hard way":

       nM> HEADERMOD/CREATE file TYPE=3000 FORM=NH NSR=3 RL=32 &
                            SR(1)=(LABL,2A,0) &
                            SR(2)=(ABSC,SD,16) &
                            SR(3)=(ORD,SD,24)

  4. To create a file as described in example 3, but with a detached header:

       nM> HEADERMOD/CREATE/DETACH file SR=(LABL/2A,ABSC/SD,ORD/SD)

       Note that this has the same effect as using the filename qualifier
       DETACHED=1:

       nM> HEADERMOD/CREATE file DETACHED=1 SR=(LABL/2A,ABSC/SD,ORD/SD)

  5. To create a non-homogeneous Type 5000 file with a 16-byte ASCII field
     "NAME" followed by VectorDouble "POS" (similar to the cities.prm file):

       nM> HEADERMOD/CREATE file COMPONENTS=(NAME/2A,POS/VD/GEODETIC/DISTANCE_M)

Switches:
  /ATTACH - Attach a detached header to a Midas file
  /CREATE - Create the file from scratch
  /DETACH - Flags the header as being detached (since NeXtMidas 3.1.3)
  /VIEW   - Dumps a BLUE file header to the terminal, useful for i/o debugging.
            Does now work with VAX files. (Since NeXtMidas 1.9.2)

See Also: STATUS, nxm.sys.inc.Units, nxm.sys.lib.DataFile