KEYWORD
Jump to navigation
Jump to search
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