### X-Midas Backwards Compatibility (XBC)

The NeXtMidas `XBC` option tree enables X-Midas host Fortran primitives to run in NeXtMidas without modifying the primitive or an X-Midas installation. With XBC, developers can use existing X-Midas signal processing primitives in NeXtMidas without converting them to C/C++ or Java. Although XBC does not require X-Midas to use host primitives on platforms where X-Midas does not run, host primitives with system Dependent code (`#if VMS`, etc.) or those that use deprecated X-Midas functionality may require minor modification.

1. Requirements
   - 64 Bit Support
2. What Works
   Complete list of wrapped `M$` calls:
   - XBC Support (Categorical)
   - XBC Support (Alphabetical)
3. Building
4. Sending Messages to a Host Primitive
5. Limitations of XBC Applications

#### Requirements

XBC requires both a Fortran (in addition to the Java and C/C++ compiler used to install NeXtMidas). The following Fortran compilers work with the current version of XBC:

- `ifc` - Intel Fortran Compiler (version 7.1)
- `ifort` - Intel Fortran Compiler (version 8, 9)
- `pgf77` - Portland Group Fortran 77 (version 4.0, 5.1, 6.1)

By default NeXtMidas will try to determine which Fortran compiler to use based on the `XM_FORTRAN` environment variable. This can be overridden by setting the `NM_FORTRAN` environment variable to the name of the compiler to use. The `fflags.compiler` property in `$NMROOT/nxm/sys/cfg/build.props` enables this behavior (`fflags.compiler = auto`) or can disable it by specifying the Fortran compiler to be used at all times.

Note: There is a known bug in Java 1.4 related to garbage collection that can result in a core dump when making extremely frequent M$... calls from a host primitive (typically seen if polling a results parameter with little or no pause between calls). Upgrade to Java 5.0 to avoid this.

##### 64 Bit Support

The following compilers work with the current version of XBC on 64 Bit systems:

- `ifort` - Intel Fortran Compiler (version 9.1.x)
- `icc` - Intel C/C++ Compiler (version 9.1.x)

FYI: X-Midas 4.4.4 currently does not build with the Intel C/C++ 10.x Compiler.

Note: Be sure to source the correct version of the compiler for your platform. i.e. for Intel EM64T (64bit) processors (use "fce" and "cce" NOT "fc" and "cc"). Replace `/opt/intel/fce/9.1.051` and `/opt/intel/cce/9.1.051` with your Intel FORTRAN and C++ installed directories.

- `$ source /opt/intel/fce/9.1.051/bin/ifortvars.csh`
- `$ source /opt/intel/cce/9.1.051/bin/iccvars.csh`

Minor modifications to your build.props file are required to build XBC with support for 64 Bit systems. You need to make the following changes to "`$NMROOT/nxm/sys/cfg/build.props`":

1. Comment out the section for the "GNU C/C++ Compiler on Linux"
2. Un-comment the section for the "Intel 9.1 C/C++ Compiler on Linux"
3. In "ifort.comp" and "ifort.link" remove `-i-static` to work around an Intel compiler bug

#### What Works

This table compares the features available to host primitives in X-Midas 3.8.3 and the current version of XBC. Note that support for low-level I/O, OpenVMS, X11 graphics and system calls are outside of the scope of XBC. See XBC Support for a complete list.

