Previous Next        Current Page: NeXtMidas User's Guide / Result Parameters
FAQs   
Release Information   
Getting Help   
Basic Concepts   
Result Parameters   
   - Data Types   
   - Tables   
   - Using KeyObject   
   + System Modeling Data   
XML Support   
Files   
System Operation   
Macros   
Applets and WebStart   
Graphics   
X-Midas Interoperability   
Third-Party Compatibility   
Installation and Customization   
Running NeXtMidas Independently   
Glossary   


Result Parameters

Valid Results Names

Results names must start with a capital letter (A..Z) or an underscore (_) and may contain capital letters (A..Z), numbers (0..9) and the underscore (_). All results names must match the following regular expression:

[A-Z_][A-Z0-9_]*

For ease of use and readability NeXtMidas will allow the user to enter results names that contain lower-case letters (a..z) and will automatically convert them to upper-case. Thus the following three statements are considered equivalent for the purposes of setting the result named COOLNESS:

SET COOLNESS 100
SET coolness 100
SET Coolness 100

Older versions of NeXtMidas did not fully check to see that results names were in conformance with this standard. As a result, some macros written for older releases of NeXtMidas that did not conform to this standard.

The following results are automatically created by NeXtMidas and can not be changed:

AUX   ENV   FUNC   OPT   RAM   REG
Additionally the following results names should be avoided (though such is not mandatory):
TRUE       FALSE      NULL       IS...      DO         ENDDO
IF         THEN       ELSE       ELSEIF     ENDIF      FORALL
FOR        ENDFOR     PROCEDURE  FUNCTION   SUBROUTINE RETURN
STARTMACRO ENDMACRO

Data Results Types

Please see Data Types for a complete list of available data types.

Automatic Type Conversion

