RESULTS
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