### Data Types

NeXtMidas works with a wide variety of data types. The types fall into two general categories Basic Types (numeric and text data) and Compound Types (Java Objects with attributes and functions).

#### Basic Types: Scalars, Atoms and Elements

NeXtMidas shared the standard Midas data types common to Blue Files and X-Midas

It's useful to introduce a few hierarchical terms to describe NeXtMidas data organization. Generally speaking, "data" means one or more elements, which comprise one or more atoms, which in turn comprise one or more scalars. For numeric data, a scalar is a single, real-valued number stored in a integer or floating-point format; for string data, a scalar is always an eight-character, ASCII-encoded "word."

NeXtMidas recognizes the scalar formats defined in the following table. It is convenient to use the indicated one-character data type codes as concise scalar format identifiers.

Scalar Format | Data Type | Scalar Size
Packed Bits | P | 1 bit
Nibble Packed Bits | N | 4 bits
Offset Byte (Not Supported) | O | 1 byte
Signed Byte | B | 1 byte
Signed 12-bit Integer | J | 12 bits
Signed (Short) Integer | I | 2 bytes
Signed Long Integer | L | 4 bytes
Signed Extra-Long Integer | X | 8 bytes
Single-Precision Floating Point | F | 4 bytes
Double-Precision Floating Point | D | 8 bytes
ASCII String (8 Characters) | A | 8 bytes
ASCII 256 Character String (since 3.9.4+) | Z | 256 bytes

Note: NeXtMidas supports Nibble and Packed data for storage and transport only. Prior to any processing, the data is extracted into complete bytes.

Caution: NeXtMidas 12-bit integer is also intended for storage and transport of type 1000 and 2000 data. Prior to any processing, the data is extracted into complete bytes. Operations only support writing out along byte boundaries, so there are some limitations in working with scalar 12-bit Some examples of SJ limitations are FFT frame sizes should be multiples of 2, Type 1000 Transfer Lengths should be multiples of 2, and the THIN command is not supported.

IMPORTANT NOTE

- 'Z' as a Data Type means a 256 character ASCII String.
- 'Z' as a macro result type (displayed as 'z') still means Boolean.
- 'Z' as a Table value type (displayed as 'z') also still means Boolean.
- DataFile Keywords are not allowed to be typed 'A' or 'Z'. ASCII types are saved as 'S' String.
- ASCII/String Macro RESULTS are stored as 'S' String type. Trying to directly type a result as 'A' type gives a warning, and the type is converted to 'S'.
- DataFiles with 'Z' Format Type Data, including in a subrecord, will be given the BLUE VER 1.2.

NeXtMidas recognizes the atom formats defined in the following table. It is convenient to use the indicated one-character data mode codes as concise atom format identifiers.

Atom Format | Data Mode | Atom Size
Scalar | S | 1 scalar
Complex | C | 2 scalars
Vector (3-tuple) | V | 3 scalars
Quad Vector (4-tuple) | Q | 4 scalars
Matrix (3x3) | M | 9 scalars
Transmatrix (4x4) | T | 16 scalars
Generic Multiplier | 1 ≤ n ≤ 9 | n scalars
Generic Multiplier (Ten) | X | 10 scalars
ASCII Multiplier (32) (since 3.1.0+ and X-Midas 4.6.0+) | A | 32 scalars

The number of atoms in an element depends on the high-level data structure. In the simplest case, an element comprises a single atom, and it is common to use the data mode/data type digraph to indicate the structure. For example, "CF"; connotes a set of complex-valued atoms whose real and imaginary parts are each single precision floating point numbers.

More complicated structures that NeXtMidas recognizes include framed and record data. In the former case, an element comprises frame length contiguous atoms. In the latter case, an element is a record that contains one or more subrecords that might or might not have the same atomic format. If the atomic format is consistent, records are homogeneous; otherwise, they're nonhomogeneous.

#### Compound Types

NeXtMidas provides access to many of the compound types defined in Java. The most common of these are:

- String - Java string of arbitrary length.
- Table - Tabular `KEY=VALUE` data (may include sub-tables).
- Message - A NeXtMidas message.

#### Typecasting in a Macro

When displaying results parameters with `RESULTS` (no 2nd argument) typecasting is used in two ways. If the `'*'` is used in <LABEL>, then the specified type is used to further limit the search (e.g. `RESULTS S:*` shows all string results, `RESULTS N:*` shows all numeric results, etc.). If no `'*'` is used, the result (if found) is cast to the specified type before being assigned or displayed.

The most useful aspect of this convention is that it is not controlled by the `RESULTS` command but by the shell; you can do explicit typecasting anyplace that a result is stored or set. For example,

    nM> status sine1 i:sinesize

forces `SINESIZE` to have a (Short) Integer type, even though `STATUS` normally stores a Double precision value into a file size result. If necessary, you can even force `STATUS` to store a string result:

    status/quiet sine1 s:sinesize
    res sinesize
    S:SINESIZE     = 4096

Macros recognize the following typecasts:

Data Type | Type Specifier
Signed Byte | B:
Signed (Short) Integer | I:
Signed Long Integer | L:
Signed Extra-Long Integer | X:
Single-Precision Floating Point | F:
Double-Precision Floating Point | D:
ASCII (similar to S:) | A:
String | S:
Boolean (since 2.5.0) | Z:
Generic Number (same as D:) | N:
Untranslated (do not substitute results values) | U:
Unknown (same as D: for numbers, S: all others) | _:
Message (used only in `processMessage`) | M:
Table | T:
Object (see KeyObject) | O:
List (X-Midas 4.6.0+ only) | C:
Table (X-Midas 4.6.0+ only) | H:
KVList (X-Midas 4.6.0+ only) | K:
XMValue (X-Midas 4.6.0+ only) | V:

It is also possible to type cast the parameters being passed into a macro, procedure or subroutine. For example:

    startmacro L:mynum S:mystring

Note that when passing parameters as described above, "N:" refers to a Number, as shown in the Table above. Otherwise (for example, when declaring a RESULT), "N:" is a NIBBLE data type, per the table at the top of the page.

#### Typecasting in a Primitive

Parameters passed to a primitive are handled by the `nxm.sys.lib.Args` reference `MA`. Examples of using this include:

    int mynum = MA.getL("MYNUM");
    String mystr = MA.getS("MYSTRING");

Once inside a primitive the standard Java typecasts are used.

#### Minimally Supported Types: Platinum Unsigned Integers

As of NextMidas 3.9.3, minimal support for 'U' and 'V' unsigned types has been added. These are not defined in the BLUE ICD, but they are defined in the PLATINUM ICD. The CoreIO IOOption MinimalSupportForUnsupportedDataTypes can be set to allow reading, displaying, and retrieval of values of these types in record data and keywords. Writing out of these types is not supported.

Scalar Format | Data Type | Scalar Size
Unsigned Signed (Short) Integer | I | 2 bytes
Unsigned Signed Long Integer | L | 4 bytes