### 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> (DataFile 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> (DataFile Only)
  Override the data format for the file.
FS=<frameSize> (DataFile 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] (DataFile Only) (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=<handlerConfig> (DataFile Only)
  Sets the packet handler configuration for a DataFile.
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> (DataFile 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.