KEYWORD
From ICE Enterprises
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>
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
KEY <file> SVGET/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> SVSET/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
