RESULTS

From ICE Enterprises
Jump to navigation Jump to search

handles creation and display of results parameters

<LABEL> - Label of result(s)
<VALUE> - Value to assign to result <LABEL>

The results table is a collection of label-value pairs that allow the user
to establish mnemonics for often used numbers (e.g. PI). It is the central
collection of scalar values passed among commands. The RESULTS command
handles results parameter creation and display.

<LABEL> is valid if its first character is alphabetic (A-Z and underscore)
and if each following character is either alphabetic or a digit (0-9).

If called with <LABEL> only, the value of the result named <LABEL> is
displayed.  An asterisk (*) may be used as the last character of <LABEL> to
match all results that start with <LABEL> (e.g. RESULTS A*).  If called with
no arguments, RESULTS displays the values of all (non-hidden) results
parameters (i.e. <LABEL> defaults to '*').

If called with both <LABEL> and <VALUE>, RESULTS sets the value of the
result named <LABEL> to <VALUE>.

To view the contents of nested results tables use the /ALL switch or specify
the table name in <LABEL>.  Individual members of nested tables are accessed
by separating the table name from the member name with a dot (e.g. ENV.USER).


Special or Reserved Names
-------------------------
  The following result names are reserved for system or special use and as such
  should not be used in one's macro:
    AUX - A table of directories for reading/writing files
    ENV - A table of environment settings
    OPT - A table of packages (option trees) available to the programmer
    RAM -
    REG - A table of references of live primitives or objects
    infinity - A string representing infinity

In-Line Functions
-----------------
  There are a number special/reserved words used to modify the behavior of
  results called In-Line functions (inline):
      CALC(<expr>)  - In-Line calculator (see CALC explain for operators)
      FILE(<name>)  - In-line to access files (BLUE files only, see DataFile
                      API for advance usages)
      SEDIT(<func>) - In-line SEDIT function (see SEDIT explain for functions)
      TEST(<test>)  - In-line boolean check using 0 and 1 for FALSE,TRUE
                      (see IF explain for tests)

  See examples below.

