

1. Rules for Valid AUX Names
============================

1.1 AUX names are one or more characters in length and can contain a upper-case
    letters (A-Z), numbers (0-9), and the underscore (_).
    
    Names that start and end with an undersore (e.g. "_FOO_") are not valid
    (these names are reserved for internal use by the Midas framework).
    
    The following names are not allowed since they have special meaning within
    the AUXILIARY command:
    
      "ALL", "WRITE", "READ"
    
1.2 The following AUX names are reserved in NeXtMidas and can not be redefined
    by users:

      "CWD"      - The current working directory. Same as AUX 0 in X-Midas.
      
      "HOMEPATH" - The current homepath. Same as AUX 98 in X-Midas.

      "HOME"     - The user's home directory. This is the same as Mc.login_path
                   in X-Midas.

      "RAM"      - Internal NeXtMidas RAM AUX. All NeXtMidas pipes are
                   included in this AUX (this allows the FILES command to
                   list the active pipes).
                   
      "XMPIPE"   - When NeXtMidas is running as an option tree for X-Midas, all
                   X-Midas pipes are automatically added to this AUX the same
                   way that NeXtMidas pipes are added to the RAM AUX.

    These names are similarly reserved for system use within X-Midas.
    
1.3 Any AUX name that contains only numbers (0-9) is called an AUX number
    and is subject to the following additional rules:
    
1.3.1 It may not have any leading zeros (e.g. "0120" is not valid, use "120").

1.3.2 The numeric value may not exceed 16777215 (0x00FFFFFF).


2. How AUX Names Works
======================

2.1 If an AUX name can be considered an AUX number under section 1.3 it is
    automatically translated to its numeric representation (e.g. "110"=110).

2.2 For compatibility between legacy X-Midas applications (which use 0 and 98)
    and legacy NeXtMidas applications (which use "CWD" and "HOMEPATH"). The
    AUX names "CWD" and "HOMEPATH" are automatically assigned the numeric
    aliases of 0 and 98 respectively.
    
2.3 Any AUX name that is not handled under section 2.1 or 2.2, is automatically
    assigned a numberic alias by the Midas framework. The assigned number will
    be between 16777216 and 2147483647 (i.e. between 0x01000000 and 0x7FFFFFFF).
    
    Existing host primitives that use the old X-Midas API (using AUX numbers)
    will continue to function, provided an integer*4 was used to hold the AUX
    number (this is very common). The numbers assigned will follow the old
    X-Midas rules (including the special cases where the write AUX is a
    negative number), except that they will be outside of the previous range
    of AUX numbers.
    
    Once a numeric alias has been assigned for a given AUX name, that alias
    will remain the same until the user exits the Midas session. If the user
    removes a named AUX and then later adds it back, it will still use the
    same AUX number. This functionality is handled internally by the Midas
    framework.
    
    Assignment of numeric aliases is internal to the Midas framework and
    users may not override this assignment. The public API for the framework
    will provide functions to allow translation between name and number.
    (This "extra step" is intentional, see Section 2.4 for details.)
    
    The Midas framework will automatically translate between AUX name and its
    numeric alias. The API functions that take in the AUX name will also
    accept the numeric alias in string form.
    
2.4 The use of AUX aliases is intended to be a transitional step to replacing
    the current number-based API in X-Midas with a name-based API (where the
    names could be numeric strings, e.g. "110"). All of the new name-based
    API methods will accept the numeric aliases (in string form) in order to
    encourage their use.
    
    Future releases of the Midas framework will deprecate the existing
    API methods that use AUX numbers in favor of using the new name-based
    methods. Subsequent to this, the methods that translate name to number
    will be deprecated and will function as a noop simply returning the
    AUX name as it's only alias.

2.5 The numeric aliases for all currently-defined AUX entries will be shown
    when the user uses:

      X-Midas> AUX/LIST
    or
      nM> AUX/LIST
    
    The alias will be listed as "Alias=<alias>" off to the right of the
    path name.

2.6 System commands (X-Midas SYS option tree) will be changed to support either
    the AUX name or its numeric alias, however such an alias will be returned
    in string form (this allows future versions to stop assigning numbers, see
    section 2.4 for details). For eaxmple, the following two lines will
    produce identical results (in this case 16777216 is the numeric alias
    that X-Midas assigned to "FOO"):
    
      X-Midas> files ,,, FOO
      X-Midas> files ,,, 16777216

    The AUX= file name qualifier will accept either the name or numeric alias.
    For example:
    
      X-Midas> xplot myfile(AUX=FOO)
      X-Midas> xplot myfile(AUX=16777216)

    The handling of the AUX= qualifier is done in the file I/O libraries for
    compatibility with existing primitives that add AUX numbers to the end of
    file names.


3. Implementation Details
========================= 
3.1 For debugging purposes, X-Midas and NeXtMidas use different numeric ranges:
    
      0x01000000 to 0x01FFFFFF - Assigned by X-Midas framework
      0x02000000 to 0x02FFFFFF - Assigned by NeXtMidas framework (used when
                                 running X-Midas primitives via the XBC option
                                 tree)
      0x04000000 to 0x04FFFFFF - Reserved for use by NeXtMidas framework when
                                 running from an old version of X-Midas
    
    The high-order byte in the AUX number is a bit field indicating which
    framework assigned the alias (0x01=X-Midas, 0x02=NeXtMidas, etc). If no
    bits are set in the high-order byte, the AUX number was a direct
    translation (e.g. "110"=0x0000006E=110). The most significant bit (0x80)
    is never set since the AUX number is a signed integer.
    
    The actual assignment within this above range is at the discression of the
    X-Midas and NeXtMidas developers.
    
3.2 When NeXtMidas is run as an option tree from newer versions of X-Midas, it
    will defer to X-Midas to handle the assignment and translation of the
    numeric aliases for any cases that fall under Section 2.3 (NeXtMidas may
    internally handle translation of cases that fall under Sections 2.1 and
    2.2).
    
    When NeXtMidas is run as an option tree from older versions of X-Midas
    (e.g. X-Midas 4.4.4), it will handle the assignment and translation of
    the numeric aliases.

    When NeXtMidas is run apart from X-Midas, it will handle all assignment
    and translation in order to support the running of existing X-Midas host
    primitives via the XBC option tree.
