KEYWORD

Facility for displaying and changing keyword fields in a file header.

KEYWORD - facility for displaying and changing keyword fields in a file header

<file>  File to access
<func>  Keyword function to perform on file
<name>  Keyword name, if applicable for <func>
<value> Keyword value, if applicable for <func>

KEYWORD provides access to the keyword fields in a file header.  Keywords
allow unrestricted free-format information storage in a KEY=VALUE format.
Keywords are typically stored in the extended header, which is extensible to
any size.

The main header also has limited keyword storage (88 characters).  In general,
the user should use the EXTENDED header for keywords and reserve the MAIN
header keyword space for system use.

Functions:

  ADD    Add a keyword in the MAIN or EXTENDED header. SET with flags=ADD.
         This can result in more than one key with the same name in the same
         scope. Multiple keywords can be added at once by specifying a list of
         name/value pairs.

           KEY <file> ADD NAME=<name> VALUE=<value> [<name2> <value2> ...]

  DEL    Delete a keyword

           KEY <file> DEL NAME=<name>

  FGET   Create an ASCII text file (<file>) containing the keywords and their
         character string values. If <name> is not given, the output goes
         to a file called "<file>.key", in the same directory as <file>.
         See section ".KEY FILES" below for more on the format of the .KEY file.

           KEY <file> FGET <name>

  FPUT   Alias for FSET.

  FSET   Replace current keyword entries by the entries in an ASCII keyword
         file (<name>). If <name> is not given, KEYWORD looks for a file called
         "<file>.key" in the same directory as the <file>. See section
         ".KEY FILES" below for more on the format of the .KEY file.

           KEY <file> FSET <name>

  GET    Get a keyword or keywords from the MAIN or EXTENDED header.

           KEY <file> GET NAME=<name> VALUE=<result name>

         Since NeXtMidas 2.5.0, multiple keywords can be retrieved on a single
         line.

           KEY <file> GET <KEYNAME1> <RESULTNAME1> [<KEYNAMEn> <RESULTNAMEn>...]

  LIST   List to terminal all keywords matching <name> and their values in
         both main and extended headers; or all keywords if <name> is blank

           KEY <file> LIST             ! list all keywords
           KEY <file> LIST <name>      ! list only those matching <name>

         Since NeXtMidas 2.7.0, <name> can be a wild-card pattern to indicate
         that all matching keywords should be listed (e.g. "*EX*" would list
         all keywords containing an "EX" in the name, "?VAL" will match any
         four-letter keywords ending in "VAL").

           KEY <file> LIST <name>      ! list keywords matching pattern <name>

         Optional flags:
           /S   - Sort entries before printing to terminal. Note that this will
                  attempt a "friendly sort" such that "ABC2" comes before
                  "ABC12", but does not preserve any internal scoping of the
                  keywords (other than MAIN vs EXT).     [Since NeXtMidas 3.3.0]

  PUT    Alias for SET.

  SET    Put a keyword in the MAIN or EXTENDED header. This will replace the
         named key in the same scope at the original location. Multiple keywords
         can be set at once by specifying a list of name/value pairs.

           KEY <file> PUT NAME=<name> VALUE=<value> [<name2> <value2> ...]

  SVGET                                                  [Since NeXtMidas 3.3.0]
         Gets state vector keywords from the file. One of the following
         modifiers may be included to specify the keyword format (if no
         qualifiers are specified an attempt will be made to try all available
         formats):
           /E   - Ephemeral keywords: ETIMn, POSXn, POSYn, POSZn, etc.
           /P   - Platinum keywords:  [prefix].TIME, [prefix]_POS.X,.Y,.Z, etc.
           /L   - Platinum keywords:  [prefix].LON,.LAT,.ALT
           /V   - Vector keywords:    ETIM_VEC, POSX_VEC, POSY_VEC, etc.

         Note that the {SVPREFIX=[prefix]} qualifier should be used to set the
         prefix as needed for /P and /L modes (if not specified, it defaults to
         "EPH" with /P).

         The /DT= switch will force all points to have the given time-delta
         between them rather than exactly matching the input points. If /DT=0
         the time delta will be set based on the keywords (defaulting to 1 min
         if the keywords are not evenly spaced). If the output is a Type 5000
         file, /DT=0 is implicit unless otherwise specified.

         The output will be written to the specified state vector file. If the
         file already exists, any data in the file will be overwritten; if not,
         a new file will be created. For a BLUE file (.tmp/.prm) the output will
         be a Type 5001 file unless the TYPE= qualifier is used to designate an
         alternate type. All Type 5000 files will have their QUADWORDS set as
         appropriate. Usage:

           KEY <file> SVGET/E <svFile>

  SVPUT                                                  [Since NeXtMidas 3.3.0]
           Alias for SVSET.

  SVSET                                                  [Since NeXtMidas 3.3.0]
         Sets state vector keywords into the file. Must include one or more of
         the following modifier switches indicating the state vector format:
           /E   - Ephemeral keywords: ETIMn, POSXn, POSYn, POSZn, etc.
           /P   - Platinum keywords:  [prefix].TIME, [prefix]_POS.X,.Y,.Z, etc.
           /L   - Platinum keywords:  [prefix].LON,.LAT,.ALT
           /V   - Vector keywords:    ETIM_VEC, POSX_VEC, POSY_VEC, etc.

         Note that the {SVPREFIX=[prefix]} qualifier should be used to set the
         prefix as needed for /P and /L modes (if not specified, it defaults to
         "EPH" with /P).

         Usage:

           KEY <file> SVSET/E <svFile>

  TCDEL                                                  [Since NeXtMidas 3.3.0]
         Deletes all time-code keywords from the file.

         Usage:

           KEY <file> TCDEL

  TCGET                                                  [Since NeXtMidas 3.3.0]
         Gets time-code keywords from the file. Must specify one input and one
         output modifier from following:
           Input Options:
             /X - X-Midas style keywords: TC_WHOLE_n, TC_FRAC_n, etc.
           Output Options:
             /I - ICE packets

         Usage:

           KEY <file> TCGET/X/I <ice_pkt_file>

  TCPUT                                                  [Since NeXtMidas 3.3.0]
         Alias for TCSET.

  TCSET                                                  [Since NeXtMidas 3.3.0]
         Sets time-code keywords in the file. Must specify one input and one
         output modifier from following:
           Input Options:
             /I - ICE packets
           Output Options:
             /X - X-Midas style keywords: TC_WHOLE_n, TC_FRAC_n, etc.

         Usage:

           KEY <file> TCSET/I/X <ice_pkt_file>

  TGET   Create a Results Table (<name>) containing the keywords and their
         values. If <name> is not given, the output goes to a Results Table
         which uses the root of <file> for its table name (e.g. MYFILE for
         "myfile.prm"). NOTE: For SCOPED Keywords, only the values in the
         final SCOPE will appear in the Results Table when the /SCOPE switch
         is NOT used.

           KEY <file> TGET <name>              ! Create a "flat" table

         or

           KEY/FLAT=F <file> TGET <name>       ! Create a table with INNER
                                               ! and EXTENDED inner tables

  TGET/F Similar to TGET except that keywords are written to a .tbl file
         (<name>) rather than a table in the results table.

           KEY <file> TGET/F <name>            ! Create a table file

         or

           KEY/FLAT=F <file> TGET/F <name>     ! Create a table file with
                                               ! INNER and EXTENDED inner tables