XBC does not support any of the X-Midas functions that were marked as deprecated in X-Midas 3.8.3 or earlier. It does not support any of the non-standard preprocessing of `xfpp` (XBC uses the Fortran compiler's preprocessor).

WARNING: Old versions of X-Midas (prior to 4.3.0) use a preprocessor that incorrectly converts any file names in `INCLUDE` statements to lower case. Any `INCLUDE` statements that relied on this will need to be fixed before using XBC.

#### Building

XBC is build by adding XBC to the path and the using `MAKE`.

    nM> PATH ADD XBC
    nM> MAKE ALL XBC

Do not use "`BLD ALL ALL XBC`" as it will skip some of the required steps.

If you have an option tree that uses XBC you will need to have XBC on the path before it can be compiled (NeXtMidas will not compile or link any Fortran code if XBC is not on the path). It is highly recommended that you have a custom `BUILDOPT` macro for your option tree that calls the one in XBC, doing so will make sure that any of the extra XBC steps (such as processing `messages.cfg`) are done correctly. Here is an example `buildopt.mm` macro to use:

    ! Calls the BUILDOPT;XBC to build the option tree.
    startmacro u:option["MYOPT"]
      BUILDOPT;XBC ^option
    endmacro

#### Sending Messages to a Host Primitive

NeXtMidas does not deal with "configured" and "unconfigured" messages the same way X-Midas does. In NeXtMidas the data can be any object (frequently a Table) without any specific configuration. When sending a message to a host primitive that expects a data field packed into a byte buffer XBC needs to translate a NeXtMidas message to an X-Midas message. The way it does this depends on if the message is configured or not:

Configured Messages: XBC expects the message to be a table with tags that match the names in the structure of the message. For example, if the message was configured as:

    name  msglog
    L:severity              ! 1=Error, 2=Warning, 3=Informational
    S[24]:date_time         ! Timestamp
    S[40]:source            ! Primitive name which initiated message
    S[80]:text              ! message text to be displayed

XBC would expect the table to have the fields `SEVERITY`, `DATE_TIME`, `SOURCE` and `TEXT`, such as:

    MESSAGE SEND MSGLOG MSGLOG ^id ^info {SEVERITY=^severity,&
      DATE_TIME="^time",SOURCE="^source",TEXT="^text"}

Note that if any of the required fields are missing XBC will fill in a 0 value (`" "` for strings) in its place. Any extra fields will be ignored. This means that if there is a typo in one of the tag names it will zeroed-out without warning!

When a configured message is send from a host primitive to the macro the reverse is done. XBC translates the data buffer into a Table.

NeXtMidas does not support modifying the name of the info field in a message. This means that all info fields will be `info` inside a NeXtMidas macro/primitive even if the host primitive uses an `infoalias`.

Unconfigured Messages: Unlike configured messages, which XBC knows how to format, unconfigured need to have their formatting information encoded in the data section of the message. An unconfigured message must have a data table that includes the following fields that match those described in the explain file for `MESSAGE` in X-Midas (note that the arguments must match the 8-byte alignment rules specified in the X-Midas explain file):

- `ARGS` - The number of arguments.
- `TYPE` - The type(s) of the arguments.

Each of the arguments should be in the table with `VALn=` where `n` is the argument number (order in the table is not important, only the tag number is), for example:

    message send echoid SPAM SPAM ^info {TYPE="LLA",ARGS="3",&
      VAL1=^lval1,VAL2=^lval2,VAL3="^mystr"}

When an unconfigured message is send from a host primitive to the macro XBC translates the data buffer into a Table but does not include the `TYPE` and `ARGS` entries.

Since host primitives are unable to handle NeXtMidas ID's (which are strings) all messages from a host primitive will be sent to the same location as specified by the `/MSGID=` switch passed to the host primitive. By default `/MSGID=` is set to null, to see the messages in the `processMessage` procedure of a macro use `/MSGID=MAIN`.

#### Limitations of XBC Applications

Although XBC allows Fortran code in NeXtMidas, there are limitations placed on applications using XBC which are not placed on pure-Java applications:

- Compiled applications are platform-Dependent and cannot run easily as a WebStart application.
- Applications cannot compile without a Fortran compiler. (Read the release notes to see which compilers have been tested with XBC).
- Primitives requiring platform-Dependent functions do not run on other platforms. (Similar to running in X-Midas.)

#### Linking to an Existing X-Midas Installation

Although XBC does not require X-Midas to build or run, you can use the host primitives from an existing X-Midas installation. The following steps explain this:

1. Make a symbolic link from your `$NMROOT/nxm` directory to the `xm` directory of the X-Midas installation.
2. Create a `commands.cnf` file in the `$NMROOT/nxm/xm/cfg` directory which contains entries for all the commands XBC will use.
3. Start NeXtMidas and add `XBC` to the path.
4. Add `XM` to the path.
5. Build the `XBC` option tree using `MAKE ALL XBC` (if required).
6. Build the `XM` option tree using `MAKE ALL XM`.

#### Compiling Host Primitives

The syntax for building host primitives is the same as building other primitives in the `BLD` and `MAKE` commands. However, there are some subtle differences:

- The XBC option tree must be in the path prior to building.
- Only the primitives listed in the NeXtMidas command dictionary (`commands.cnf`) are compiled.