ConvertBot: handles creation and display of results parameters

2020-04-27T22:05:02Z

handles creation and display of results parameters

New page

handles creation and display of results parameters
<pre>
<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

</pre>

[[Category:NXM_Explain]]

RESULTS - Revision history

ConvertBot: handles creation and display of results parameters