.KEY FILES
  The .KEY file used by FGET and FSET have one keyword name/value pair per line.

  The format is:

          NAME=VALUE    ! single "=" for main header
          NAME==VALUE   ! double "==" for extended header

  "NAME" can start in any column.  "VALUE" is interpreted literally (no quotes
  needed, space retained) and stored by default in ASCII.  NAME can be preceded
  by a type character as with results parameters, to typecast the value as
  numeric (with binary storage).  The special type "S[<len>]"  means an ASCII
  string of length <len>; this is a way of forcing/capturing trailing spaces.
  Keyword arrays are represented by type-casting to numeric and separating the
  keyword values with commas.  A "&" at the end of the line forces continuation
  to the next line.  Blank lines or anything after a "!" are interpreted as a
  comment and ignored.

  To load all key/value pairs into the extended header, use the /EXTONLY switch.
  This is useful for loading a 3rd party key=value text file into the
  extended header without having to change = to == in the text file.
  Use this switch to revert to behavior prior to NeXtMidas 3.1.2.


KEYWORD SCOPE
  Keyword "scope" refers to the keyword storage range actually visible at any
  given time.  By default, the entire extended header is visible.

  Special scope syntax:
    * To access keywords in the main header, use /SCOPE=MAIN.
    * To access keywords at the start of the EXTENDED header, use /SCOPE=EXT.
    * To INCLUDE the scope keyword in your output use /SCOPE=TAG=VALUE
    * To EXCLUDE the scope keyword in your output use /SCOPE=TAG-=VALUE
    * To EXCLUDE the scope keyword but INCLUDE the next use /SCOPE=TAG+=VALUE

