Qualifiers

A data file specification may include one or more qualifiers to modify the normal interpretation of the file. They provide for specific value indexing, or other tuning parameters. Qualifiers are similar in concept to command switches in that they alter the way the file is accessed (when read in from disk), but do not alter the actual file (on disk). The qualifiers are specified via a table (i.e. using curly braces, {}) that is appended onto the end of a file name (make sure there are NO spaces between the end of the file name and the opening left curly brace).

Note: Qualifiers must come after any file trimmers (which use parentheses, ().)

Examples

  1. Simple example adding qualifiers onto myfile.csv:
    nM> plot myfile.csv{HEADERROWS=1,TAG=MYTAG}
  2. Since the qualifiers are a table they can also be given via:
    nM> set quals {HEADERROWS=1,COLUMNNAMES="NAME|CODE|F:LAT|F:LON"}
    nM> plot world|airports.csv^{quals}
  3. Or even (using the special Table merge function):
    nM> set quals {HEADERROWS=1,COLUMNNAMES="NAME|CODE|F:LAT|F:LON"}
    nM> plot world|airports.csv{HEADERROWS=3}^{quals}
    In this example HEADERROWS=1 would override {HEADERROWS=3} since it comes later.
  4. The table merge function makes it possible to write a macro that adds qualifiers onto a given file name, even if that file name already includes qualifiers:
    startmacro s:fname
      plot world|^{fname}{LAYER={COLOR=RED}}
    endmacro

Available Qualifiers

While qualifiers are handled by the individual file types, most file types will accept any qualifier that matches one of the settable fields for the class. Some of the most common qualifiers include:

AUX=<aux>
Specify the read/write AUX to use for the file.
This overrides the default read and write AUX settings.
DS=<start> (DafaFile Only)
Data start position in a non-detached file.
Note that the indicated byte position in the file at which the data starts; it does not specify initial values for the data in the file (see XS= and YS=).
EXIST=<mask>
Sets the existence algorithm used when checking for the existence of a given URL (the default is "CGI|STATUS"). The accepted values include:
  • NONE - Turns off any explicit existence checks. URLs are assumed to exist.
  • CGI - Performs a check on the URL string itself to determine if the URL points to a CGI script. If the URL string contains known patterns then the existence is true.
  • LIST - Attempts to retrieve a directory listing of the directory containing the URL. This listing is examined and determines if the named file exists. Under some conditions this can be very useful. (Note: The server and the directory must support server generated listings for this to work properly.)
  • STATUS - A HEAD request is performed on the URL and the status code of the response is examined. If the status code indicates success then the URL is assumed to exist. This can cause problems with CGI scripts since the script must be executed in order for the status code to be generated.
  • ALL - Uses all of the tests (except NONE).
In general this qualifier only applies to HTTP resources.
EXTKW="<label>=<value>" (DataFile Only)
Adds or replaces extended header keywords during file open
Can provided multiple label=value combos when they are comma separated
It is important to use the type character, if the type is not String
For example: EXTKW="D:EXTKW1=3.14,I:EXTKW2=2,MYSTR=HELLO"
FG=<ext>
Specifies "file group" that the file belongs to. By default the group for a file is determined based on its extension (".txt"=TextFile, ".prm"=DataFile, ".csv"=CsvFile, etc). This qualifier can be used to (1) override the file's extension (e.g. FG="TXT" can be used to open a CSV file as if it was a text file), or (2) specify the type for a file (or more commonly a URL - which may point to a Perl script) that does not have a file extension.
For a complete list of file groups supported (and their associated Java class) type:
nM> res reg.handlers.file
FLAGS=<mask>
Sets special I/O flags to be used when working with the file.
See the docs for nxm.sys.lib.BaseFile for a complete list of the available I/O flags.
FORM=<format> (DafaFile Only)
Override the data format for the file.
FS=<frameSize> (DafaFile Only)
Overrides the Frame Size for a data file.
Type 1000: If <frameSize> > 0 the Type 1000 file to be treated as a Type 2000 file with the specified frame size.
Type 2000: If <frameSize> > 0 the frame size is set accordingly, if <frameSize> = 0, the Type 2000 file will look like a Type 1000 (which has a frame size of 1).
Other Types: This is intended for use with a Type 1000 or a Type 2000 file; its use with other types may be unpredictable.
(Note: For this qualifier, 0 is used to indicate a Type 1000 file since 1 is a valid, though uncommon, frame size for a Type 2000 file.)
LAYER=<tbl>
This is a special qualifier that is used by PLOT to set the layer settings for the file when plotted.
Note that <tbl> is a table and may include nested tables such as LINE={...}.
MAINKW="<label>=<value>" (DataFile Only)
Adds or replaces main header keywords during file open
Can provided multiple label=value combos when they are comma separated
The type is always String
For example: MAINKW="MYMAINKW=YES!"
PROT=[0|1] (Deprecated)
Modifies file protection flag for a DataFile.
Provided for compatibility with X-Midas.
The FILE command should be used to protect or unprotect a file in NeXtMidas.
PS=<size> (Pipes Only)
Sets the size of a pipe.
PACKET=<???>
???
SAMETLKW=<boolean>
Specifies if the file should contain exactly the same timeline keywords as contained in the reference file. Also can be specified as SAMETIMELINEKEYWORDS.
TAG=<name>
Sets the ID of a file. By default the tag for a file matches the name of the file (less the file extension).
This is most commonly used to identify a layer in a PLOT.
TYPE=<type> (DafaFile Only)
Override the Blue file type (e.g. TYPE=1999).
XD=<delta>
Override the X-delta value.
XS=<start>
Override the X-start value.
XU=<units>
Override the X-units value.
The value of <units> can one of the following:
  • The special code identifier for the units (discouraged, this is only included for compatibility with X-Midas).
  • The full units name (e.g. XU="FREQUENCY_HZ").
  • A valid units abbreviation (e.g. XU="FREQ").
A complete list of the supported units is included in the docs for the nxm.sys.inc.Units class.
YD=<delta>
Override the Y-delta value.
YS=<start>
Override the Y-start value.
YU=<units>
Override the Y-units value.
The valid values for <units> is identical to those used for XU=.

Qualifiers Notes

When file qualifiers are masks, the also have the additional options:
ALL - for all options (-1)
NONE - none of the options (0)
DEF - the default option (case dependent)

Tests can be combined by combining the strings with a '|' (bar) separator. For example: 'EXIST=CGI|STATUS' will apply CGI and STATUS tests for the exist qualifier.