When NeXtMidas encounters a parameter in a macro or on the command line, it tries to automatically convert it to the correct type. The following is an overview of this process:

  • If the name of the result is given NeXtMidas will use that result (it copies a pointer to the result).
  • If the parameter starts with a caret (^<RES_NAME>) NeXtMidas will substitute in the text value of the named result and then will attempt further conversion.
  • If the parameter starts with a double quote (") or single quote (') (e.g. "Queasy") it will remain as a case-sensitive string. However the outer quotes will be removed.
  • If the parameter starts with an opening curly brace ({) (e.g. {NAME="Stinky Pete",AGE=57}) it will resolve to a new Table. (See Tables for more details.)
  • If the parameter can be parsed as a numerical value (e.g. 42) or an array of numerical values (e.g. (3.14,180)), it will resolve to a new Data instance containing those values. Note that this will convert the following special numeric formats to numbers:
    • Dates (e.g. 2006:06:07::20:50:45.267) to seconds since midnight 1 JAN 1950
    • Times (e.g. 12:30:00) to seconds since midnight
    • Angles in DMS (e.g. 27'32'50) to decimal degrees
    • Hexadecimal numbers (e.g. 0xCAB) to integers
    • Numbers with binary multipliers (e.g. 16K) to integers
  • If none of the above are applicable then the parameter will resolve to a String.

Here are a few examples (assume two results are defined, NAME and HEIGHT that are equal to "Jasper" and 72, respectively):

Parameter                  What it Resolves To         Type        
SnackTime                  SNACKTIME (Uppercased)      String
"SnackTime"                SnackTime (Case Sensitive)  String
NAME                       Jasper (Copy Object Ref)    String
^NAME                      JASPER (Resolve, Uppercase) String
^{NAME}                    JASPER (Resolve, Uppercase) String
"^NAME"                    Jasper (Resolve, Quote)     String
"^{NAME}"                  Jasper (Resolve, Quote)     String
HEIGHT                     72                          Data (SL)
^{HEIGHT}                  72                          Data (SL)
^AGE                       ^AGE                        String
"Squeaky"                  Squeaky                     String
'the mouse'                the mouse                   String
{NAME=^NAME,AGE=47}        {NAME="JASPER",AGE=47}      Table
{NAME="^{NAME}",AGE=47}    {NAME="Jasper",AGE=47}      Table
{ABC                       ERROR                       ERROR
3.14                       3.14                        Data (SD)
(1,2,3)                    (1,2,3)                     Data (VD)
(1,a,b)                    (1,A,B)                     String
"0x1CAB"                   0x1CAB                      String
16K                        16384  (Multiplier K=1024)  Data (SL)
0x1CAB                     7339   (Hex -> Int)         Data (SL)
12:30:00                   45000  (sec since midnight) Data (SL)
2006:06:07::20:50:45.267   1.780865445267E9 (sec)      Data (SD)
27'32'50                   27.5472222222222 (deg)      Data (SD)

Accessing Basic Results Types

Any independent results type can be accessed using the name of that results type prefixed by a caret (^) (the caret is not mandatory, but is highly recommended). If there is reason to believe that a results name could be confused, the caret-curly-brace syntax can be used:

^{RESULTS_NAME}
The caret-curly-brace syntax is useful when trying to insert the value of a results parameter in a location that it would otherwise prevent normal parsing of the parameter:
nM> SAY "I caught a fish that was ^{FEET}ft-^{INCHES}in long."

Accessing Compound Results

One of the most powerful features of the macro language is the ability to access a variety of compound results types using a simple syntax. For example:

nM> SET NAME {FIRST="Frost",MIDDLE="The",LAST="Snowman"}
nM> SAY "His friends call him ^{NAME.FIRST}y."
His friends call him Frosty.

This syntax allows easy access to the following:

  • Java Methods
    - Using full method name.
  • JavaBean Properties
    - Using the property name, or
    - Using the acronym for the property name, or
    - Using an abbreviation for the property name.
  • Java Fields
    - Using the name of a static final field.
  • - Using the name of a non-static final field. (DEPRECATED)
  • Keyable Objects (includes Table, KeyVector)
    - Using the Key name.
  • Java Arrays, List and Data Objects (includes Vector)
    - Using the numerical index into the array/List, or
    - Using one of the following names for a given index:
    X --> 0,    ALT --> 0,    R --> 0
    Y --> 1,    LAT --> 1,    I --> 1
    Z --> 2,    LON --> 2
    T --> 3
  • Chained Objects
    - If the referenced object is Chainable and none of the above match, the next link in the chain is searched.

For more details, please see Using KeyObject.

Vectored Results

NeXtMidas provides the FILE(..) function to provide easy access to the values in a a file. The syntax for doing this differs significantly from X-Midas in order to prevent confusion between file operations and operations involving a file name.

Please see Accessing Files From Macros for more details.

Atomic Results

Atomic results are result parameters with more than one numeric element. All Midas results can have atomic formats such as SF, VD, or CF. A results table stores any atomic format that is supported by the file system along with any arbitrarily sized array of scalars. For example:

nM> res myres (0.5,3.3)
Creates a result of type CD, or complex double, or:
nM> res myres (1,2,3,4,5,6,7,8,9,10)
establishes an array of 10 numbers in the results table.

You can't do much with a 10 element array directly from the shell. However, each element of the array can be accessed separately using array element syntax such as the following CALC statement:

nM> CALC myres(3) myres(4) myres(5) + myres(6) /
This modifies the 3rd element of the result myres based on an expression using other elements of the result. (Note: To access a single element of an atomic result, the result must already exist and not be a scalar.)

Escape Sequences in Strings

Since NeXtMidas 2.9.0, it is possible to store result parameter Strings that contain escape characters. The escape sequences begin with a backslash ("\") followed by the standard Java escape sequence. For example, a newline in a String would be "\n". Unicode escape sequences begin with "\u" followed by four hex digits.

Example Escape Sequences:

  nM> res s:plusminus "\u00b1"
  nM> res plusminus
  1S: PLUSMINUS       = ±
  
  nM> res tabs "1\t2\t3"
  nM> res tabs
  5S: TABS            = 1        2       3