Examples:
  1. Create a file, put a keyword in it and extract it.
      nM> header/create junk.tmp
      nM> key junk.tmp PUT mykey "INITIAL VALUE"
      nM> key junk.tmp GET mykey myval
      nM> res myval
      13S: MYVAL           = INITIAL VALUE

  2. Replace the value of the keyword inserted above with a new value
      nM> key junk.tmp PUT mykey "NEW VALUE"
      nM> key junk.tmp GET mykey myval
      nM> res myval
       9S: MYVAL           = NEW VALUE

  3. Scope with multiple keywords. Put the DUMMY keyword in twice and
     Now use scope to get the second DUMMY keyword.
      nM> header/create junk.tmp
      nM> keyword junk.tmp PUT DUMMY DUMMY1  TAG2 VAL2  NODE MYNODE
      nM> keyword junk.tmp ADD DUMMY DUMMY2
      nM> keyword/scope="TAG=NAME,NODE=MYNODE" junk.tmp GET DUMMY out
      nM> res out
       6S: OUT             = DUMMY2

    NOTE: Using () around the scope keyword works as well.
      nM> keyword/scope=(TAG=NAME,NODE=MYNODE) junk.tmp GET DUMMY out

  4. Special syntax for /SCOPE. For a file with the keyword list:
      TIME==12:00
      FREQ==31e6
      AMPL==1.1
      TIME==13:00
      FREQ==32e6
      AMPL==1.2
      TIME==14:00
      FREQ==33e6
      AMPL==1.3

      KEY/SCOPE=TIME=13:00
              (includes TIME=13:00, FREQ=32e6, and AMPL=1.2 in scope)

      KEY/SCOPE=TIME-=13:00   ! "-=" means skip /scope keyword
              (skips TIME=13:00, includes FREQ=32e6 and AMPL=1.2 in scope)

      KEY/SCOPE=TIME+=13:00   ! "+=" means skip /scope keyword, include next
              (skips TIME=13:00, includes FREQ=32e6, AMPL=1.2, TIME=14:00)

  5. PUT a "D_VEC" keyword containing a vectorized list/array of doubles
      nM> keyword junk.tmp PUT "D_VEC" (1.1,2.2,3.3,4.4,5.5)

     PUT a "I_VEC" keyword containing a vectorized list/array of short integers
      nM> res I:data (1,2,3)
      nM> keyword junk.tmp PUT "I_VEC" data

  6. ADD multiple keywords using a single command
      nM> keyword junk.tmp ADD KEY1 "1st-Val" KEY2 "2nd-Val" THIRDKEY "3rd-Val"

Switches:
  /DT=     - Override the time delta used for SVGET.
  /EXTONLY - FPUT or FSET only. Load all key/value pairs from .KEY file into the
             extended header. (Since NeXtMidas 3.1.2) [DEF=FALSE]
  /FLAGS=  - Keywords flags/settings to use. [DEF=none, NoAbort for FUNC=LIST]
               NoAbort - Try to continue when an invalid keyword block is found.
               See also nxm.sys.lib.Keywords.flagsList. (Since NeXtMidas 3.1.1)
  /FLAT    - TGET or TGET/F only.  Generate a flat table or a table with
             inner tables MAIN and EXTENDED [DEF=TRUE]
  /LEGACYLIST - For LIST only, use old listing format prior to NeXtMidas 3.3.0
             that has paging enabled.        (Since NeXtMidas 3.5.4) [DEF=FALSE]
  /PREFIX= - Sets the prefix used with Platinum keywords in SVGET and SVSET.
  /SCOPE=  - restricts range of keywords currently visible.
               /SCOPE=MAIN will GET or SET in the main header.
               /SCOPE=EXT will GET or SET at the start of the extended header.
               /SCOPE=ALL will GET or SET in the main or extended header.
                      This is the equivalent of a space " " in X-Midas.
  /WARN    - State switch for warnings [DEF=TRUE]

See Also: STATUS, nxm.sys.lib.Keywords