Type Casting
------------
  In assigning results parameters, a result's type is typically assumed to be
  numeric if <VALUE> is a translatable numeric expression otherwise it is
  usually stored as a String result (the "Results" section in the "NeXtMidas
  User's Guide" has details). A result's type can be cast (forced or strongly
  typed) by prefixing <LABEL> with a type and colon. A complete list of the
  types allowed is given in the "Results" section in the "NeXtMidas' User's
  Guide," a few of the more common ones include:

    B:<LABEL> - Byte (8-bit)
    I:<LABEL> - Short Integer (16-bit)
    L:<LABEL> - Long integer (32-bit)
    X:<LABEL> - Extra Long integer (64-bit).
    F:<LABEL> - Float (32-bit)
    D:<LABEL> - Double precision (64-bit)

    S:<LABEL> - STRING (will translate <VALUE> if a valid STRING result)
    T:<LABEL> - Table (.tbl and .xml files can be automatically converted)
    O:<LABEL> - Object (view the "NeXtMidas User's Guide" for details)

    U:<LABEL> - Untranslated string (<VALUE> not translated)
    _:<LABEL> - Unknown (same as D: for numbers, S: all others).

  This strong-typing nomenclature can be used in any NeXtMidas command that sets
  a results parameter with a label entered on the command line such as STATUS,
  IMPORT, ASK, MAXMIN, etc.

  When a result's name is strongly typed RESULTS will issue a warning and
  abort if <VALUE> cannot be converted to the given type.

  When displaying results parameters (no 2nd argument) typecasting can be
  used in two ways.  If the '*' is used in <LABEL>, then the specified type
  is used to further limit the search (e.g. RESULTS A:* will show all ASCII
  results, RESULTS N:* will show all numeric results, etc.).  If no '*'
  is used, the result (if found) is cast to the specified type before being
  assigned or displayed.  This is useful mostly with Control Tags (type T:).

Global Results
--------------
  If a macro needs to set a result in the global table that is not listed in a
  GLOBAL statement then the /GLOBAL switch will force the named result in there.
  Note that elements of a global table (like ENV.HWFILE) are inherently global
  so the /GLOBAL is not necessary.


RESULTS: CLONE -vs- REFERENCE
-----------------------------
  A result can be cloned (copied) such that the copy is stored in a separate
  memory location from the original. A change to the clone will not affect the
  original. When two variables need to refer to the same result a reference
  can be created such that a change using either reference variable changes
  the value seen by both. A results table example illustrates these
  relationships:

    nM> set origtable {x=1,y=2} (create a table and assign some values)
    nM> set table1 origtable    (create a reference to the original table)
    nM> set table2 ^origtable   (clone/copy the original table)
    nM> set table1.x 9          (modify x value in table 1)
    nM> res table1.x            (x=9 because table 1 value was modified)
    nM> res table2.x            (x=1 because the copy remains unchanged)
    nM> res origtable.x         (x=9 table1 references same memory as origtable)

Load and Save
-------------
  The /SAVE and /LOAD switches provide a mechanism for saving and loading
  results parameters and values to and from a file.  Either switch,
  if given a value (i.e. /SAVE=FILENAME), will use the file named FILENAME; if
  no name is specified, they will use the file RESULTS.TMP.  With the /SAVE
  switch, only the specified results in <LABEL> are written ('*' may be used
  as described above), and the resulting file is either a text file or a Blue
  file, depending on the extension specified. If running from within a macro,
  the result table entry for the macro itself will not be saved, since it is
  not a valid data type. If no extension is specified, the
  file is saved with a .tmp extension. The /LOAD switch loads results in
  the file to the results table in sequence.  However, System-use results
  (AUX, REG, OPT, and ENV) will not be overwritten. The primary
  value of the /LOAD mechanism is the ability to take a "snapshot" of your
  working environment before quitting a session and reload it later. See
  examples below.

Importing XML or Table files
----------------------------
NeXtMidas can import XML (.xml) or NeXtMidas table (.tbl) files into results
automatically.  A the result must be cast as a T: to indicate the presence of
a file (not a string with a period in it).  Since XML can support multiple
tags of the same name, duplicate names have '_<num>' prepended to them.

  nM> res t:tab nxm.sys.test.test_datalist_setup.tbl
or
  nM> res t:mytable nxm.sys.test.test_xml.xml
  nM> res mytable
    T: MYTABLE         = Table of 3 entries
    T:  TABLE_1        = Table of 0 entries
    T:  TABLE_2        = Table of 0 entries
    T:  TABLE_3        = Table of 0 entries

Escape Sequences Within Strings
-------------------------------
As of NeXtMidas 2.9.0, the macro language supports Java-style escape sequences,
i.e. a backslash ('\') followed by a special character or Unicode sequence.
For example:

  nM> res s:myStr "Plus-Minus sign: \u00b1"
  nM> res mystr
  18S: MYSTR           = Plus-Minus sign: ±

This behaviour can be disabled through the ENV IOOPTIONS:

  nM> env set iooptions +disableEscapeSequences

For more details see the ENV explain file.

Evaluating Numerical Expressions:
---------------------------------
RESULTS can evaluate simple numerical expressions prior to storing the result.
  nM> res x 1+1
  nM> res x
    L: X               = 2

Note that, other then parentheses, precedence rules are not followed, the
expression is evaluated left to right.
  nM> res x 1+1/2
  nM> res x
    L: X               = 1
  nM> res x 1+(1/2)
  nM> res x
    D: X               = 1.5


Examples:
  1.  Show local table values
        nM> res
        F: Y          = 6.6
        T: ENV        = Table of 28 entries
        T: G_STATUS   = Table of 6 entries
        D: MYVAL      = 123356.0
        T: OPT        = Table of 2 entries
        T: AUX        = Table of 14 entries
        T: REG        = Table of 2 entries
        T: RAM        = Table of 0 entries

  2.  Show all values in all tables
        nM> res/all
        <listing with all tables expanded - this can be quite long>

  3.  Show values in local table that start with FR
        nM> res FR*
        D: FREQ       = 9728.0
        T: FRANK      = Table of 3 entries

  4.  Show values in all tables that start with FR
        nM> res/all FR*
        D: FREQ       = 9728.0
        T: FRANK      = Table of 3 entries
        L:  A         = 1
        L:  B         = 2
        L:  C         = 3

  5.  Get the first element of the file fftdemo.prm.
        nM> res FILE(fftdemo.prm).data(0)
        CF: FILE(FFTDEMO.PRM).DATA(0) = (0.9778422,0.28689098)

  6.  Set the fourth element of the file mytest1000.tmp to "Hi"
        nM> res FILE(mytest1000.tmp).data(3) "Hi"

  7.  Get the second element of the file test3000.prm (record based) as a table.
        nM> res FILE(test3000.prm).dataTable(1)
          T: FILE(TEST3000).DATATABLE(1) = Table of 7 entries
         2A:  INPU           = DCR2B
         2A:  CONN           = F60OPP2
         2A:  OUTP           = F63IPP2
         2A:  USER           = AWD
         2A:  RESY           =
         2A:  TCIN           =
         2A:  CLOC           = I

  8.  Get the FF subrecord of the 3rd element of the file test6000.prm.
        nM> res FILE(test6000.prm).data(2,"FF")
        L: FILE(TEST6000.PRM).DATA(2,"FF") = 236

      Since NeXtMidas 2.7.0, you can also do this to get the FF subrecord.
        nM> res FILE(test6000.prm).getDataTable(2).FF
        L: FILE(TEST6000.PRM).GETDATATABLE(2,"FF") = 236

  9.  Set the FF subrecord of the 3nd element of the file my6000.tmp to 8175.
        nM> res FILE(my6000.tmp).data(1,"FF") 8175

  10. In-line SEDIT operation.
        nM> res STR SEDIT("a string",UPCASE)
        nM> res str
        S: STR        = A STRING

  11. Merge (join) two tables, keys on right overwrite the keys on the left.
        nM> res tab {X=5,Y=2}{X=1,Z=3}
        nM> res tab
        T: TAB        = Table of 3 entries
        L:  X         = 1
        L:  Y         = 2

  12. Type casting.
              DEFAULT        |         D:             |         S:
        ---------------------+------------------------+-------------------
        nM> res temp 7       | nM> res D:temp 7       | nM> res S:temp 7
        nM> res temp         | nM> res temp           | nM> res temp
        L: TEMP       = 7    | D: TEMP       = 7.0    | S: TEMP       = 7

  13. Saving results to a file.
       COMMAND                            FILE CREATED       CONTENTS
       -------------------------------------------------------------------
       nM> res/save                       results.tmp        Whole Results Table
       nM> res/save *                     results.tmp        Whole Results Table
       nM> res/save="home1"               home1.tmp          Whole Results Table
       nM> res/save=home1                 home1.tmp          Whole Results Table
       nM> res/save tab                   results.tmp        TAB results
       nM> res/save=mySave tab            mySave.tmp         TAB results
       nM> res/save=mySave.txt tab        mySave.txt         TAB Results
       nM> res/save=mySave.txt tab.foo    mySave.txt         TAB.FOO Results

  14. Loading the results table from a file.
     COMMAND                            ACTION
     ---------------------------------------------------------------------------
     nM> res/load                       Loads results.tmp
     nM> res/load="mySave"              Loads mySave.tmp
     nM> res/load="mySave.txt"          Loads mySave.txt
     nM> res/load=mySave.txt            Loads mySave.txt
     nM> res/load=mySave.txt TAB        Loads mySave.txt (TAB ignored)

     Note: System-use results (AUX, ENV, REG, OPT) are forbidden to be
           overwritten and so are ignored if found in the file.

  15. Using escape sequences. Note that \u00b1 gets translated to the
      plus-minus sign.
      nM> res s:myStr "Plus-Minus sign: \u00b1"
      nM> res mystr
      18S: MYSTR           = Plus-Minus sign: ±


  16. Get the count of the number of results that match a given filter.
      nM> res x1 1
      nM> res x2 "dog"

      nM> res/count=myCount x*
          L:MYCOUNT = 2

  17. Get the count from example 16, but also display the results:
     nM> res/count=myCount/verbose x*
         L: X1              = 1
        3S: X2              = dog
         L: MYCOUNT         = 2

  18. Get an individual value from a VD (Vector Double) data element.
     nM> res VX1 FILE(nxm.sys.dat.sv1.prm).data(60,"VEL").0
     nM> res VX1
       D: VX1             = 13.358262980277374


Switches:
  Scope:
    /GLOBAL    - Sets the result in the GLOBAL results table
    /PARENT    - Sets the result in the PARENT result table
    Note: If both /GLOBAL and /PARENT switches are present, /GLOBAL will
          override and a warning will be issued to the command line.

  Setting Results:
    /ADDROOT   - Automatically add roots of tables
    /FORCE     - Sets in a readonly table

  Displaying Results:
    /ALL         - Display all results parameters, expand tables as necessary
    /BIN         - Display a numeric result in binary format (same as /RADIX=2)
    /COUNT=<res> - Display and store a count of the number of results that match
                   a given filter (see example 16).      (Since NeXtMidas 3.1.0)
    /HEX         - Display a numeric result in hex format  (same as /RADIX=16)
    /LOAD=<fn>   - Load results from file created by /SAVE= into results table.
                   The default filename with just a state switch is
                   "results.tmp".
    /OCT         - Display a numeric result in octal format  (same as /RADIX=8)
    /RADIX=<n>   - Display a numeric result with the given radix (2,8,10,16)
    /RES=<res>   - Output to this result instead of the screen, if a radix is
                   given and the value is a number, the value stored will be a
                   string representing the value in the given radix
    /SAVE=<fn>   - Save specified results to the given file name.
                   The default filename with just a state switch is
                   "results.tmp".

See Also:  GLOBAL, REMOVE, SET, GET, INVOKE