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
  2. What Works
    Complete list of wrapped M$ calls:
  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:

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.
64 Bit Support

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

Note: Be sure to source the correct version of the compiler for your platform.

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).

Caveman 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.

Caveman 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):

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.

Caveman 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:

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: