ICE Enterprises - User contributions [en]

ENDDO

2020-04-27T22:05:20Z

ConvertBot: end a DO block

end a DO block
<pre>
Each DO statement in a macro must be coupled with an ENDDO statement at
the end of the DO block.

SEE ALSO: DO, BREAK

</pre>

[[Category:NXM_Explain]]

POLYFIT

2020-04-27T22:05:20Z

ConvertBot: evaluates polynomial fit on data in a piecewise manner

evaluates polynomial fit on data in a piecewise manner
<pre>
<IN> - Type 1000/2000 format S# input file name.
<ORDER> - Order of polynomial [DEF=1]
<COEF> - Results label to receive coefficients
<OUT> - Output file name to receive fit coefficients.Type 2000 format SD.
<FIT> - Output file name to receive fit output. Type/Format of <IN>.
<ERR> - Output file name to receive error output. Type/Format of <IN>.

The <IN> file can be a type 1000 or 2000 file. If 1-D file, POLYFIT will fit
one curve to the entire file. If 2-D, POLYFIT will fit one curve to each frame
of the input file. The output files follow the input file type.

The internal algorithm normalizes the abscissa to be from 0 to 1 to prevent
floating point overflow errors when XSTART or XDELTA are large numbers. The
coefficients are transformed to the file's abscissa reference frame before
output.

All internal statistics and matrix transformations are computed in double
precision regardless of input data type.

Examples:

Switches: NONE

</pre>

[[Category:NXM_Explain]]

SAY

2020-04-27T22:05:19Z

ConvertBot: echoes a text line to the terminal

echoes a text line to the terminal
<pre>
<TEXT> - A formatable string with optional results substitution

This is used to print an informative string to the terminal - normally for
use in macros. <TEXT> will normally be surrounded with doubles quotes ("")
to preserve case and allow spaces. A typical string would have the form:

SAY "The bin ^NBIN frequency shift is ^FREQ Hz"

The trailing quote may be omitted. When executed, the strings preceded by
the caret (^) will be interpreted as results parameters, and assuming the
parameters NBIN and FREQ are defined as 5 and 5.6420 respectively, the user
will see:

The bin 5 frequency shift is 5.6420 Hz

Examples:
* nM> SAY "Hello"
Hello

* nM> SAY "The bin ^NBIN frequency shift is ^FREQ Hz"
The bin 5 frequency shift is 5.6420 Hz

* The /L=F switch can be used to repress the new line in a macro
startmacro
SAY/L=F "Running"
SAY/L=F "."
SAY/L=F "."
SAY/L=F "."
SAY "Done"
endmacro

Outputs the text:
Running...Done

Switches:
/L - Write a new line if true [DEF=TRUE]

See Also: INFO, WARN

</pre>

[[Category:NXM_Explain]]

Geogui

2020-04-27T22:05:19Z

ConvertBot: Demonstration macro of geographical plotting capability

Demonstration macro of geographical plotting capability
<pre>
GEOGUI <PORT> <REMOTE>

Displays a macro that demonstrates the useage of much of the plotting
capability of the NeXtMidas framework.

<PORT> NOT USED

<REMOTE> NOT USED

When executed an application frame will be shown that contains interactive
plots of the world, a line spectrum, an image, and a table. The application
is broken into three columns. The left hand column displays different menus
controlling the display of data and displaying the metadata for the world
plot. The center of the display contains a world plot on which different
features can be overlayed and a table containing metadata on the features
which can be displayed on the map. The right hand panel shows two different
styles of line plots and an image raster of a penny.

Menu behavior

- Mouse click on the title will expand/collapse the menu.

- Left clicking on the value of a menu entry will display a popup menu
containing the available values or a text entry field if the value is
unconstrained.

- Right/Left clicking on the circle between the menu label and its value
will cause the value to cycle through the available settings.

Map/Plot behavior

- Left mouse click in the window will cause geolocation features to change
according to where you click.

- Left mouse click and drag will cause a viewing box to be drawn. When the
mouse button is released, the map will zoom to display the selected area.

- Right mouse click will cause the map to revert to its "clean" state.

- Middle mouse click will cause a popup menu to be displayed which will
allow you to discover the properties of the map and all of its layers.

Table behavior

- Clicking in a sell will select that cell

- Clicking on a row or column header will select that row or column.

- Holding shift or control will allow you to perform multiple selections.

Messages:
None

Switches:
None

See Also: SD360

</pre>

[[Category:NXM_Explain]]

PLOT

2020-04-27T22:05:19Z

ConvertBot: Generic plotter for Midas files (or shared Layer objects)

Generic plotter for Midas files (or shared Layer objects)
<pre>
<file> - File(s) to plot (file1|file2|... for multiple)

Keyword Only Parameters: NOTE: These cannot be abbreviated. These keys are also
available with the SET/GET messages and/or the set/get methods.

[AUTOL] - autoscale length (in frames) (See [SCALE]) [DEF=8]
Supported by Layer1D, Layer2D, and LayerXY. Cannot be zero.
[AUTOM] - mask of layers to include in autoscaling, -1 for all. [DEF=2]
[AXIS] - axis mode = DEF,UNLAB,NUM,FRAME,TFrame,BFrame,TRFrame,BRFrame,
TLFrame,BLFrame,~Grid,~Show,Modify,~Gridfront,
~RotateVals,~AutoRotate
[BUTTONACTION] - Table to control what happens when a mouse button is pressed
(Since 3.5.2)
The table should be in the form:
{LMB=<act>,MMB=<act>,RMB=<act>}
Where <act> is one of the following:
Default - default action for button
None - do nothing
Menu - bring up menu (default for MMB)
Mark/Mark__Message - mark this location (default for LMB)
UnZoom - zoom out (default for RMB)
[C1,C2,CD] - set color min, max, and/or delta (Not Implemented)
[CM] - complex mode = Mag,Phase,Real,Imag,RnI,RvI,10Log,20Log,X,Y,Z
[CMAP] - (Layer2D, Layer1D for type 2000) Use predefined Color map =
GrayScale,Ramp,XRamp,Wheel,Terrain,Multi,T5Layer,MapLine,Grid,
Spectrum,XDatalist. [DEF=based on input file]
See MColor.colorMapList for full list. See also [NC] parameter.
[CNT] - controls mode = Click|Motion|Drag|NONE [DEF=Click]
Sets the mouse interaction messages to send to the macro.
[DRANGEUNITS] - Units to use for the dRange [READOUT] display value. (M,KM,NMI)
[FEATURES] - table of features to set on plot class
[FILE] - Input files (FILE1|FILE2...)
[LAYER] - table of default parameters for all layers. This can be used
to persist things like colormaps from one file to the next.
Use {TAG=mytagname} to change the layer name, otherwise the
root file name is used.
[MAXRANGE] - sets the maximum autoscale range (usually Y values) [DEF=100]
[MINRANGE] - sets the minimum autoscale range (usually Y values) [DEF=50]
[MIMIC] - sets the IDs of the plotters that any PAN/ZOOM messages should
be forwarded to such that they will mimic this PLOT and
PAN/ZOOM along with any changes to this plot; note that if
bi-directional behavior is desired both plots need to be
passed MIMIC= that point to the other; it is OK if the other
PLOT has not been defined yet as the ID is not used until the
first message is sent (Since NeXtMidas 3.5.4)
[NC] - (Layer2D, Layer1D for type 2000) Number of colors to use for
[CMAP] parameter [DEF=32].
[OPTIONS] - MPlot options (BStore|Axes|Mark|Contrast|CrossHairs|XCut|YCut|
ZCut|StillZoom|BlockZoom|Pager|All|Auto2D|
DBuffer|NearInt|DragZoom)
[RANGE] - sets the autoscale (max) range for the plot (and the range below
automax mode). Same as setting both SCALE=+MaxRange and
MAXRANGE=[value of RANGE]
[READOUT] - specs readout, use | as separator, i.e. READOUT=Show|onTitle
( Show|onStatus|onAxis|onTitle|
X|dX|1/X|iX|Y|dY|dY/dX|iY|Z|dZ|dZ/dX|iZ|T|dT|1/T|1/dT|dRange|
extPrec|Index|DMS|Units|View|DateString|Scientific|Azimuth)
(Macro mode default=Show|onStatus|onTitle|X|dX|Y|dY|dRange|
View|Scientific; Interactive mode default +onAxis)
[SCALE] - autoscale= AutoMin|AutoMax|MinRange|MaxRange|
MinZRange|MaxZRange|NoAverage|ExpandOnly
NOTE: Autoscaling uses the min/max exponential (sliding)
averages of [AUTOL] frames in the [AUTOM] layer(s),
unless NoAverage (Since 3.3.3) is set, then it will use
the actual min/max over [AUTOL] frames.
For TYPE=LINE: min sets y1, max sets y2 (y-axis)
For TYPE=RASTER: min sets z1, max sets z2 (color range)
AutoMin - autoscale the min
AutoMax - autoscale the max
MinRange - bound autoscale of max within a range of
(min + [MINRANGE])
MinRange - bound autoscale of min within a range of
(max - [MAXRANGE])
MinRange|MaxRange - bound autoscale of min within a range of
1. (max - [MAXRANGE]), then to a range of
2. (max - [MINRANGE])
ExpandOnly - only expand min/max (no shrink) (Since 3.4.2)
[SETUP] - table of configuration parameters to be applied to the plot
[TYPE] - set plot mode = LINE,RASTER,CONTOUR,MESH,POINT,DOT
[VIEW] - Change the plot view/layout, such as axis direction, etc.
e.g. YX swaps X and Y axes; XiY reverses direction of Y axis.
Options: XY,iXY,XiY,iXiY,YX,iYX,YiX,iYiX,
XYZ,Polar,LatLon,Mercator,Geodetic
[X1,X2,XD,XU] - set X min, max, delta, and/or units
[Y1,Y2,YD,YU] - set Y min, max, delta, and/or units
[Z1,Z2,ZD,ZU] - set Z min, max, delta, and/or units
[ZOOMTO] - open the plot zoomed to a particular portion of the plot. E.g:
nM> plot apenny.prm ZOOMTO={x1=50,x2=100,y1=0,y2=100}

This routine plots multiple files or layers in both static and real-time modes.
A file/pipe will have its I/O handled by this routine. A layer must provide its
own I/O and tell this routine when to update. The following is a short list of
*some* of the layers supported (see the LAYER explain file for details):

1000 - a type 1000 file
2000 - a type 2000 x/y grid
3000 - a non-homogeneous file with subrecords specified by
qualifiers in the form {Layer={LT=XY,X=ABSC,Y=ORD}}.
5000 - a type 5000 file with a vector component of interest
qualifier {NAME=XXX} specifies component other than all
1998 - a polygon file specifying 2 or 3 dimensions (filled)
1999 - a line segment file specifying 2 or 3 dimensions

- Plot supports markers and annotations. - See FEATURE.
- Plot supports non-file based layers - See LAYER.
- Plot supports SHAPE (.shp) files. - See the examples below.
- Plot supports NGA image files. - See the MAP option tree.
- Plot supports IMAGE (gif,tif,jpg,png,xpm,pdf) files.

Scaling:
Plot autoscaling can be set or adjusted in many ways:
0. Autoscaling of the min and max is on by default.
1. If a user specifies an X, Y or Z minimum value on the plot command line,
then the plot will not automatically scale minimum values.
2. Likewise, setting a max value will turn off autoscaling of max values.
3. Setting the range on the command line (via the "RANGE"=<range> parameter)
will set the scale to include scaling by Max data range values.
4. A user can set the autoscale options on the plot command line using the
"SCALE=<scale>" parameter.
5. Scaling can be done on an active plot by using the Scale menu described
in the Menus section below.
6. Also on an active plot, users can invoke either the setScale(String) or
the setScale(int) methods.
a. The setScale(int) method accepts values or groups of int values
corresponding to the items listed in [SCALE], above.
b. The method setScale(String) takes in String forms of those values and
includes, for convenience, several common group designations.
These group designations are:
"FIX" : De-selects autoscaling (uses current range)
"FULL" : Sets to "AUTOMIN|AUTOMAX"
"AUTO" : Same as "FULL" (Sets to "AUTOMIN|AUTOMAX")
"RANGE" : Sets to "MINRANGE|MAXRANGE".
As with many methods that relates to setting mask values, users can
use the word "NONE" to de-select all current values.

Menus:
Plot menus may be accessed by using the middle-mouse button (MMB). An MMB can
be simulated on a two-button mouse by briefly holding down the right-mouse
button. Menu selections made with the left-mouse button (LMB) and are not
"sticky" (the menu goes away after selection). Menu selections made using the
MMB are sticky. The following is a summary of the options available through
plot menus:

Files -> Addnew / Reread / [plot file #1,...]
Layers -> [same as Legend]
Features -> Load / Save / AddNew
View -> YX / iYX / YiX / iYiX / XY / iXY / XiY / iXiY / XYZ /
Polar / LatLon / Mercator / Geodetic
Mode -> Mag / Phase / Real / Imag / RnI / RvI / 10Log / 20Log
Scale -> Flags: AutoMin,AutoMax,MinRange,MaxRange,MinZRange,MaxZRange,
NoAverage
/ XMin / YMin / ZMin / MinRange / ScaleAvg / XMax / YMax /
ZMax / MaxRange
Axis -> Default / Unlabeled / Numbered / Frame / TFrame / BFrame /
TRFrame / BRFrame / TLFrame / ~Grid / ~Show / Modify /
~Gridfront / ~RotateVals / ~AutoRotate
Readout -> Show / onStatus / onAxis / onTitle / X / dX / 1/X / iX / Y /
dY /dY/dX / iY / Z / dZ / dZ/dX / iZ / T / dT / 1/T / 1/dT/
dRange / ExtPrec / Index / DMS / Units / View /
DateString / Scientific / Azimuth / dRangeUnits>
dRangeUnits -> M / KM / NMI
Legend -> [display options for each layer...]
Options -> BStore / Axes / Mark / Contrast / CrossHairs / XCut / YCut /
ZCut / StillZoom / BlockZoom / Pager / All / Auto2D /
DBuffer / NearInt / DragZoom
Query -> [PLOT status information]
Export -> [ExportImage parameters and options]
More -> Window / Controls / Animate / Theme / Precision / Type /
~Dots / Locate / GoToLocation
Exit

Menu options presented with a tilde (~) in front are toggle options. For
example, the menu selection Plot -> Axis -> ~Show toggles view of the X and Y
axes.

Menu options followed by a greater than (>) lead to further options, such as
popup menus. For example, the Readout selection dRangeUnits> pops up a menu
asking the user to select the unit type (M, KM, or NMI).

Plot Mode Options:
NeXtMidas plots support the rendering of data several ways. Typically, the
data values are treated as REAL numbers and plotted as such. Users are able
to change the data representation on the command line using the cm=<mode>
argument or via the Menus as depicted above.

Note: not all data can be rendered in all modes, or the rendering change may
have no effect.

Axis Menu Options:
Default - The default axis layout. Includes Axis lines and labeled tics
Unlabeled - The axis does not includes labels
Numbered - Axis has numbers and tics
Frame - Axis has tics only
TFrame - Show axis values at top
BFrame - Show axis values at bottom
TRFrame - Show axis values at top and right
BRFrame - Show axis values at bottom and right
TLFrame - Show axis values at top and left
~Grid - Toggle showing grid
~Show - Toggle showing axis
Modify - Brings up axis configure menu
~GridFront - Place grid in front of data
~RotateVals - Draw vertically the labels on the Y axis (since 3.1.0)
~AutoRotate - Rotate if necessary labels on the Y axis (since 3.1.0)

Options:
BStore - Put drawn data or features into a backing store for faster
refreshes. Not recommended for moving features or realtime
(piped) data.
Axes - Show axes
Mark - Show marks
Contrast - Adjust contrast (slightly darkens plot)
CrossHairs - Display cross hairs at the mouse location
XCut - Creates a "cut" of the X-Axis cross-section at the mouse position
YCut - Creates a "cut" of the Y-Axis cross-section at the mouse position
ZCut - TBD
StillZoom - Use still zoom
BlockZoom - Use block zoom
Pager - Use pager
All - Use all available data
Auto2D - Auto Geodetic To Mercator for speed where appropriate
DBuffer - Simulate Double BUffering (helps eliminate flicker)
NearInt - Use nearest integral scaling
DragZoom - Allow zooming by RMB dragging top-right corner of plot

Messages:
NAME - (IN/OUT) DESCRIPTION
-----------------------------------------------------------------------
BUTTON - (IN) (Internal Message:) Mouse click.
CLOSEFILE - (IN) Close a layer/file. Data=<TAG name>
CONTROLS - (IN) Set the controls mask: ONCLICK, ONMOTION.
INFO=<controls mask>
DBLCLICKZOOM - (IN) Disable or enable zooming in/out through the use of
double-clicking the mouse. (Since NeXtMidas 2.7.2)
DATA=TRUE,FALSE
NOTE: When enabled, this can cause confusion if Left
Mouse Clicks or Right Mouse Clicks are already
mapped by the user's application.
DRAG - (IN) (Internal Message:) Mouse drag.
DRAGBOX - (OUT) Indicates user has drawn a dragbox (a Shift+Drag).
(e.g. macro test %test_box)
DROPDATA - (OUT) Indicates user has executed a drag and drop.
DRANGEUNITS - (IN) Sets the dRange Units
EXIT - (IN) Exit plot (if EXIT_MESSAGE enabled)
EXPORTIMAGE - (IN) Creates and saves the image. INPUT DATA=<FileName>.<ext>
Image type is based on file extension.
FEATURE - (??) TBE
FOCUS - (IN) No action taken if plot receives this message.
GOTOLOCATION - (IN) Marks or Zooms to a given location. Message data is a
table with:
XVAL - X coordinate (or center point)
YVAL - Y coordinate (or center point)
RADIUS - Zoom radius (same units as plot)
FLAGS - Type of action (|MarkLocation|Zoom|)
HOLDREFRESH - (IN) Prevent refreshes, allowing the user to make many changes
before allowing refreshes again, thus drawing all
changes at once. DATA=<what to hold>
DATA=NONE (Allow all refreshes) [DEF]
DATA=[~,+,-]FEATURE (Hold refreshes on Features only)
DATA=[~,+,-]LAYER (Hold Layer refreshes)
DATA=ALL (Hold Feature AND Layer refreshes)
KEYPRESS - (IN) (Internal Message:) Keyboard interaction.
KEYRELEASE - (IN) (Internal Message:) Keyboard interaction.
LAYER - (IN) (Internal Message:) Brings up the layer configuration
menu. DATA=[LayerName]
LOADFEATURESFROMFILE - (IN) Loads features from a file.
MARK - (OUT) Indicates current pointer position. [CNT] controls when
MARK message will be sent. INFO=[0=Motion,1=Click/Drag]
MENU - (IN) (Internal Message:) Brings up the plot menu.
MODIFY - (OUT) (Internal Message:) Used with RMIF connections.
MORE - (IN) (Internal Message:) Brings up the more menu.
MOUSEWHEELZOOM - (IN) Disable or Enable zooming in/out through the use of the
mouse scroll wheel. (Since NeXtMidas 2.7.2)
DATA=TRUE,FALSE
NOFILE - (IN) (Not Implemented)
OPENFILE - (IN) Open a layer/file. DATA=<filename>. Unlike REREAD
message this processes the file header information. If
info=-1, clears old files first. To set additional
arguments or to update the viewable area of the plot
when opening, use the optional message field
QUALS=<table>. See the example for using QUALS with
OPENFILE in EXAMPLES for more details.
PANOBS - (IN) Pan the observer position.
PANX - (IN) Pan in X dimension only.
PANXY - (IN) Pan in both X and Y dimensions.
PANY - (IN) Pan in Y dimension only.
PANTW - (IN) Pan to specified time window (start,len)
PLOT - (??) TBE
POINTER - (IN) Set the current pointer position.
PRECISION - (IN) Set the readout precision (# places after decimal).
REFRESH - (IN) Perform a FULL refresh (Drawable.FULL)
REPARENT - (IN) MPLOT.reParent is invoked with data
REREAD - (IN) REREAD the file, does not reread the header
RESIZE - (IN) (Internal Message:) Resizes plot.
SAVEFEATURESTOFILE - (IN) Saves features to a file.
SHOW - (IN) (Internal Message:) Shows or hides the plot.
INFO=[1=Show,0=Hide,-1=Iconify]
SHOWN - (IN) (Internal Message:) Sets plot visibility status.
THEME - (IN) Change the THEME ("MORE -> Theme" menu)
Data=Desktop,Default,WoB,GoB,BoW,Browser,Gear1,Gear2,
Gear3,Gear4,Nak.
TIME - (IN) Set the time for animated displays. Same as using
MPLOT.setTime(String) method.
TYPE - (IN) Set Type as per [TYPE] above
UNZOOM - (I/O) Unzoom back one zoom level.
Output Data=nxm.sys.libg.DragBox (as of NeXtMidas 2.5.0)
WINDOW - (IN) (Internal Message:) Sets window status.
XCUT - (IN) Create a cut of the X-Axis cross-section
DATA={IX=<xpos>,IY=<ypos>}
YCUT - (IN) Create a cut of the Y-Axis cross-section
DATA={IX=<xpos>,IY=<ypos>}
ZOOM - (I/O) Zoom one level to the X1,X2,Y1,Y2 real world coordinates.
INPUT DATA={X1=<x1>,X2=<x2>,Y1=<y1>,Y2=<y2>} or
={XMIN=<x1>,XMAX=<x2>,YMIN=<y1>,YMAX=<y2> or
=nxm.sys.libg.DragBox
OUTPUT DATA=<same as input data> (macro initiated) or
=nxm.sys.libg.DragBox (user initiated)
ZOOMIN - (I/O) Zoom in on a plot by a given percentage (0 < % < 1)
INPUT DATA=<float> [DEF=0.5f], QUALS={PERCENT=<float>}
Examples:
DATA=0.1 (Zoom in 10%)
DATA=0.9 (Zoom in 90%)
DATA=0.5 (Zoom in 50%) [DEF]
OUTPUT DATA={XMIN=<x1>,XMAX=<x2>,YMIN=<y1>,YMAX=<y2>}
QUALS={PERCENT=0.5}
ZOOMOUT - (I/O) Zoom out on a plot by a given percentage (0 < % < 1) or
all the way out (-1)
INPUT DATA=<float> [DEF=0.5f], QUALS={PERCENT=<float>}
Examples:
DATA=0.1 (Zoom out 10%)
DATA=0.9 (Zoom out 90%)
DATA=0.5 (Zoom out 50%) [DEF]
DATA=-1 (Zoom all the way out)
OUTPUT DATA={XMIN=<x1>,XMAX=<x2>,YMIN=<y1>,YMAX=<y2>}
QUALS={PERCENT=0.5}
ZOOMX - (I/O) Same as ZOOM for X only
ZOOMY - (I/O) Same as ZOOM for Y only

NOTE 1: Some messages only support passing because a way to implement
their data portion has not yet been implemented.

NOTE 2: There is an inherent delay when using the message command with the
function SEND, since the message is put onto the plot message queue
and waits there for plot to retrieve it. Therefore, the user should
not update any values on the plot until the plot has had time to
process the message. An alternative is to use SENDW or SENDX. See
Message explain file for details on their use.

NOTE 3: Messages are intended to be processed and executed by the PLOT thread,
although it is possible to call plot.processMessage directly via an
INVOKE or through Swing EDT interaction (such as mouse interaction).
Since 3.1.1, PLOT will re-queue most messages that are not on the
PLOT thread in order to avoid possible thread collision issues. For
performance reasons, the PAINT, POINTER, and DRAG messages are
excluded from this behavior.

NOTE 4: The original MouseEvent, generated by a user interacting with the Plot,
is saved in a table in the "quals" field of the Plot Message under the
key ORIG_MSG_DATA. (Since 3.5.4)

Examples:
1. Axis and grid options:

Plot a Layer2D file with a grid in the background using a 3-D view.
nM> plot alaska.prm axis=grid view=xyz

Plot a Layer2D file with a grid in the foreground using a 3-D view.
nM> plot alaska.prm axis=grid|gridfront view=xyz

Toggle the appearance of the axis (turn it off).
nM> plot fftdemo.prm axis=show

Rotate the Y axis labels (draw the text vertically)
nM> plot fftdemo.prm axis=+rotateVals

Disable the buffer that is added to axis values
nM> plot/axisBuffer=0 fftdemo.prm

Increase the size of the axis buffer
nM plot/axisBuffer=12 fftdemo.prm

2. Change the default color attribute for all layers.
nM> plot/bg fftdemo.prm layer={color=red}
nM> mess FUNC=send ID=plot NAME=openfile INFO=-1 DATA=fftdemo.prm
NOTE: Color is still red
NOTE: The INFO=-1 flags plot to close all current files.

3. Override the units settings for the plot.
nM> plot/bg/id=myplot fftdemo.prm
nM> set reg.myplot.xUnits 1
nM> set reg.myplot.yUnits 3

4. Override the symbol settings for a layer.
nM> plot world|cities{LAYER={SYMBOL=tri,SymbolSize=8,SymbolFill=on}}
or
nM> plot world|cities{LAYER={SYMBOL=square,SymbolFill=off,COLOR=red}}

See the FEATURE explain file for details on the symbols and symbol settings
available.

5. Display x Units in MHz when DataFile units are Hz by default:
nM> plot/bg/id=myplot/xmult=6 fftdemo.prm
or
nM> set reg.myplot.setxmult 6

6. Turn AutoSelect on for a LayerT5 layer so that when a user clicks near a
point the name of the point is displayed.
nM> plot world.prm|cities.prm{Layer={AutoSelectEnable="CLICK",&
AutoSelectMode="GreatArc",&
AutoSelectRange="750000.0"}}
7. Have a default color for a file
nM> plot/bg/id=plotid LAYER={COLOR=RED}
nM> message FUNC=SEND ID=PLOTID NAME=OPENFILE INFO=-1 DATA=fftdemo.prm
or for type 2000 files
nM> plot/bg/id=plotid LAYER={COLORMAP=XRAMP}
nM> message FUNC=SEND ID=PLOTID NAME=OPENFILE INFO=-1 DATA=apenny.prm

8. Plot a KML file and set the MAX Image Icon Size for non-zoomed icons to 10
and the blending ratio for blending (tinting) colors in image Icons.
nM> plot world.shp|kmlSamples.kml{LAYER={IconSize=10,
ColorBlendRatio=.9}} view=geo

9. Plot a KML file and do not display any labels for points.
nM> plot world.shp|kmlSamples.kml{LAYER={SHOWLABEL=FALSE}} view=geo

10. Plot a KML file and position the point label above the point Icon.
nM> plot world.shp|kmlSamples.kml{LAYER={LABELPOS=TOP}} view=geo

11. Do all painting in the SWING thread (EDT)
nM> env set graphics SWING

12. Let plots draw outside of the SWING thread
nM> env set graphics SWING|REALTIME

13. Plot a map and set the Readout to display ranges in Nautical Miles
nM> plot world.shp dRangeUnits=NMI

14. Plot a 1D file that has a very large Axis START value using /INDEX
nM> wave temp.tmp start=1e30
nM> plot/index temp.tmp

15. Zoom in on a plot by 90% then zoom all the way out
nM> plot world.prm /bg
nM> message FUNC=sendw ID=PLOT NAME=ZOOMIN DATA=.9
nM> message FUNC=sendw ID=PLOT NAME=ZOOMOUT DATA=-1

16. Zoom in / out on a plot using keyboard shortcuts:
nM> plot world.prm
<press '+' keys on keyboard or number pad> (Zoom in %50)
<press '-' keys on keyboard or number pad> (Zoom out %50)

Note: These shortcuts can be re-mapped in ENV.KEYMAP.PLOT. See
$NMROOT/nxm/sys/cfg/keyMap.tbl for example.

17. Plot two files with different Z MIN/MAX ranges with z scaling by the layer
nM> plot/scalez=layer temp.tmp|apenny.prm{LAYER={ZMIN=-50,ZMAX=100}}

18. Open a file and immediately set the left Outer Limit (Bounds) using QUALS
nM> message send idplot name=openfile data="world.shp" &
quals={outerlimits={x1=-100}}

19. Create a XCut plot from a point on a Layer2D plot (message)
nM> plot/id=plotid apenny.prm /bg
nM> message func=sendw id=plotid name="XCUT" data={IX=200,IY=200}

20. Create a XCut of the current mouse position (keyboard shortcut)
nM> plot apenny.prm
Hover mouse where you want the cut and press X

21. Display the Azimuth from a clicked point to the current mouse position
in the readout.
nM> plot world.prm READOUT="+azimuth"

22. Reverse the current colormap on the apenny.prm plotted file
invoke ,, reg.plotid.layers.apenny.reverseColorMap()

23. Reverse a colormap when initially plotting
nM> plot apenny.prm /reverseColors

24. Reverse the colormap on a single layer only when initially plotting
nM> plot world.shp{LAYER={ReverseColormap="TRUE"}}|cities.prm

25. Plot type 1000 file without connecting lines by setting the Layer's line
type to "Symbol" and to make the points "Diamond" symbols.
nM> plot fftdemo.prm{LAYER={Type="Symbol",Symbol="Diamond"}}

26. Set the Max Range of Z (Data) values to be within 50 units of the
file data max value:
nM> plot apenny scale=MAXZRANGE maxrange=50

27. Invert the colormap (creating a photo negative effect)
nM> plot/id=plotid apenny.prm{LAYER={InvertColormap="TRUE"}} /bg
or using invoke after plot is already running:
nM> invoke ,, reg.plotid.layers.apenny.invertColorMap()

28. Set the mouse cursor appearance to be the wait cursor.
nM> set reg.plot.cursor "WAIT"
... do something or wait for something ...
nM> set reg.plot.cursor "DEFAULT"

29. Zoom in to a portion of the plot when the plot is opened.
nM> plot apenny.prm ZOOMTO={x1=50,x2=100,y1=0,y2=100}

30. Plot a type 2000 file with multiple lines in "line" mode
and use the /LPS switch to tell NeXtMidas to compute the
data buffer size of the file.
nM> plot alaska.prm type=line /lps=-1

31. Create a plot with a LayerGeo and set the reference time for the
StateVectors in the LayerGeo plot from within a macro:
startmacro
...
timex now sod=mySOD
plot/id=plot1 world
layer geoLayer {NAME=GL,SVA=sv1.prm,SVB=sv2.prm,...} plot1
set geoLayer.timeCode mySOD
...
endmacro

32. Create a plot with a LayerGeo and set the timecode (J1950) for the
StateVectors in the LayerGeo plot from within a macro:
startmacro
...
timex now sod=mySOD
calc myEpoch now 300 - ! 5 minutes ago
plot/id=plot1 world
layer geoLayer {NAME=GL,SVA=sv1.prm,SVB=sv2.prm,...} plot1
set geoLayer.timeCode myEpoch
...
endmacro

33. Create a plot that updates a RESULT named "cfreq" with the Y value of
the current mouse position whenever the mouse is clicked:
nM> plot/xcnt=click/mtag={y="cfeq"} nxm.sys.dat.sinewave

34. Save/export contents of the PLOT to an image file.
nM> plot/bg/id=plotid world
nM> message FUNC=SEND ID=PLOTID NAME=EXPORTIMAGE DATA=myplotimage.png

35. Change the default units labels on the X axis to custom text:
nM> plot/bg/id=plot1 sinewave
nM> set reg.plot1.XAxisLabel "Puppies"

36. Change the custom label on the X axis back to default text:
nM> set reg.plot1.XAxisLabel ""

37. Open a new file and pass in the /ALL argument in order to show all the
data in the plot area. (Since NeXtMidas 3.3.1)
nM> message send plot1 name="OPENFILE" info=-1 &
data=myfile quals={"/ALL=true"}

38. Hiding/showing a layer:
nM> plot/bg/id=plotid world.prm|cities.prm
nM> set reg.plotid.layers.cities.enable -GLOBAL ! hide cities layer
nM> set reg.plotid.layers.cities.enable +GLOBAL ! show cities layer
nM> set reg.plotid.layers.cities.enable ~GLOBAL ! toogle layer visibility
nM> invoke ,, reg.plotid.layers.cities.toggle ! toggle layer visibility

Using dRange and Azimuth Readout Options (LatLon and Mercator Views Only)
========================================================
The dRange and Azimuth readout options give the user the distance and
direction between a mouse click location and the current mouse pointer.
The default readout includes dRange but Azimuth must be enabled by the
user. The units of measurement for the dRange is meters by default but
can be set to kilometers or nautical miles.

Holding Graphical Refreshes on Features and Layers
========================================================
In NeXtMidas 2.7.2, enhancements were made to allow users to suspend
graphical refreshes on entire plots or just the Features on the plots. This
was expanded in 2.7.4 to allow users to hold refreshes on just the Layers
while still allowing Feature refreshes to continue.

The typical use of holding refreshes is when a user is processing a large
amount of updates in a short amount of time and does not want or need to
draw each update.

For detailed example see $NMROOT/nxm/sys/test/test_plot_hold_refreshes.mm

NOTE: In order to avoid unnecessary refreshes, when re-allowing refreshes
on Layers, NeXtMidas does NOT automatically refresh the plot. It is up to
the user to do this (if needed).

ZOOMing and Adjusting the Viewable Area of a Plot
========================================================
Plot keeps track of and applies user bounds changes as they occur.
This allows the user to set ZOOM boundaries (as well as standard x1=, x2=,
y1=, etc boundaries) before actually having data. The QUALS field of some
MESSAGEs was expanded to allow for passing in outer limits or viewport
limits (current view) using the syntax QUALS={OUTERLIMITS={X1=,X2=,Y1=,
Y2=,Z1=,Z2=},VIEWLIMITS={X1=,X2=,Y1=, Y2=,Z1=,Z2=}}. See the example in
the example section. Since 3.1.0, users can substitute XMIN, XMAX, YMIN,
YMAX, ZMIN, and ZMAX for X1, X2, Y1, Y2, Z1, and Z2, respectively.

In NeXtMidas 2.9.1, the ZOOMTO= keyword only parameter was added to allow
users to zoom in on a plot when they initially open it.

ZOOMIN:
ZOOMIN allows a user to quickly zoom in on a plot without the need for
dragging a box or sending a message. To ZOOMIN using the keyboard, simply
press the '+' key (there is no need to hold down SHIFT). This will zoom
in the current view by the default (currently 50%). If /dblclickzoom is
enabled, double-clicking with the left mouse button will re-center the
plot on the location of the double-click and then execute a ZOOMIN.
Finally, rotating the mouse scroll wheel forward will execute one ZOOMIN
per notch.

ZOOMOUT:
ZOOMOUT allows a user to quickly zoom out on a plot without the need for
dragging a box or sending a message. To ZOOMOUT using the keyboard, simply
press the '-' key. This will zoom out the current view by the default
(currently 50%). If /dblclickzoom is enabled, double-clicking with the
right mouse button will re-center the plot on the location of the
double-click and then execute a ZOOMOUT. Finally, rotating the mouse
scroll wheel backward will execute one ZOOMOUT per notch.

PAMNXY:
PANXY allows a user to quickly shift the viewable area of a plot. To
PANXY, simply press the arrow (left, right, up, down) key of the direction
you wish to shift. This will move the viewable area by the default pan
view adjustment (currently 10%).

Pressing HOME (left), END (right), PAGE UP, or PAGE DOWN
will adjust the view by a greater percentage (currently 50%).

You can also click and drag the small scrollbar that appears when zoomed
in or press and hold the Middle Mouse Button and drag the mouse to pan.

NOTE 1: Keyboard shortcut keys can be remapped using the environment
variable KEYMAP={PLOT={<TABLE>}}

NOTE 2: Double-Click ZOOMIN/ZOOMOUT can be enabled/disabled with the switch
/DBLCLICKZOOM=TRUE,FALSE.

NOTE 3: Mouse scroll wheel ZOOMIN/ZOOMOUT can be disabled with the switch
/MOUSEWHEELZOOM=FALSE, which is the current default.

NOTE 4: ZOOMIN/ZOOMOUT from the keyboard, message, or mouse does not use
the stored image ZOOMs (history), therefore the normal limitation
of fifteen ZOOM levels does not apply. Thus, ZOOMOUTs will
execute a redraw.

NOTE 5: In addition to the keyboard/mouse shortcuts, ZOOMIN/ZOOMOUT/
PANXY can be accomplished using messages, which allows the user
to use a different percentage for the action. See messages above for
details.

Plotting KML files
========================
In NeXtMidas, KML files are plotted like other files. However, since the
representation (Mark-up) of the data is handled in the KML file itself via
element tags and attributes, there are no input arguments for items such as
colors, fonts, etc.

NeXtMidas recognizes the .kml extension on the file and parses it using its
KML parser, which uses the Java SAX XML parser. Mal-formed files will throw
exceptions as in XML.

**NOTE**: In the JAVA SAX parser, ending element tag names are case
sensitive relative to the starting element tag. For example:

<folder> ... </folder> CORRECT
<FOLDER> ... </FOLDER> CORRECT
<Folder> ... </Folder> CORRECT
<folder> ... </Folder> - WRONG -

The following plots the drawable objects in a KML file on a globe:

nM> plot world.shp|nxm.sys.test.kmlSamples.kml view=geo

Note: The above example file requires an Internet connection to properly
display the Ground Overlay and Image Icons.

NeXtMidas allows the user to configure several items not specified in the
KML specification:
ALLOWPOPUPS - Boolean - Whether or not to show popups for KML points
COLORBLENDRATIO - float - Ratio (0 to 1.0) to blend (tint) an image icon
FORCEREFRESH - boolean - Ignore the modified date on a linked file.
(see details below).
ICONSIZE - int - Max allowable size of (non-zoomed) Image Icons
ICONZOOMSIZE - int - Max allowable size of (zoomed) Image Icons
LABELPOS - String - Where to position the labels for points.
Allowable settings:
TOP - Centered above the icon
TOPR - Text begins near the top right
BOTTOM - Centered below the icon
BOTTOMR - Text begins near bottom right
RIGHT - Text begins to the right of icon
SHOWLABEL - Boolean - Whether or not to display labels for points.

Without FORCEREFRESH being set to TRUE, LayerKML will ignore (not plot)
any network linked file that has already been plotted if it has not been
modified, regardless of the specified refresh interval. This is done to
avoid "blinking" displays from the refresh and to conserve cpu. The flag
FORCEREFRESH is intended to be used when the network linked file is a cgi-
script and can generate new data without the script itself changing.

For more information, see the JavaDocs for LayerKML.java and the Google
online reference (for KML structure).

Plotting type 3000 files
========================
A non-homogeneous file is plotted X vs. Y where the axis is specified by:

nM> plot file3000{Layer={LAYERTYPE=XY,X=LAT,Y=LON}}
or
nM> plot file3000{Layer={LT=XY,X=LAT,Y=LON}}

where LT or LAYERTYPE represents the Layer Type. The layer type may be a
full package name (i.e. nxm.sys.libg.Layer1D) or the layer suffix (i.e. 1D,
2D, XY,...) if the layer named Layer[suffix] and is located in nxm.sys.libg.

Type 3000 files that store multiple columns of data can be plotted using
LayerMulti:
nM> plot testxy3000.prm{Layer={LT="Multi",COLUMNS="*"}}
or
nM> plot testxy3000.prm{Layer={LT="Multi",COLUMNS="ORD|ORD2|ORD3"}}

Plotting type 5000 files
========================
To plot a cone flag file clipped at a plane vertical to the point (the POS
field in the file) on the Earth's surface (this is what X-Midas does)
nM> plot world.prm|coneflags5000.prm{layer={flags=CONEFLAGVERT}}

To plot a cone flag file along the Earth's surface, extending to the horizon
nM> plot world.prm|coneflags5000.prm

Plotting type 6000 files
========================
These types of files are also non-homogeneous and can be treated almost
exactly like a type 3000. In fact, type 6000 files are merely extensions of
type 3000 files that allow longer record names and more than 26 subrecords.

For example, a Type 6000 file with columns "LON" and "LAT" can be plotted
using the following syntax:

nM> plot testfile6000.prm{LAYER={LT="Scatter",X="LON",Y="LAT"}

Plotting SHAPE (.shp) files
===========================
To plot a SHAPE file:
nM> plot world.shp

If the SHAPE file has a companion file (.dbf) which contains the country
name (here indicated by NAME), the following allows the country name to be
displayed in the readout.
nM> plot world.shp{LAYER={LABEL=NAME}}

The layer used by shape files (see nxm.sys.libg.LayerShape) can use one of
the following algorithms to determine how to color the shapes in the file:
Default - Uses the default algorithm (currently MinAdj, but may change
between releases).
Mono - Monochrome, all shapes have the same color. This was the default
in NeXtMidas 2.0.0 and earlier when a single COLOR was given.
NOTE: The Monochrome color will be the first color listed in
the colormap. To change the mono color, change the first color
in the colormap.
Mod5 - The index of the color (in the color map) to use for a shape is
equal to the shape's index MOD 5. This was the default in
NeXtMidas 2.0.0 and earlier. (The color map must have 5 or more
colors in it for this to work.)
ModN - Same as Mod5 but uses all available colors in the color map.
MinAdj - Minimizes the number of adjacent shapes that have the same color
(works best with five or more colors in the color map). This
algorithm considers two shapes to be adjacent if they share
a common point. (Note: This is the slowest option, but has the
best results, by far.) If the file is an ARC or POINT file then
this defaults to using the ModN algorithm to improve speed.
OnSelect- Colors the selected shape in one color while other items use
a default color. When the world.shp file is used this enables
the user to highlight an individual country. By invoking the
setSelectedValue(<tag>,<value>,<ignoreCase>) method in
LayerShape. For example:
nM> invoke,,reg.plot.layers.world.setSelectedValue(CODE,US,TRUE)

nM> plot world.shp{LAYER={LABEL=NAME,ColoringMode=Mod5}}
nM> plot world.shp{LAYER={LABEL=NAME,ColoringMode=MinAdj}}

Plotting NGA images (requires MAP option tree)
==============================================
To plot NGA data:
1) Generate the list of table-of-contents files in the NGA directory
structure Assuming the directory /midas/mapdata/ contains NGA directories
(such as CIB10_129, GNC_126, JNC_127, ...)
nM>mapper MTOC /midas/mapdata/master_toc.tmp /midas/mapdata

2) Create a table file (.tbl) with FILE= references for all desired layers
in addition to /midas/mapdata/master_toc.tmp.
For example (master_toc_maps.tbl):
FILE=nxm.map.dat.world.shp{LAYER={LABEL=NAME},TAG=CONTINENTS}
FILE=/midas/mapdata/master_toc.tmp

3) Run the plot command with the table file as the SETUP= input.
nM>plot setup=/midas/mapdata/master_toc_maps.tbl
Zoom into area of map with imagery to see them.

Steps 1 and 2 only have to be performed once (unless the NGA directories are
changed, of course)

If the NGA data is on a remote system the NeXtMidas Map Server can be used to
serve the images up for remote plotting with LayerNMS (see EXPLAIN MAPSERVER).

Plotting Maps from a Map Server (WMS/NMS)
================================================
o Plot images from an OpenGIS Web Map Server (WMS):
nM> plot {LT="WMS",URL="http://<server>"}|world.prm view=LatLon

Since 3.3.2, the URL String can contain a comma-separated list of multiple
URLs. NeXtMidas will attempt to connect to the first URL in the list, and
if that is not reachable, then it will attempt to connect to the second
URL in the list, etc.

Since 3.3.3, the automatic connection to the Map Server while setting the
URL can be disabled using (NOTE: AutoConnect= must be before URL=):
nM> set url "http://<server>:<port>/..."
nM> plot {LT="WMS",AutoConnect=false,URL="^url"}|world.prm view=LatLon
later, the connection can be established using:
nM> res reg.plot.layers.wms.connect()

By default, no WMS layers are turned on. The WMS layers can be graphically
enabled using the WMS config panel. In the plot MMB->LAYERS->WMS to get
the config window. Layers can be specified on the command line by name
separated by commas (where the highest priority is at the end of list):
nM> plot {LT="WMS",URL=mapURL,Layers="shapePolitical,Relief,cadrg"}|...

To override the default network connection/open and read timeouts when
communicating with the Map Server to 30 and 99 seconds, respectively.
NOTE: the ConnectTimeout and ReadTimeout MUST come before the URL setting:
nM> plot {LT="WMS",ConnectTimeout=30,ReadTimeout=99,URL=mapURL,...}|...

To enable use of tiles with three download threads in the background:
nM> plot {LT="WMS",URL=mapURL,UseTiles=true,DownloadThreads=3,...}|...

Once the layer is configured, the configuration can be dumped to a table
using:
nM> res reg.plot.layers.wms.config

Note that layer names and URLs are CASE SENSITIVE, so always use quotes!

o Plot images from the NeXtMidas Map Server (NMS):
nM> plot {LT="NMS",URL="http://<server>:<port>/nms/"} view=LatLon

Plot images from the mapserver with the BLUEMARBLE background:
nM> plot {LT="NMS",URL="http://<server>:<port>/nms/",&
BACKGROUND="BLUEMARBLE"}|world.shp{LAYER={LABEL="NAME",OPAQ=0}} &
view=LatLon

Plotting Files Using LayerGeo
=============================
o NeXtMidas has a custom layer for plotting certain geo data. This class
is intended for use through the macro language.

o When bypassing the macro language (i.e. calling directly from Java),
users should call the setRef(Object ref) method to set their Midas
reference, otherwise some files (such as those in RAM, may not be found).

o LayerGeo uses two StateVectors (usually type 500 files) to compute
FDOA,TDOA, etc. These two files typically reference their data elements
through a time reference (offset from start). Since NeXtMidas 3.1.1,
when setting the desired time for the StateVectors, users can call either
LayerGeo.setTime(double) to pass in the reference time, or call
LayerGeo.setTimeCode(double) and pass in a J1950 time, which is
then converted to the appropriate reference time for the StateVectors.

o When setting the reference time in LayerGeo.setTime(double), if the given
value is a double greater than 86400*100 (100 days), NeXtMidas assumes
the user meant to call setTimeCode(double), so the given value is
passed through to that method.

Plotting IMAGE Files (and TBL Files)
====================================
To plot the PNG file in the SYS/DAT area:
nM> plot network.png

To plot a JPEG so it lines up with other data (this example is one of the
NASA Blue Marble pictures of the world:
nM> plot world_200409_3x5400x2700.jpg{LAYER={XSTART=-180,YSTART=90,&
XDELTA=360/5400,YDELTA=-180/2700}}&
|world.shp{LAYER={LABEL=NAME,OPAQ=0}} view=LatLon

Here XSTART and YSTART are the real-world-coordinates of there the upper
left pixel is located. The XDELTA and YDELTA are the extents divided
by number of pixels (i.e. deg/pixels). Most of the time YDELTA will need
to be negative to account for images being measured top-to-bottom rather
than bottom-to-top.

Alternatively this information could all be put into a tbl file...
bluemarble.tbl
: COMMENT="My comment"
: FILENAME="nxm.map.dat.bluemarble.jpg"
: XSTART=-180.0
: YSTART=90.0
: XDELTA=360.0/5400.0
: YDELTA=-180.0/2700.0
and then plotted quickly using:
nM> plot bluemarble.tbl

Plotting CSV Files
==================
CSV files can be plotted as "X vs Y" or "Multi" files depending on their
data. (Note that the name of the columns to be plotted must be prefixed with
a numeric type specifier.) Read "Plotting type 3000 files" for details on
these layer types.

LayerMulti (default):
nM> plot myfile.csv{HEADERROWS=1,COLUMNNAMES=SF:A|SF:B,&
LAYER={COLUMNS=A},TAG=A}

LayerXY:
nM> set quals {HEADERROWS=L:1,COLUMNNAMES="NAME|CODE|F:LAT|F:LON",&
LAYER={LT="XY",X="LON",Y="LAT",LINE={COLOR="red",TYPE="symbol"}}}
nM> plot world|nxm.sys.dat.airports.csv^{quals}

In NeXtMidas 3.1.1, a new Layer (LayerScatter) was added to provide more
support for plottinig CSV (and other) files. LayerScatter may replace
LayerXY in future releases.

LayerScatter:
nM> set quals {HEADERROWS=L:1,COLUMNNAMES="NAME|CODE|F:LAT|F:LON",&
LAYER={LT="Scatter",X="LON",Y="LAT",LINE={COLOR="red",TYPE="symbol"}}}
nM> plot world|nxm.sys.dat.airports.csv^{quals}

Formatting:
In NeXtMidas 3.3.3, the /DATEFORMAT switch supports a wide variety of
time/date formats made available via the MFormat class. Acceptable formats can
be either a standard Midas format ("STD", "ACQ", "EPOCH", "NORAD", "VAX",
"TCR", "HMS", "YMD", "ISO8601", etc.) or they can be any of the patterns
accepted by the java.text.SimpleDateFormat class.

For details, please see nxm.sys.lib.MFormat, nxm.sys.lib.Time.formatList and
java.text.SimpleDateFormat.

DRAG and DROP:
PLOT supports Drop in the following way (DRAG is not supported):

Since actions to take for DROP-ed objects are application-dependant,
objects DROP-ed onto a PLOT are sent to the Message Handler (then typically
sent to a Macro application) for handling.

For example usage, see the macro $NMROOT/nxm/sys/test/test_plot_drag_drop.mm.

Switches:
/ALL - Plots ALL data in the file. Note: this also sets the Backing
Store option, so the following two lines are equivalent:
nM> plot myfile.prm /all
nM> plot myfile.prm options="+ALL|BS"
/AXISBUFFER= - Set the size of the buffer area drawn around the plot axis.
This buffer area ensures that values that fall exactly on the
axis are displayed. Set to 0.0 to disable. Set to a negative
number to reduce values display area. [DEF=1e-12]. (Since 3.1.0)
/AXISINDEX - Sets Axis START=0 and DELTA=1 (Identical to /INDEX) [DEF=FALSE]
/CMAP= - (Layer2D only) Use predefined Color map. e.g: GrayScale,Ramp,
XRamp,Wheel,Terrain,Multi,T5Layer,Grid,Spectrum,XDatalist.
This overrides the [CMAP] parameter.
/COLORS= - (Layer2D only) Custom list of colors to use. This overrides the
[CMAP] parameter and /CMAP switch.
/DATEFORMAT= - Output format used to display time. See the above section
titled "Formatting" for details of valid inputs. In addition,
use AUTO to allow the plot to determine the appropriate format
where time spanning over a day will display STD, otherwise, HMS
format will be displayed. (Since NeXtMidas 3.3.3)
/DB - Display in dB (same as CM=10LOG)
/DB2 - Display in dB (same as CM=20LOG)
/DBLCLICKZOOM - Enable zooming in/out through the use of double-clicking the
mouse. (Since NeXtMidas 2.7.2)
/DRAGDROP - Enable or disable Drag and Drop. (Since NeXtMidas 3.3.0)
/EXIT= - Mask value with flags to exit: RETURN, MENU, MESSAGE, WINDOW
or ALL [DEF=NONE in pipe mode, else ALL]
/FOCUS - Try to get focus if true. (DEF=TRUE from shell,FALSE from macro)
/INDEX - Set Axis START=0 & DELTA=1 (Identical to /AXISINDEX) [DEF=FALSE]
/REVERSECOLORS - Reverse the colormap used by the layers of the plot
/LAYER - Same as [LAYER] parameter. Overrides [LAYER] if both are present
/LEGEND= - Legend corner (TL/TOPLEFT,TR/TOPRIGHT,BL/BOTTOMLEFT,
BR/BOTTOMRIGHT) the /LEGEND switch alone default is TOPLEFT.
or
Table of settings for the legend. Table keys include:
CORNER - The corner in which to come up
/LPB=n - Type 2000. Lines per buffer (max) used in grabs [DEF=16]
For LayerMulti this is Line-segments Per Buffer (this is the
same as /LPS= for pipes, but can be less in the case of paging
for a large static file).
/LPS=n - Type 1000,2000. Data frames/lines per screen over-ride (normally
scales to window height). If using a LPS value less than 16, set
/LPB=1.
For Type 2000 files plotted with type=line (Layer1D):
You may specify /LPS=-1 to compute the PlotFile's data buffer
size.
For Type 2000 files plotted with type=raster (Layer2D):
LPS=0 is the same as not having the switch (LPS based on
screen size) (Since NeXtMidas 3.7.0)
LPS = -1 will default LPS to 128
LPS > 0 sets LPS to the specified value
Note: In paging mode, LPS is set to /LPB (or default LPS of
128 if /LPB is not specified)
For LayerMulti this is Line-segments Per Screen, and defaults to
the SIZE of the file/pipe; this should be >= LPB.
/MSGID= - Registry name of command to handle messages (usually MAIN)
/MTAG=t - Used in conjunction with [CNT] or /XCNT=. This is a table of
key value pairs where the key is one of "X","Y","Z", or "X+Y"
and the value is the name of a RESULT to set with the
corresponding value of the key, based on mouse actions
defined in CNT or /XCNT. Since 3.1.1.
/MOUSEWHEELZOOM - Enable zooming in/out through the use of the mouse scroll
wheel. (Since NeXtMidas 2.7.2)
/NICE= - 1=retry for layers if don't exist yet
2=disconnect from pipes if iconified
/NOPUSHPOP - Disables user Push/Pop for a window (e.g. clicking the 'X' when
popped out. Does not affect Push/Pop messages from a macro).
/OPENWARN - Mask value with flags indicating where to WARN when a file can not be
opened: NONE, POPUP, or PRINT [DEF=POPUP]
(Since NeXtMidas 3.5.2)
/PRECISION= - Number of decimal places of precision used for readout display.
This has higher precedence than the ExtPrec readout option.
/QUICKDRAW - Type 5000 only. Optimizes drawing of objects in Type 5000 files,
but some objects do not get drawn (lines where one of the points
is off-screen). (Since NeXtMidas 3.1.0)
/READOUT= - Sets the ReadOut mask (e.g. "/READOUT="+OnAxis|+Units").
NOTE: This will override the [READOUT] parameter.
/RT - use real-time algorithm even on files
/SCALEZ= - Layer2D only. Scale color range option= PLOT,LAYER [DEF=PLOT]
PLOT - All Layers / Files use the same Z Min and Z Max [DEF]
LAYER - Individual Layers scale their Z Min and Z Max
/THEME= - Use a named Theme (Desktop,Default,WoB,GoB,BoW,Browser,Gear1,
Gear2,Gear3,Gear4,Nak)
/THEME=tbl - Creates a custom theme from a table of parameters. See PANEL for
complete description. Table keys include:
CBG - background color
CFG - foreground color
CWTS - widget top shadow
CWFH - widget foreground highlight
CWBG - widget background color
CWFG - widget foreground color
CWTITLE - widget title color
CWBS - widget bottom shadow
/TIMEALIGN - Type 1000 time-based plots only. Align overlapping layers based
off the XStart of the base layer. (Since NeXtMidas 3.1.2)
/WIN= - Specifies the name of WINdow (or panel) in the registry that
will host this (see nxm.sys.libg.MWindow). If the window name
is not specified, or included in panel config, a new frame is
created.
/WIN.cmd= - Similar to /WIN.
/WDISP=n - Set the monitor number for the display [0...n-1]
/WFS= Set the axis labels and axis title font size [DEF=12]
/WPOS= - Set the position of the plot when it opens, use the syntax
"/WPOS=(X,Y[,Width,Height])" where all values are in pixels.
/WTITLE - Sets the window bar title (not the axis title). The readout
will override this when READOUT=ONAXIS is selected. [DEF=PLOT]
/XCNT= - See [CNT] above. [CNT] has precedence when both are
present. (Since NeXtMidas 3.1.1)
/XMULT= - Convert x units using scientific notation prefix.
Arguments for this switch can be passed in three ways:
1) n, where n is one of {-12,-9,-6,-3,3,6,9,12}:
(e.g. 6 is Mega) --OR--
2) One of { "pico", "nano", "micro", "milli",
"Kilo", "Mega", "Giga", "Tera" } --OR--
3) One of {'p','n','u','m','K','M','G','T'}
/YMULT= - Convert y units using scientific notation prefix. (cf. /XMULT)
/ZOOMADJ= - Percentage (float) to adjust plots when doing incremental zoom.
Value is greater than zero and less than 1. [DEF=0.1]
/ZOOMMULT= - Multiplier which is used when moving zoom by larger amount,
typically through the use of PAGE UP, PAGE DOWN, HOME, and END
shortcut keys. [DEF=5.0]

See Also: LAYER, FEATURE, PANEL, nxm.sys.libg.MPlot, nxm.sys.libg.MColor

</pre>

[[Category:NXM_Explain]]

ENDIF

2020-04-27T22:05:18Z

ConvertBot: end an IF block

end an IF block
<pre>
This command has no arguments.

Each block IF statement in a macro must be ended with an ENDIF statement
at the end of the block.

SEE ALSO: IF, ELSE, ELSEIF

</pre>

[[Category:NXM_Explain]]

ENVIRONMENT

2020-04-27T22:05:18Z

ConvertBot: Performs various functions on the NeXtMidas environment

Performs various functions on the NeXtMidas environment
<pre>
<func> Function to perform on environment [DEF=SHOW]
<key> Function dependent keyword. Desired variable of interest for
SET or GET
<value> Results label for GET, or value for SET

This command performs a number of functions from showing the NeXtMidas
environment, to performing an NFSLOOKUP or showing system related
information like memory usage or threads Java properties

Since the environment variables are now the table ENV in the results table,
they may be read directly without using this command.

The NeXtMidas FILE intrinsic replaces the X-Midas environment file functions.

Special keywords may not set an entry in the ENV table or may do more than
just set the entry.

FUNCTIONS:
GET - ENV GET <key> <label>
Get the keyword in the environment. Prints to screen if <label> is blank

The environment variables in the ENV table are:
NMROOT - The NeXtMidas root installation directory
USER - User name
HOME - The home directory
HOSTNAME - The local host name
HOSTADDR - The local host IP address
OSTYPE - The operating system type (UNIX,WINDOWS,...)
OSNAME - The operating system name (Linux,...)
OSREP - The operating system data representation (EEEI,IEEE)
EDITOR - The desired editor. Automatically chosen by EDIT command.
VIEW - TBD
THEME - The current theme (see LOOKANDFEEL).
STYLE - TBD
GRAPHICS - What graphics options to use. See details below.
PID - Process ID
MSF - The current Midas State File
NMVERSION - The NeXtMidas version (x.y.z).
JVMVERSION - The Java version (x.y.z).
NMPRERELEASE - TRUE if version is a pre-release, FALSE otherwise.
PAUSE - The default pause time between primitive process calls.
VERIFY - The VERIFY mask string
DEBUG - The DEBUG mask string of bar ("|") separated values.
HWFILE - The hardware configuration file
KEYMAP - Mapping of Plot keyboard shortcuts
UIMANAGER - Adjustments made to the SWING UIManager
IOOPTIONS - The options for input/output for files and other I/O.

Special GET keywords (not necessarily in the table) are:
COMPLETIONAUXEXCLUDE - Pipe-separated list of AUXes that are to be
excluded when using FILES searching and
tab-completion (since NeXtMidas 3.1.0)
DEFAULTTABLEFLAGS - The default table flags (since NeXtMidas 2.7.1)
DEFAULTTABLEMODE - The default table mode (since NeXtMidas 2.7.0)
FileNameCASE - Default FileName case option (this is overridden
by the FNCASE= qualifier). (since NeXtMidas 3.3.1)
HOSTNAMEFQDN - Fully-Qualified-Domain-Name for the ENV.HOSTNAME
(note that this will simply return ENV.HOSTNAME if
the name resolution fails. (since NeXtMidas 3.3.2)
NUMSCReens - The number of screens in this graphics environment
NUMNONVIRTSCREENS - The number of non-virtual screens in this graphics
environment (since NeXtMidas 2.8.0)
PRIV - The privileges mask
SERVER - Gets the current server address (this can be
overridden by /REMOTE=<server>)
SERVERFQDN - Fully-Qualified-Domain-Name for the ENV.SERVER
(note that this will simply return ENV.SERVER if
the name resolution fails. (since NeXtMidas 3.3.2)
USENATIVE - The mask string defining native code use

GRAPHICS - The graphics options (found in Theme.java) allow for control over
the method NeXtMidas uses to display certain items such as plots
and widgets. The current default in Theme.java is SWING|REALTIME
but this can be overridden using the 'env set' command (such as in
startup scripts).

Options:
--------
HEADLESS - Do not draw Windows (including Plots) on display
AWT - use heavyweight (AWT) objects
SWING - use lightweight (SWING) objects for Plots
REALTIME - allow lightweight plots to draw in their own thread
MOBILE - All-SWING with special parenting options for pop-ups
SWINGDB - turn on SWING double buffering
SWINGWIDGETS - GWidget controls drawn on SWING panels
SWINGPOPUPS - GWidget controls drawn on SWING panels
NOSLAF - No Swing Look and Feel theme support (or query)
NOXLAF - No external swing look and feel changes via UIManagers
INITONLOAD - Initialize graphics themes on load instead of on demand
DEBUG - Enable graphics environment debug output

KEYMAP - (Since 2.7.2) The keymap is a mapping of keyboard shortcuts to
Plot zoom adjustments. Based on industry practices (most notably
Google Maps), the keyboard shortcuts allow users to move the
viewable area of a zoomed-in plot using only the keyboard.

ENV.KEYMAP is typically set in nmstartup.mm, but can be modified
at any time. If it is null, Plot will use default settings. The
defaults are basically to use the arrow keys to make small
adjustments, the home/page up/page down/end keys for larger
adjustments, and the "+" and "-" keys for incremental zooming in
and out.

UIMANAGER - The SWING UIManager provides the ability to change many aspects
of the Swing look and feel "on demand".

Starting in NeXtMidas 2.7.3, users can alter the UIManager by
using the "environment set uimanager <table>" command:

nM> env set uimanager {scrollbar={width=10,thumb=red}}

The above example will change the Swing scrollbar to be 10 pixels
wide and have a color of red.

Note that not all UIManager settings can be altered, as they may
require inputs of sound files, images, etc.. Generally, the
following input values types are supported:

Data Types (int, long, double, boolean, etc)
Strings (or char)
Colors
Fonts (font name only, e.g. "courier", "arial", etc)

A complete list of UIManager properties depends on the Java
version and OS, but can be found in Java by using the following:

Enumeration<Object> keys = UIManager.getDefaults().keys();

IOOPTIONS - The options for input/output for files and other I/O. Since 2.9.0
DisableEscapeSequences - Turn off the handling of escape
sequences in quoted Strings (inside macro/prompt)
using the backslash character (i.e. '\') just like
Java/C string escape sequences.
Note: this does not apply to creating Tables from
Strings or writing out the contents of a Table with
Table.toByte(..). This option is DEPRECATED.
In 3.1.0, escape sequences are enabled by default.
StrictHTTP - Strictly follow HTTP 1.1 (RFC 2616) rules. E.g. Work
around HTTP servers that return 200 status code to a
GET/POST request with Range header (with desire to
read partial content), which will potentially break
communication with NeXtMidas 2.8.2 and prior HTTP
servers that did not correctly returned 206 status
code.
TruncateBLUE - When overwriting existing BLUE files, truncate
them on the storage device to minimum size
necessary (Since 2.9.1).
DisableQuadwordsEqualityChecks - Turn off the equality checks in
DataFile that check quadwords in Type 5000 files.
Setting this will enable the (buggy) behavior of
NeXtMidas 3.2 and earlier which ignored quadwords
in equality checks. (Since 3.3.0)
WriteNoAbort - Do not abort even if an Exception occurs during
writing. (Since 3.5.4)
FileIONoAbort- Do not abort even if an Exception occurs during
a file write or read. (Since 3.7.1)

SET - ENV SET <key> <value>
Set the keyword in the environment

Special SET keywords are:
COMPLETIONAUXEXCLUDE - Sets the pipe-separated list of AUXes which are
ignored when searching via the FILES command or
tab-completion. (Since NeXtMidas 3.1.1)
DEFAULTTABLEFLAGS - The default table flags, this can also be set using
the TABLE command. (since NeXtMidas 2.7.1)
DEFAULTTABLEMODE - The default table mode, this can also be set using
the TABLE command. (since NeXtMidas 2.7.0)
FileNameCASE - Default FileName case option (this is overridden
by the FNCASE= qualifier). (since NeXtMidas 3.3.1)
PRIV - Sets the sandbox privileges (supports value=ALL)
USENATIVE - Sets the property in nxm.sys.lib.Native for use
of native code

SHOW - ENV SHOW <key>
By default shows the current environment is listed on the terminal or
any of the other special SHOW functions listed below.

Special SHOW functions are:
"" - shows all NeXtMidas environment variables in ENV table and
other special ones not in the table [DEFAULT]
THREAD - shows all threads
MEM - shows memory usage
PROP <filter> - shows all Java Property values. Since 3.5.2, a simple
case-insensitive <filter> search string can be specified for
either property name or value.
KEYGETS - Deprecated since NeXtMidas 2.7.0 (always blank)
KEYSETS - Deprecated since NeXtMidas 2.7.0 (always blank)
HANDLERS - show table of handlers for FILEs and PACKETs

RESET - TBD - resets variables affecting pipes and macros

NSLOOKUP - gets an IP address for the named node
Syntax: ENV NSLOOKUP <hostname> <inetaddress>

GC - runs the garbage collector. Use /VERBOSE=T to see output in a macro.
Syntax: ENV GC

Examples:
1. A typical set of the environment variables kept in the ENV table are
nM> env
T: ENV = Table of 24 entries
19S: NMROOT = /home/midas/nxmxxx/
3S: USER = jph
10S: HOME = /home/jph/
6S: HOSTNAME = JPHLAP
9S: HOSTADDR = 127.0.0.1
4S: OSTYPE = UNIX
5S: OSNAME = Linux
4S: OSREP = EEEI
3S: EDITOR = nedit
4S: VIEW = TEXT
5S: THEME = GEAR3
5S: STYLE = GEAR3
14S: GRAPHICS = SWING|REALTIME
4S: PID = 1172
19S: MSF = /home/jph/nmsf_1172
5S: NMVERSION = 3.4.3
5S: JVMVERSION = 1.8.0
4S: NMPRERELEASE = FALSE
D: PAUSE = 0.0125
1S: VERIFY = |
17S: DEBUG = |Trace|Deprecate|
34S: USENATIVE = |IO|Math|Cast|CastX|Convert|Other|
20S: HWFILE = nxm.sys.dat.hwconfig
T: KEYMAP = Table of 1 entries
------- Other Environment Settings ------
CompletionAuxExclude = |99|
DefaultTableFlags = |AutoReadPrev|
DefaultTableMode = SynchronizedLinkedHashMap
FileNameCase = AutoCase
HostNameFQDN = jphlap.localdomain
NumNonVirtScreens = 1
NumScreens = 3
Priv = ALL
Server =
ServerFQDN =
UseNative = |IO|Math|Cast|Convert|Other|

2. To determine the host address of this computer
nM> ENV GET HOSTNAME myHostname

3. To set the control panel widgets to use SWING panels and double buffer
nM> ENV SET GRAPHICS +SWINGWIDGETS|+SWINGDB

4. To set the Swing scrollbar to be 10 pixels wide and have a color of red:
nM> env set uimanager {scrollbar={width=10,thumb=red}}

5. If the /SERVER switch is specified on a macro, it is to be run in server
mode. If the /CLIENT switch is specified on a macro, it is to be run in
client mode. The client macro gets the server address from the
/REMOTE=host:port switch, the ENV.SERVER variable, or the Midas.getServer()
function. This command will search this path for the servers address
nM> ENV GET SERVER theServer

6. To determine how many screens your computer has:
nM> env get NUMSCREENS ns

7. To determine how many screens your computer has that are not virtual (aka,
cinerama is 1 screen not 3).
nM> env get NUMNONVIRTSCREENS nsNonVirt

8. Disable the handling of escape sequences in Strings:
nM> env set iooptions +DisableEscapeSequences

9. Set the list of AUXes to ignore when using the FILES command or
tab-completion
nM> env set COMPLETIONAUXEXCLUDE "RAM|99"

Switches:
/ALL - Enumerate contents of any tables in the environment for SHOW
function
/REMOTE=<r> - Override the default host:port for the ENV GET SERVER function
/VERBOSE - Show additional information while command is running

See Also: TABLE, LOOKANDFEEL

</pre>

[[Category:NXM_Explain]]

HTTPSERV

2020-04-27T22:05:18Z

ConvertBot: An HTTP/1.1 server to serve files rooted in given directory.

An HTTP/1.1 server to serve files rooted in given directory.
<pre>
<PORT> The port that the web server is to run on. [default=8080]
Use 0 for any free port (Since NeXtMidas 2.7.0, once server is running,
port is updated and printed to reflect the actual listen port.)

<DIR> The directory containing the files to be served. If the parameter
begins with a slash (/) then it is assumed to be an absolute pathname,
otherwise it is assumed to be relative to NMROOT. [default=htmlhelp]

<NAME> The alias by which the directory will be accessed. [default=dat]

The NAME parameter is the alias used by the web server for the directory.
HTTP requests that begin with the specified name will be mapped to a file
that is contained in the given directory. Files in subdirectories will be
served if the request URI begins with the NAME.

+---------------------------------------------------------------+
| WARNING |
| Unlike most web servers, the names of the file accessible via |
| HTTPSERV should be assumed to be case sensitive. |
+---------------------------------------------------------------+

Messages:
HTTPGET - Send from primitive to /MSGID= with the following:
NAME=HTTPGET
INFO=0
DATA={SOCKET=<outputSock>,PARAMAMETERS=<params>}
<outputSock> is an instance of nxm.sys.net.HPage
<params> is a Table of input parameters (same as calling
<outputSock>.getParameters())

Note that the macro ***MUST*** invoke both openSocket() and
closeSocket() on the <outputSock>. Failure to do this will cause
the request handler to hang!!!

HTTPPOST - Same as HTTPGET, except for an HTTP POST request. See the API
for HPage.getPostData() for details on accessing POST data.
(Note: Support for HTTP POST was added in NeXtMidas 2.7.0)

Examples:
1. Make the files in "${NMROOT}/nxm/sys/dat" available on the net via
"http://hostname:8080/dat/":

nM> httpserv 8080 DIR="nxm/sys/dat" NAME="dat"

This will instantiate a server on port 8080 that will serve files rooted
in the ${NMROOT}/nxm/sys/dat directory and will use 'dat' as the alias for
this directory.

While this is running, you can do the following from another system:
nM> status http://hostname:8080/dat/apenny.prm

or even
nM> noop http://hostname:8080/dat/apenny.prm localpenny

This connection is not limited to NeXtMidas sessions, any program with
HTTP access can access the files, for example a web browser can load the
"Sunset.jpg" file using "http://hostname:8080/dat/Sunset.jpg".

Note that by default ALL files under $NMROOT are accessible via
"http://hostname:8080/nmroot/" also note that any web browser pointed
to "http://hostname:8080/" will automatically be able to access the
NeXtMidas documentation (if built) and status information about any of
the primitives running over the network.

2. Run SD360;SYS with HTTPSERV:
nM> sd360/server=9000/http

Now it is possible to point a web browser to "http://hostname:9000/" and
get status information about the running RMIF connection.

See the SD360 explain file for details.

3. Run HTTP server on any available port and display host and listen port

nM> httpserv port=0 /bg
INFO: Starting HTTP Web Server at URL=http://<host>:<port>/ [HTTPSERV]

nM> say "using host=^{reg.httpserv.host} port=^{reg.httpserv.port}"
using host=10.10.1.59 port=38375

4. Use the /MNAME= and /MSGID= switches to allow the macro to respond to a
HTTP request:
startmacro
pipe on
httpserv/msgid=main/mname="mymacro" port=9999
pipe off
endmacro

procedure processMessage m:msg
say "Got message name=^msg.name info=^msg.info data=^msg.data"

if msg.name eqs "HTTPGET" then
set socket msg.data.socket
set params msg.data.parameters

! say "Got HTTPGET request, URI= ^{socket.uri}"
invoke,,socket.openSocket()
invoke,,socket.writeln("Got request with ^{params}")
invoke,,socket.closeSocket()
elseif msg.name eqs "HTTPPOST" then
...
endif
return

A client can then use "http://localhost:9999/mymacro?a=1&b=2&c=3" to access
this macro. NOTE: The macro MUST invoke both openSocket() and closeSocket()
on the <socket>. Failure to do this will cause the primitive to hang!!!

Switches:
/AUXLIST=<l> - List of AUXs to make available under
"http://host:port/Files/<AUX>/<filename>". By default none
are listed (same as /AUXLIST=null). /AUXLIST="*" serves up
everything in AUX.READ (use of /AUXLIST="*" is very common).
/HOMEPAGE=<p> - Homepage location for HTTP web server (<p> = path).
/MNAME=<n> - Turns on macro handling of requests where <n> is the name of
the macro as given in the HTTP request. If /MNAME="/mymacro"
(or /MNAME="mymacro", leading slash is implied) then the
client uses "http://<server>:<port>/mymacro" to access it).
When this is enabled HTTPGET and/or HTTPPOST messages will
be sent to /MSGID=. If /MNAME="/" (e.g. root alias) then all
requests will be forwarded specified message handler otherwise
the default HServer index will serve up the / requests.
/MSGID=<n> - Registry name of command to handle messages (usually MAIN),
only used with /MNAME= switch.
/PRANGE=n - Range of port numbers above <PORT> to use if already
allocated. [DEF=1] Since 2.9.3.

See Also: RMIF, nxm.sys.net.HServer, nxm.sys.net.HPage

</pre>

[[Category:NXM_Explain]]

THIN

2020-04-27T22:05:17Z

ConvertBot: Copy one file to another with optional offset, length, and decimation

Copy one file to another with optional offset, length, and decimation
<pre>
<IN> Input file
<OUT> Output file
<START> Starting offset (inclusive)
<END> Ending offset (exclusive)
<INC> Increment between input file elements
<FSTART> Frame Starting offset
<FEND> Frame Ending offset
<FINC> Frame Increment between input file elements

This primitive performs data thinning on 1D, 2D, or record oriented file
formats. The last 3 arguments apply only to 2D interframe. (The X-Midas
TWODTHIN function). If the increment is negative, this primitive performs the
UPZERO function.

The <START>, <END>, and <INC> arguments are absolute, offset addresses by
default. To use abscissa addressing, precede the argument with a tilde (~). To
use relative addressing, precede the argument with a plus.

The <START> and <END> are ZERO based offsets, so that start=2 end=10 actually
gets the data elements starting and INCLUDING offset=2 up and EXCLUDING
offset=10. This corresponds to the one-based elements 3 through 10. This is
identical to the way file trimming arguments are used.

Examples:

1. Copy infile to outfile downsampling by factor of 2 (i.e. 50% reduction)
nM> thin infile outfile ,, 2
-or-
nM> thin infile outfile inc=2

2. Copy elements 1-3 of infile to outfile.
nM> thin infile outfile 0 3

3. Copy all but the last two elements of infile to outfile.
nM> thin infile outfile 0 -2

4. Copy every third element from the 2nd element to the end of the file (EOF).
nM> thin infile outfile 1 -0 3

5. Copy 20 elements starting at 1 second into the file.
nM> thin infile outfile ~1 +20

6. Copy every other element from 1sec to 2sec into the file.
nM> thin infile outfile ~1 ~2 2

7. Upsample infile by 8 by inserting 7 zeros between each value.
nM> thin infile outfile INC=-8
or
nM> thin infile outfile INC=.125

8. Get Y cut of a type 2000 file at index x (without adjustments).
nM> thin in2000 out2000 fstart=x fend=x+1
-or- into a type 1000 file with xstart, xdelta, xunits re-adjusted
nM> thin in2000 out1000{type=1000,xs=inys,xd=inyd,xu=inxu,yu=none} &
fstart=x fend=x+1

9. Reset the Frame Start value of a thinned Type 2000 data pipe
nM> set reg.<id>.fstart <new fstart value>

10. Reset the frame start, stop and increment of a thinned Type 2000 data pipe
nM> set reg.<id>.fvals {FSTART=<val>,FEND=<val>,FINC=<val>}

11. Thin out file forcing abscissa + timecode addressing
nM> thin infile outfile startTime endTime /addressing=TIMECODE

12. Thin out file using only abscissa addressing (do not add timecode)
nM> thin infile outfile startSec endSec /addr=ABSCISSA

Switches:
/ABSC Use ABSCISSA_LEGACY addressing for ALL arguments
/ADDR= Alias for /ADDRESSING
/ADDRESSING= Addressing mode. [DEF=INDEX] (Since 2.9.1)
INDEX - Absolute indexing.
ABSCISSA - Abscissa indexing only (e.g. time or frequency).
TIMECODE - Indexing using time: abscissa address +
(TimeLine (if exists) or timecode, in that order).
ABSCISSA_AUTO - Same as TIMECODE mode when abscissa units is Time,
otherwise same a ABSCISSA mode.
ABSCISSA_LEGACY - Similar to ABSCISSA_AUTO, but ONLY use
abscissa + TimeLine/timecode when abscissa units is Time
and when return index is greater than 100e6 seconds.
/RESTART=T|F Enable/disable the output pipe from restarting when certain
properties (inc, start, end, and fend) are changed. [DEF=TRUE]
/TL=n Specify the number of elements to process on each read

</pre>

[[Category:NXM_Explain]]

SORT

2020-04-27T22:05:17Z

ConvertBot: Sorts a Type 3000 file.

Sorts a Type 3000 file.
<pre>
<IN> The input file.
<OUT> The output file.
<KEYS> The keys to sort by (separated by '|').

DESCRIPTION:
This will sort a Midas BLUE Type 3000 file. The input file will be read in
and then the data will be sorted before writing out to the output file. The
provided keys specify which key or keys to sort by. They should be in the
form:
<KEYS> = "key1|key2|key3"

This will sort with "key1" as the primary key, and "key2" as the secondary
key (used where multiple "key1" values match), and so forth.

This primitive is intended for use with only small data files. The following
assumptions were made when the primitive was written:
1. The entire file can be read into memory prior to sorting.
2. The sort algorithm need not be highly optimized. (Though
it is optimized in the current implementation.)
3. The keys specified will match the fields in the records.
4. All values for a given field will be of the same data type.

SORT ORDER:
To "normal"-sort on a key (smallest-to-largest) prefix the key name with a
plus sign ('+'), or give it no prefix. Such as:
<KEYS> = "+key1|+key2|+key3" or <KEYS> = "key1|key2|key3"

To reverse-sort on a key (largest-to-smallest) prefix the key name with a
minus sign ('-'). Such as:
<KEYS> = "-key1|-key2|-key3"

Mixing the sort order between keys is permitted. Such as:
<KEYS> = "key1|-key2|+key3"

EXAMPLES:
1. Sort the 'testxy3000' file based on 'ABSC':
nM> sort testxy3000 outfile absc

2. Sort the 'testxy3000' file based on 'ABSC',in the reverse order
sort key (for instances where 'ABSC' values match):
nM> sort testxy3000 outfile -absc

3. Sort a file based on multiple keys:
nM> sort inFile outFile "-SINT|-NAME|+SLNG"

</pre>

[[Category:NXM_Explain]]

SWITCH

2020-04-27T22:05:17Z

ConvertBot: Define static switches or get a switch value into a results parameter

Define static switches or get a switch value into a results parameter
<pre>
<NAME> Name of the switch
<VALUE> Switch value for SET; Switch value label for GET (default) and DEL
<FUNC> Action to perform (GET[DEF], GETALL, SET, or DEL)
<DEF> Default value if switch is not present
<SDEF> Default value if only a state switch is present

SWITCH is the mechanism by which macros define their own switches and branch
in response to switches.

Functions:
GET - Gets a particular switch and stores its value in a result

Syntax:
SWITCH <NAME> <VALUE> GET <DEF> <SDEF>

<NAME> The name of the switch (e.g. "MYSWITCH")
<VALUE> The label of the result to store the value of the
switch in (e.g. "MYVALUE")
<DEF> The default value if the switch is not specified
<SDEF> The default value to use if the switch is given as a
state switch (usually "true" or "1"). If not set,
the empty string ("") will be used.

SET - The SET function works the same as the GET, but has the effect of
setting the highest precedence for the value of the switch. This was
done to allow commands within a macro to NOT inherit values of
designated switches. See example. (Since NeXtMidas 2.9.0)

Syntax:
SWITCH <NAME> <VALUE> SET

<NAME> The name of the switch (e.g. "MYSWITCH")
<VALUE> The value to set the switch to, or the label of the
result containing the value

DEL - The DEL function allows the user to delete any current value for the
switch. This also allows for users to not inherit a values of
designated switches, but does not set a value in turn.
See example. (Since NeXtMidas 2.9.0)

Syntax:
SWITCH <NAME> <VALUE> DEL

<NAME> The name of the switch (e.g. "MYSWITCH")
<VALUE> The label of the result to store the previous value of
the switch (since neXtMidas 3.1.3)

GETALL - Gets all switches and stores their values in a result. Note that
this function works by looking at all switches passed in on the
macro's command line rather than looking only for a pre-defined
set of switches. (Since NeXtMidas 2.9.0)

Syntax:
SWITCH ,, <VALUE> GETALL ,, <SDEF>

<VALUE> The name of the table to put the switches in. If the table
exists, the contents of the table will be used as default
values (like <DEF> with GET)
<SDEF> The default value to use if the switch is given as a
state switch (usually "true" or "1"). If not set,
the empty string ("") will be used.

In NeXtMidas, most switches can be tested in logical test directly, as with

if /C then
...
else
...
endif

The same syntax works on numeric or string values, as with

if /FN eqs "MYFILE"
or
if /N gt 4

The switch statement is useful for applying defaults to switches that may
or may not be present, as with

switch FN fnlabel get "MYFILE"
or
switch N nlabel get 20

which applies the defaults "MYFILE" and 20 to those switches, if they are not
applied. String valued switches that supply the <SDEF> parameter will set the
value to <DEF> if the switch is not present, or <SDEF> if the switch is present
but no =value is given.

SWITCH inheritance:
1. Switches right after the command (no space in-between) are inherited by
primitive and intrinsic commands called by the command. e.g.
MYMACRO/ASWITCH arg1 arg2

2. Switches at END of argument list are the same as the above but they are
also inherited by macro commands called by the command. e.g.
MYMACRO arg1 arg2 /ASWITCH

SWITCH precedence (order):
1. Macro command line (passed in when macro is run)
2. Commands (macros,primitives,intrinsics) in the macro
3. Command dictionary (commands.cnf)
4. Macro Defaults (on startmacro line)
eg. startmacro/switch

Examples:

1. Set fnlabel to "NOFN" if no switch is present, or "MYFILE" if just /FN is
present. If /FN=<text> is present, fnlabel will have the value of <text>.

switch FN fnlabel get "NOFN" "MYFILE"

2. A switch command with its own switch has the effect of setting the default:

switch MYSW myres /MYSW=10

3. Allow child macro to see a pipes created in calling macro

mymacro/sharemask=pipes

4. Set the value of a switch regardless of what is passed in on the command
line (ignore precedence):

switch name="MYSWITCH" value=15 func=set

5. Delete a current switch but store its value, if it exists.

switch name="MYSWITCH" value=savedVal func=del

6. Get all switches passed to the macro

switch ,, mytable ,, GETALL ,, 1

7. Use the switches passed to the macro to override a set of defaults

set t:mytable {SWITCH1="VALUE1",SWITCH2="VALUE2"}
switch ,, mytable ,, GETALL ,, 1

Switches:
/CS - Get a case-sensitive value (for FUNC=GET) without requiring user to
quote strings. (Since 3.1.2)
/QUIET - Disable verbose messages (overrides universal /VERBOSE switch).
(Since 3.3.0)

Graphical Command Switches:
Applies to anything that extends nxm.sys.lib.MWindow, like PLOT, LIST2,
GCONTROLS, etc.
/DISPLAY= - Make window come up in specified display mode:
Icon, Back, Front, or Maximized. (Since 3.1.1)
/EVENTFILTER= - Window event filter mask (e.g. NoMouse,NoKeyboard,NoMove,
NoPushPop,NoMiddleMouse). For complete list of values
see nxm.sys.libg.MWindow.eventFilterList. (Since 3.3.1)
/ICON - Make window come up in icon state. (Since 3.1.0)
/NOALTTITLE - Disables automatic updates to the status/title bar text
from events such as mouse hovers. (Since 3.3.0)
/NOPUSHPOP - Disable window push/pop out/in of panel. The /EVENTFILTER=
switch takes precedence over this.
/SHARETHEME - Whether or not to have all graphical components share
the same Theme. (Since 3.3.0)
/THEME= - Specifies the THEME to use. See EXPLAIN LOOKANDFEEL.
/WDISP= - Specifies the Window DISPlay to use (i.e. specifies which
monitor for systems with 2+ monitors).
/WFS= - Window or widget font size.
/WIN= - Specifies the name of WINdow (or panel) in the registry
that will host this window. If the window name is not
specified, or included in panel config, a new frame is
is created.
/WIN.<cmd>= - Similar to /WIN.
/WIN.NEW - Always open in a new frame.
/WPOS=(x,y,w,h) - Window position in pixels. Width and height are optional.
/WTITLE= - Window title.

Macro Switches:
/MSGDEBUG=mask - Enable debugging printout of messages processed (e.g.
received) by macro. Default for just specifying as a state
switch is NAME|INFO|DATA|QUALS|FID|TID. [DEF=NONE]
(Since 2.7.1)
/SHAREMASK= - Control whether or not a child macro (a macro called from
another macro) can see the parent's (calling macro) pipes.
Currently the only options are "PIPES". [DEF=NONE]
(Since 2.7.3)

Pipe and File Switches:
/AUX= - Specifies which AUX to use for file. The {AUX=<aux_name>}
file qualifier takes precedence over this.
/PS= - Pipe Size in bytes. [DEF=131072]
/TLL= - TimeLine length [DEF=128]
/TLT= - TimeLine tolerance [DEF=0.1]

Universal Switches for all command (when handled by NeXtMidas proper):
/BG - Run command in BackGround. [DEF=FALSE]
/CMDOPENTIMEOUT=- Provides a way for a command run in a pipe section to NOT
wait for a very slow open() to complete before running
the next command in the pipe section.
[DEF=-1 for effectively infinite] (Since NeXtMidas 2.7.4)
/CMDRUNMODE= - Provides a way for a command to override its default run
mode behaviors. An example of this is running a primitive
to completion in a pipe section. Possible values:
Default - Use default behavior (this is the
default)
RunToCompletion - Run command to completion rather than
following the normal pipe section
rules, note that this does override
/BG. (Since NeXtMidas 3.5.4)
/ID= - Associate an ID to a command. Only primitive, host
primitive, or macro IDs are used for message passing,
entry in the registry, etc. [DEF=based on command name]
/MSGID= - Sets the ID of the registry entry that will process
messages sent by this command. Using /MSGID=MAIN will
send all messages to the macro's processMessage procedure.
[DEF=none]
/POLL= - Time (in seconds) between process loops (e.g. reads of a
file) when there are no data to process. [DEF=ENV.PAUSE]
/VERBOSE - Produce more screen (verbose) output. [DEF=FALSE in macro,
TRUE at shell prompt]

</pre>

[[Category:NXM_Explain]]

LOCAL

2020-04-27T22:05:17Z

ConvertBot: declare results names as local to the macro (deprecated)

declare results names as local to the macro (deprecated)
<pre>
This command is a placeholder for help in transitioning XMidas scripts to
NextMidas. The default behavior within NeXtMidas is to have all results be
local so this command is not necessary.

</pre>

[[Category:NXM_Explain]]

XGEOPLOT

2020-04-27T22:05:16Z

ConvertBot: ALPHA! - An incomplete drop-in replacement for X-Midas XGEOPLOT

ALPHA! - An incomplete drop-in replacement for X-Midas XGEOPLOT
<pre>
<SITE> - Site file
<SV> - State Vectors for platform A
<UNKNOWN> -
<REFTIME> - Reference time of interest in seconds (initial)

This primitive is NOT COMPLETE but is the start of a replacement for the
X-Midas XGEOPLOT primitive.

Messages:
NAME - DESCRIPTION (Note: all messages are INcoming)
-----------------------------------------------------------------------
OVERLAY - General Information:
This message is used to overlay a file onto the current file.
If an overlay message arrives which specifies a file that has
already been loaded, that file will be reread. To set additional
arguments or to update the viewable area of the plot when opening,
use the optional message field QUALS=<table>. For more details, see
the plot explain file.

INFO = 3-layers 4-events
DATA = <filename.ext>

- Optional Fields:
QUALS = {OUTERLIMITS={}, VIEWLIMITS={}}

T5REC - General Information:
This message is a somewhat raw method of altering a LAYERT5
record. All type 5000 files are stored internally with a
record structure closely resembling the T5REC message fields.

INFO = modmask (i.e. bitmask of fields to modify). Note: This
information can also be supplied in String form by
having a MODMASK key in the DATA table (MODMASK Data
Field/Table entry will override INFO).
Only those items whose bit in the modmasks field is set
will be updated when the message is received. For
short, modmask=0 modifies nothing, modmask=-1 modifies
everything. Bits are numeric starting at 1 for alt, 2
for lat, and so on. Bit 0 is unused.
Example modmasks:
14=alt,lat,lon 16=name 224=azim,elev,roll 1792=r,a,b
2048=color 12288=symbol,size 49152=cone,invert

- Required Data Fields:
L:LAYER - The <layer> refers to the layer number associated
with the type5000 data. If <layer> is negative,
it is the index counting from the last, backward.
(i.e. -1 is the last, -2 is 2nd from the last) If
<layer> = 0, it refers to the marker record and
index is ignored.
L:INDEX - The <index> refers to the record index within the
layer. If <index> is negative, it is the index
counting from the last, backward. If <index> = 0,
it refers to the entire layer.

- Optional Data Fields:
D:ALT - Altitude (Geodetic coordinates of the point)
D:LAT - Latitude
D:LON - Longitude
D:NAME - 8 character label for the point
D:R - Meaning varies and affects interpretation of other
fields as well (see next section)
S:MODMASK- String representation of bit mask (fields that are
listed will be modified). Full list:
|ALT|LAT|LON|NAME|AZIM|ELEV|ROLL|R|A|B|COLOR|
SYMBOL|SIZE|CONE|INVERT|
Flag fields:
L:COLOR - T5 Color number:
1 - Gray (MPlot.T5_INDEX_GRAY)
2 - dark green (MPlot.T5_INDEX_DARK_GREEN)
3 - red (MPlot.T5_INDEX_RED)
4 - yellow (MPlot.T5_INDEX_YELLOW)
5 - green (MPlot.T5_INDEX_GREEN)
B:SYMBOL - 1:DOT, 2:CIRCLE, 3:PLUS, 4:CROSS, 5:UTRI, 6:DTRI
B:SIZE - diameter of symbol in pixels
B:CONE - specifies the type of conic to plot:
-9: uses XGEOPLOTs current/default CONELEV
-1: map cone to intersection with geosphere
0: off - no conic
N: number of sections (rings) along cone centerline
B:INVERT - the cone is inverted, ie. the base of the cone
and the vertex are swapped.
(saved, but not used at this time)

- Optional Data Fields Where Interpretation depends value of R:
[R > 1 or not specified case - WARNING: Currently Unimplemented]:
D:AZIM - Azimuth | Used along with ELEV and ROLL to apply
D:ELEV - Elevation | a coordinate reorientation at the
D:ROLL - Roll | geodetic position. If all are zero, Z
| points up, X points east, and Y north.
| Conics are formed along the Z axis.
D:R - Height of the conic
D:A - Major half angle for the cone
(saved, but not used at this time)
D:B - Minor half angle for the cone
(saved, but not used at this time)
R = -1 case (cone):
D:AZIM - ALT2 | Used along with LAT2 and LON2 to define
D:ELEV - LAT2 | a second point. If any flag data fields are
D:ROLL - LON2 | set, this point is the position the cone is
| originating from (the viewer) and the first
| point is the target location (the point the
| viewer is looking at). If no flag fields
| are set, the points are reversed (this point
| is the target and the first point the
| viewer)
R = 0 case (error ellipses):
D:AZIM - ellipse orientation | An error ellipse is a
D:A - ellipse major radius | special case of a conic.
D:B - ellipse minor radius |

T5TEXT - General Information:
This is a special case of the T5REC used to plot text strings.

INFO = modmask (i.e. bitmask of fields to modify). Note: This
information can also be supplied in String form by
having a MODMASK key in the DATA table (MODMASK Data
Field/Table entry will override INFO).
Only those items whose bit in the modmasks field is set
will be updated when the message is received. For
short, modmask=0 modifies nothing, modmask=-1 modifies
everything. Bits are numeric starting at 1 for alt, 2
for lat, and so on. Bit 0 is unused.
Example modmasks:
14=alt,lat,lon 16=name 32=text 64=color
384=symbol,size

- Required Data Fields:
L:LAYER - The <layer> refers to the layer number associated
with the type5000 data. If <layer> is negative,
it is the index counting from the last, backward.
(i.e. -1 is the last, -2 is 2nd from the last) If
<layer> = 0, it refers to the marker record and
index is ignored.
L:INDEX - The <index> refers to the record index within the
layer. If <index> = 0, it refers to the entire
layer. If <index> is negative, it refers to the
last index.
(NOT IMPLEMENTED: If <index> is negative,
it is the index counting from the last, backward.)

- Optional Data Fields:
D:ALT - Altitude (Geodetic coordinates of the point)
D:LAT - Latitude
D:LON - Longitude
D:NAME - 8 character label for the point
S:TEXT - text string
(saved, but not displayed)
[Also NOT implemented: An "@" in the text is
treated as a CR/LF and the remaining text is
displayed on the next line.]
S:MODMASK- String representation of bit mask (fields that are
listed will be modified). Full list:
|ALT|LAT|LON|NAME|TEXT|COLOR|SYMBOL|SIZE|CONE|
INVERT|

T5LAYER - General Information:
This message is used to modify the structure of a type 5000
layer

INFO = layer number

- Data Fields:
S:ACTION - "DELETE" deletes points indexed P1 through P2
P2 = -1 refers to the last point
<TODO>
"COPY" copies point index P1 to P2
<p2> = 0 appends the point to the end
<TODO>
"CREATE" creates a layer with P1 points
INFO=0 is one after the last layer
L:P1 - first point (1 indexed) / number of points
L:P2 - second point (inclusive & 1 indexed) / <not used>

SETVIEW - General Information:
Set the view

INFO = View:
1: LATLON
2: PERSP <unsupported>
3: SVA <unsupported>
4: SVB <unsupported>
negative: split mode <unsupported>

- Required Data Fields:
D:VAL1 = longitude min
D:VAL2 = longitude max
D:VAL3 = latitude min
D:VAL4 = latitude max

- Optional Data Fields <UNSUPPORTED>
eyelat/lon/dis = viewing lat/lon/distance for perspective mode

Examples:

1. Use T5REC message to add/merge Point 1 with Error Ellipse component on
Layer 2. (uses String MODMASK)

message FUNC=SEND ID=^XGEOID INFO=0 NAME="T5REC" &
DATA={Layer=2,INDEX=1,&
ModMask="ALT|LAT|LON|R|AZIM|A|B|COLOR|CONE|NAME|SYMBOL|SIZE", &
ALT=45.0,LAT=0.5,LON=0.5,R=0,AZIM=15.0,A=300000.0,B=70000.0,COLOR=2, &
CONE=-9, SYMBOL=5,SIZE=3,NAME=PNT1REC}

2. Use T5REC message to add/merge Point 2 with Cone component on Layer 3
(uses String MODMASK)

invoke red nxm.sys.libg.MColor.T5_INDEX_RED
message FUNC=SEND ID=^XGEOID INFO=0 NAME="T5REC" &
DATA={Layer=3,INDEX=2, &
ModMask="ALT|LAT|LON|R|AZIM|ELEV|ROLL|COLOR|CONE|NAME|SYMBOL|SIZE",&
ALT=1000000.0,LAT=1,LON=5,R=-1,AZIM=7.0,ELEV=5.0,ROLL=0.0,COLOR=^red, &
CONE=-9, SYMBOL=5,SIZE=3,NAME=PNT2REC}

4. Use T5REC message to modify all points in the Layer to have Longitude 6.0
and have the color gray. (uses INFO for modmask)

invoke gray nxm.sys.libg.MColor.T5_INDEX_GRAY
message FUNC=SEND ID=^XGEOID INFO=72 NAME="T5REC" &
DATA={Layer=4,INDEX=0,LON=6.0,COLOR=1}

5. Use T5TEXT message to add Point with TEXT/NOTE component on third LayerT5

message FUNC=SEND ID=^XGEOID INFO=-1 NAME="T5TEXT", DATA={Layer=4,INDEX=3, &
ModMask="ALT|LAT|LON|NAME|COLOR|SYMBOL|TEXT|SIZE|INVERT",ALT=55.0,LAT=2, &
LON=2,COLOR=4,SYMBOL=2,SIZE=3,INVERT=1,NAME=PNT3TEXT, TEXT=NoteToDisplay}

6. Use T5LAYER ACTION=CREATE message to create a LayerT5

message FUNC=SEND ID=^XGEOID INFO=1 NAME="T5LAYER" &
DATA={ACTION="CREATE",P1=1}

7. Use T5LAYER ACTION=DELETE message to delete Points 1 to 2 in Layer 1

message FUNC=SEND ID=^XGEOID INFO=1 NAME="T5LAYER" &
DATA={ACTION="DELETE",P1=1,P2=2}

8. Use T5LAYER ACTION=DELETE message to delete Points 4 to the end in the
layer defined as citiesLayer

set L:layNum ^citiesLayer
message FUNC=SEND ID=^XGEOID INFO=^layNum NAME="T5LAYER" &
DATA={ACTION="DELETE",P1=4,P2=-1}

9. Use T5LAYER ACTION=COPY to make Point 1 a copy of Point 3

message FUNC=SEND ID=^XGEOID INFO=3 NAME="T5LAYER" &
DATA={ACTION="COPY",P1=3,P2=1}

10. Use T5LAYER ACTION=COPY to append copy of Point 3 to the existing points

message FUNC=SEND ID=^XGEOID INFO=3 NAME="T5LAYER" &
DATA={ACTION="COPY",P1=3,P2=0}

11. Use SETVIEW to zoom in

set box {MINLON=-1,MAXLON=8,MINLAT=-3,MAXLAT=5}
message FUNC=SEND ID=^XGEOID INFO=1 NAME="SETVIEW" &
DATA={VAL1=^box.minLon,VAL2=^box.maxLon,VAL3=^box.minLat,VAL4=^box.maxLat}

12. Use OVERLAY message to add a file to the current file.

message FUNC=SEND ID=^XGEOID NAME=OVERLAY INFO=3 DATA="temp_xgeo_cities" QUALS={OUTERLIMITS={x1=-100}}

Switches:
/DEBUG - Switch description
/XN - Window title
/MTAG - Switch description
/MSGID - Switch description
</pre>

[[Category:NXM_Explain]]

KEYWORD

2020-04-27T22:05:16Z

ConvertBot: facility for displaying and changing keyword fields in a file header

facility for displaying and changing keyword fields in a file header
<pre>
<file> File to access
<func> Keyword function to perform on file
<name> Keyword name, if applicable for <func>
<value> Keyword value, if applicable for <func>

KEYWORD provides access to the keyword fields in a file header. Keywords
allow unrestricted free-format information storage in a KEY=VALUE format.
Keywords are typically stored in the extended header, which is extensible to
any size.

The main header also has limited keyword storage (88 characters). In general,
the user should use the EXTENDED header for keywords and reserve the MAIN
header keyword space for system use.

Functions:

ADD Add a keyword in the MAIN or EXTENDED header. SET with flags=ADD.
This can result in more than one key with the same name in the same
scope. Multiple keywords can be added at once by specifying a list of
name/value pairs.

KEY <file> ADD NAME=<name> VALUE=<value> [<name2> <value2> ...]

DEL Delete a keyword

KEY <file> DEL NAME=<name>

FGET Create an ASCII text file (<file>) containing the keywords and their
character string values. If <name> is not given, the output goes
to a file called "<file>.key", in the same directory as <file>.
See section ".KEY FILES" below for more on the format of the .KEY file.

KEY <file> FGET <name>

FPUT Alias for FSET.

FSET Replace current keyword entries by the entries in an ASCII keyword
file (<name>). If <name> is not given, KEYWORD looks for a file called
"<file>.key" in the same directory as the <file>. See section
".KEY FILES" below for more on the format of the .KEY file.

KEY <file> FSET <name>

GET Get a keyword or keywords from the MAIN or EXTENDED header.

KEY <file> GET NAME=<name> VALUE=<result name>

Since NeXtMidas 2.5.0, multiple keywords can be retrieved on a single
line.

KEY <file> GET <KEYNAME1> <RESULTNAME1> [<KEYNAMEn> <RESULTNAMEn>...]

LIST List to terminal all keywords matching <name> and their values in
both main and extended headers; or all keywords if <name> is blank

KEY <file> LIST ! list all keywords
KEY <file> LIST <name> ! list only those matching <name>

Since NeXtMidas 2.7.0, <name> can be a wild-card pattern to indicate
that all matching keywords should be listed (e.g. "*EX*" would list
all keywords containing an "EX" in the name, "?VAL" will match any
four-letter keywords ending in "VAL").

KEY <file> LIST <name> ! list keywords matching pattern <name>

Optional flags:
/S - Sort entries before printing to terminal. Note that this will
attempt a "friendly sort" such that "ABC2" comes before
"ABC12", but does not preserve any internal scoping of the
keywords (other than MAIN vs EXT). [Since NeXtMidas 3.3.0]

PUT Alias for SET.

SET Put a keyword in the MAIN or EXTENDED header. This will replace the
named key in the same scope at the original location. Multiple keywords
can be set at once by specifying a list of name/value pairs.

KEY <file> PUT NAME=<name> VALUE=<value> [<name2> <value2> ...]

SVGET [Since NeXtMidas 3.3.0]
Gets state vector keywords from the file. One of the following
modifiers may be included to specify the keyword format (if no
qualifiers are specified an attempt will be made to try all available
formats):
/E - Ephemeral keywords: ETIMn, POSXn, POSYn, POSZn, etc.
/P - Platinum keywords: [prefix].TIME, [prefix]_POS.X,.Y,.Z, etc.
/L - Platinum keywords: [prefix].LON,.LAT,.ALT
/V - Vector keywords: ETIM_VEC, POSX_VEC, POSY_VEC, etc.

Note that the {SVPREFIX=[prefix]} qualifier should be used to set the
prefix as needed for /P and /L modes (if not specified, it defaults to
"EPH" with /P).

The /DT= switch will force all points to have the given time-delta
between them rather than exactly matching the input points. If /DT=0
the time delta will be set based on the keywords (defaulting to 1 min
if the keywords are not evenly spaced). If the output is a Type 5000
file, /DT=0 is implicit unless otherwise specified.

The output will be written to the specified state vector file. If the
file already exists, any data in the file will be overwritten; if not,
a new file will be created. For a BLUE file (.tmp/.prm) the output will
be a Type 5001 file unless the TYPE= qualifier is used to designate an
alternate type. All Type 5000 files will have their QUADWORDS set as
appropriate. Usage:

KEY <file> SVGET/E <svFile>

SVPUT [Since NeXtMidas 3.3.0]
Alias for SVSET.

SVSET [Since NeXtMidas 3.3.0]
Sets state vector keywords into the file. Must include one or more of
the following modifier switches indicating the state vector format:
/E - Ephemeral keywords: ETIMn, POSXn, POSYn, POSZn, etc.
/P - Platinum keywords: [prefix].TIME, [prefix]_POS.X,.Y,.Z, etc.
/L - Platinum keywords: [prefix].LON,.LAT,.ALT
/V - Vector keywords: ETIM_VEC, POSX_VEC, POSY_VEC, etc.

Note that the {SVPREFIX=[prefix]} qualifier should be used to set the
prefix as needed for /P and /L modes (if not specified, it defaults to
"EPH" with /P).

Usage:

KEY <file> SVSET/E <svFile>

TCGET [Since NeXtMidas 3.3.0]
Gets time-code keywords from the file. Must specify one input and one
output modifier from following:
Input Options:
/X - X-Midas style keywords: TC_WHOLE_n, TC_FRAC_n, etc.
Output Options:
/I - ICE packets

KEY <file> SVGET/X/I <ice_pkt_file>

TCPUT [Since NeXtMidas 3.3.0]
Alias for TCSET.

TCSET [Since NeXtMidas 3.3.0]
Sets time-code keywords in the file. Must specify one input and one
output modifier from following:
Input Options:
/I - ICE packets
Output Options:
/X - X-Midas style keywords: TC_WHOLE_n, TC_FRAC_n, etc.

Usage:

KEY <file> SVSET/I/X <ice_pkt_file>

TGET Create a Results Table (<name>) containing the keywords and their
values. If <name> is not given, the output goes to a Results Table
which uses the root of <file> for its table name (e.g. MYFILE for
"myfile.prm"). NOTE: For SCOPED Keywords, only the values in the
final SCOPE will appear in the Results Table when the /SCOPE switch
is NOT used.

KEY <file> TGET <name> ! Create a "flat" table

or

KEY/FLAT=F <file> TGET <name> ! Create a table with INNER
! and EXTENDED inner tables

TGET/F Similar to TGET except that keywords are written to a .tbl file
(<name>) rather than a table in the results table.

KEY <file> TGET/F <name> ! Create a table file

or

KEY/FLAT=F <file> TGET/F <name> ! Create a table file with
! INNER and EXTENDED inner tables

.KEY FILES
The .KEY file used by FGET and FSET have one keyword name/value pair per line.

The format is:

NAME=VALUE ! single "=" for main header
NAME==VALUE ! double "==" for extended header

"NAME" can start in any column. "VALUE" is interpreted literally (no quotes
needed, space retained) and stored by default in ASCII. NAME can be preceded
by a type character as with results parameters, to typecast the value as
numeric (with binary storage). The special type "S[<len>]" means an ASCII
string of length <len>; this is a way of forcing/capturing trailing spaces.
Keyword arrays are represented by type-casting to numeric and separating the
keyword values with commas. A "&" at the end of the line forces continuation
to the next line. Blank lines or anything after a "!" are interpreted as a
comment and ignored.

To load all key/value pairs into the extended header, use the /EXTONLY switch.
This is useful for loading a 3rd party key=value text file into the
extended header without having to change = to == in the text file.
Use this switch to revert to behavior prior to NeXtMidas 3.1.2.

KEYWORD SCOPE
Keyword "scope" refers to the keyword storage range actually visible at any
given time. By default, the entire extended header is visible.

Special scope syntax:
* To access keywords in the main header, use /SCOPE=MAIN.
* To access keywords at the start of the EXTENDED header, use /SCOPE=EXT.
* To INCLUDE the scope keyword in your output use /SCOPE=TAG=VALUE
* To EXCLUDE the scope keyword in your output use /SCOPE=TAG-=VALUE
* To EXCLUDE the scope keyword but INCLUDE the next use /SCOPE=TAG+=VALUE

Examples:
1. Create a file, put a keyword in it and extract it.
nM> header/create junk.tmp
nM> key junk.tmp PUT mykey "INITIAL VALUE"
nM> key junk.tmp GET mykey myval
nM> res myval
13S: MYVAL = INITIAL VALUE

2. Replace the value of the keyword inserted above with a new value
nM> key junk.tmp PUT mykey "NEW VALUE"
nM> key junk.tmp GET mykey myval
nM> res myval
9S: MYVAL = NEW VALUE

3. Scope with multiple keywords. Put the DUMMY keyword in twice and
Now use scope to get the second DUMMY keyword.
nM> header/create junk.tmp
nM> keyword junk.tmp PUT DUMMY DUMMY1 TAG2 VAL2 NODE MYNODE
nM> keyword junk.tmp ADD DUMMY DUMMY2
nM> keyword/scope="TAG=NAME,NODE=MYNODE" junk.tmp GET DUMMY out
nM> res out
6S: OUT = DUMMY2

NOTE: Using () around the scope keyword works as well.
nM> keyword/scope=(TAG=NAME,NODE=MYNODE) junk.tmp GET DUMMY out

4. Special syntax for /SCOPE. For a file with the keyword list:
TIME==12:00
FREQ==31e6
AMPL==1.1
TIME==13:00
FREQ==32e6
AMPL==1.2
TIME==14:00
FREQ==33e6
AMPL==1.3

KEY/SCOPE=TIME=13:00
(includes TIME=13:00, FREQ=32e6, and AMPL=1.2 in scope)

KEY/SCOPE=TIME-=13:00 ! "-=" means skip /scope keyword
(skips TIME=13:00, includes FREQ=32e6 and AMPL=1.2 in scope)

KEY/SCOPE=TIME+=13:00 ! "+=" means skip /scope keyword, include next
(skips TIME=13:00, includes FREQ=32e6, AMPL=1.2, TIME=14:00)

5. PUT a "D_VEC" keyword containing a vectorized list/array of doubles
nM> keyword junk.tmp PUT "D_VEC" (1.1,2.2,3.3,4.4,5.5)

PUT a "I_VEC" keyword containing a vectorized list/array of short integers
nM> res I:data (1,2,3)
nM> keyword junk.tmp PUT "I_VEC" data

6. ADD multiple keywords using a single command
nM> keyword junk.tmp ADD KEY1 "1st-Val" KEY2 "2nd-Val" THIRDKEY "3rd-Val"

Switches:
/DT= - Override the time delta used for SVGET.
/EXTONLY - FPUT or FSET only. Load all key/value pairs from .KEY file into the
extended header. (Since NeXtMidas 3.1.2) [DEF=FALSE]
/FLAGS= - Keywords flags/settings to use. [DEF=none, NoAbort for FUNC=LIST]
NoAbort - Try to continue when an invalid keyword block is found.
See also nxm.sys.lib.Keywords.flagsList. (Since NeXtMidas 3.1.1)
/FLAT - TGET or TGET/F only. Generate a flat table or a table with
inner tables MAIN and EXTENDED [DEF=TRUE]
/LEGACYLIST - For LIST only, use old listing format prior to NeXtMidas 3.3.0
that has paging enabled. (Since NeXtMidas 3.5.4) [DEF=FALSE]
/PREFIX= - Sets the prefix used with Platinum keywords in SVGET and SVSET.
/SCOPE= - restricts range of keywords currently visible.
/SCOPE=MAIN will GET or SET in the main header.
/SCOPE=EXT will GET or SET at the start of the extended header.
/SCOPE=ALL will GET or SET in the main or extended header.
This is the equivalent of a space " " in X-Midas.
/WARN - State switch for warnings [DEF=TRUE]

See Also: STATUS, nxm.sys.lib.Keywords

</pre>

[[Category:NXM_Explain]]

REPORT

2020-04-27T22:05:16Z

ConvertBot: turns on/off reporting of INFO/WARN/ERROR messages

turns on/off reporting of INFO/WARN/ERROR messages
<pre>
<FUNC> - Function = ON|FLUSH|OFF|SAVEOFF|AUTOSAVE
<FILE> - Logging file name for ON function [DEF=midas_log.mlog]
NOTE: any filename extension is currently overridden with .mlog.

Reports Midas INFO/WARNING/ERROR messages to a display (terminal) and/or file.

The log file is saved as a Type 3000 of NH format with following sub-records:
1. SubRecord Name=TIME Format=3A Offset=0 - STD Date/time of message
2. SubRecord Name=TYPE Format=1A Offset=24 - e.g. WARN, INFO, ERROR, etc.
3. SubRecord Name=TEXT Format=XA Offset=32 - text of message
4. SubRecord Name=FROM Format=2A Offset=112 - source of message

Warning: Interactive commands's terminal output will be NOT be displayed when
logging to a file is enabled, because it goes to the log file.

Examples:

</pre>

[[Category:NXM_Explain]]

EXIT

2020-04-27T22:05:15Z

ConvertBot: exit from NeXtMidas environment back to operating system

exit from NeXtMidas environment back to operating system
<pre>
EXIT returns to the operating system. After EXIT, you can re-enter the
NeXtMidas environment by typing "nm" at the operating system prompt. If you are
really done with a session, type "nm end" at the operating system prompt, to
flush history buffer and delete any NeXtMidas symbols tables (this includes the
"nmsf_.." file a NeXtMidas session puts in the user's home directory). Then
restart NeXtMidas with an nmstart.

</pre>

[[Category:NXM_Explain]]

ABSCISSA

2020-04-27T22:05:15Z

ConvertBot: alters abscissa fields in a Midas data file header

alters abscissa fields in a Midas data file header
<pre>
<file> Name of input file
<start value> New abscissa start value
<increment> New abscissa increment value

DEPRECATED: Use HEADERMOD

<increment> is the double precision increment between consecutive points or
number of current abscissa increments (integer) by which current start abscissa
should be changed.

ABSCISSA accepts any type class or data format. The header is not modified if
its write protect field is set to TRUE.

</pre>

[[Category:NXM_Explain]]

DEMUX

2020-04-27T22:05:15Z

ConvertBot: decomposes complex file into separate real and imag output files

decomposes complex file into separate real and imag output files
<pre>
<COMP> - Type 1000 COMPLEX input file
<REAL> - Real part output file
<IMAG> - Imaginary part output file

Decomposes a <COMP> file into separate <REAL> and <IMAG> files. The
following rules apply:

* Output files are the same type as the input.

Note: The default /TL is the variable bufSize defined in nxm.sys.lib.Primitive.

Switches:
/TL - The number of elements to be read each process loop [DEF=32768]

See Also: MUX, nxm.sys.lib.Primitive

</pre>

[[Category:NXM_Explain]]

TIMER

2020-04-27T22:05:15Z

ConvertBot: implements various timer functions

implements various timer functions
<pre>
<FUNC> - Name of the function (ON,OFF,SET,ELAPSE) [DEF=ON]
<LABEL> - Name of results parameter to receive timer information

The timer modes are:
1) elapsed time per command
2) elapsed time over several commands
3) resource usage per primitive.

FUNCTIONS:
ON - TIMER ON
turns on the "elapsed time per command" function. The image
activation time and the execution time for an intrinsic or primitive are
shown in "wall clock" (not CPU) seconds. System loading may affect this
value. These times are displayed on the terminal and cannot be recorded in
results parameters.

OFF - TIMER OFF
Turns off the timer

SET - TIMER SET
turns on the "elapsed time over several commands" function, useful
for timing a macro or a block within a macro. Again, "wall clock" (not CPU)
seconds are displayed, so system loading may affect this value as well.
TIMER SET is used to "start the stopwatch", and TIMER ELAPSEd is used to
report the time to <LABEL>. TIMER ELAPSED reports elapsed time and continues
timing.

ELAPSEd - TIMER ELAPSE <LABEL>
Used to report the time to <LABEL> since SET. Reports elapsed time and
continues timing.

Examples:

Messages: NONE

Switches: NONE

</pre>

[[Category:NXM_Explain]]

FORALL

2020-04-27T22:05:14Z

ConvertBot: performs a Midas command for a list of items or counter index

performs a Midas command for a list of items or counter index
<pre>
<file/count> List filename or counter string
<command> Midas command to perform

FORALL performs the named command for each item in a list file or for each
increment of a count variable. If either argument is left blank, it prompts
for them.

<command> specifies the command to execute for each item, using a # everywhere
the current item value should be substituted.

If the <file/count> parameter includes an "=" sign, FORALL expects a count
string of the form:

#=START:END;INC

where START is the start count, END is the end count, and INC is an optional
increment. <command> is executed for each count in the loop progression, with
the current iteration number substituted for each instance of "#". For example,

nM>res n 0
nM>forall #=1:21;2 calc n n # +

sums all odd integers from 1 to 21. Counts and increments are not required to
be integers.

If the <file/count> parameter does NOT include an "=" sign, FORALL expects the
name of a file containing a list of strings or numbers. It loops through each
element of this file, substituting the indexed item wherever "#" is found in
<command>. Often the file will be generated by a FILES/F or MENU/F command:

nM>files/f t* ,,1
nM>forall FILES status #

will display the status of every file beginning with T.

To see the DEFAULTS of each Intrinsic or Macro:

nM>menu/f ,,, IM
nM>forall MENU syntax #

NOTE: When using FORALL within a macro, note that its arguments are treated
like arguments to operating system commands. The reason is that it is
unknown what kind of command you may be giving FORALL. Thus local result
parameter translation will only occur if you use the caret (^) to
indicate a result substitution. For example:

mymacro L:number

forall #=1:number ramp r# ! This will NOT work right
forall #=1:^number ramp r# ! This WILL work correctly

endmacro

NOTE: <command> cannot invoke GOTO or CALL. This is because FORALL is itself
a macro with it's own macro level and local results parameters. (The
labels, procedures and subroutines of the calling macro are not visible
to it.) If you need to call a procedure repeatedly within a macro use
the DO, FOREACH or WHILE commands.

Switches:
/ECHO - Shows each iteration of the command before performing it.

</pre>

[[Category:NXM_Explain]]

RMIF

2020-04-27T22:05:14Z

ConvertBot: Remote Midas InterFace handles communication with remote processors

Remote Midas InterFace handles communication with remote processors
<pre>
<PORT> - UDP port number for local node (may be output) use PORT=-1
to use any available local port (NeXtMidas only).
<PROPS> - Property list to export _:result|q:message|_pipe
<REMOTE> - Host address and port of remote connection...
NeXtMidas uses: {ID=<remoteId>,HP="<host>:<port>"}
X-Midas uses: <host>:<port>
<ITEMS> - List of remote properties to connect to ("|" separated list)
<REMOTEN> - Remote connection #2,...
<ITEMSN> - List of remote properties #2,...

Since there are X-Midas (C/FORTRAN) and NeXtMidas (Java) versions of this
primitive, (N) and (X) are used to indicate NeXtMidas or X-Midas only
capabilities, respectively.

This command, when put in a macro, allows another X-Midas or NeXtMidas macro
access to any of the items listed. These items may be messages, results
parameters, pipes, or files. The remote connections will always have read
access to any parameter available through the results table.

The /HTTP switch (NeXtMidas only) starts an Http server on the same port for
application status, debug, control, and file serving through a web browser.
For example, on the local node, the URL might be: http://localhost:9000

The protocol is modeled after Remote Method Invocation (RMI) - a distributed
object model for the Java programming language. The underlying socket transport
is UDP. A reliable data protocol (RDP) is implemented by RMIF to "guarantee"
delivery of messages (configurable with the RETRY attribute).

The RMIF protocol definition allows for data packet formats: RAW, BINARY, ASCII,
or XML. Currently only RAW is used.

The port number, along with the local node name, serve to identify this
interface within a subsystem. When this routine sends packets to remote nodes,
the local address is attached to the packet, allowing the recipient to respond
directly to the sender.

If the specified port is already in use and the /PRANGE switch is specified,
RMIF will search for a free port. In this case the actual port number will be
written to the first results parameter (assuming that an ASCII input is
specified, if the input is numeric, this step is skipped).

All results table entries are available to the local interface upon request
using the SET and GET messages. The properties argument is a "|" separated
list of results, messages, pipes, or files that this interface can serve to
remote application interfaces without queries. Once a remote interface issues
an OPEN on one of these properties, updates will be sent whenever new data is
available, until a CLOSE message is issued. The list of properties is made
available through the GETKEYNAMES message allowing a macro to publish
properties available to be displayed or manipulated by client GUI's.

The pairs of remote node:port and "|" separated items list define client
connections that should be automatic and permanent. Remote properties that are
specified here are automatically reOPENed if the remote node is temporarily
unavailable for any reason (death, network, reboot, ...)

Each remote connection can have differently tuned parameters using the Port
Parameter Table. The /PPT={table} switch defines the default for all new
connections. See the switches section for specifics.

Clients that have OPEN channels, regularly ping the remote server to verify
health and status. The servers also ping the clients. This ping interval can
be set with the /TIMEPING switch. The /TIMEOUT switch specifies how many
seconds to wait for a response before closing the remote channels. The PINGs
are still issued to poll for life, but channels are CLOSED. When the remote
node starts responding again, the listed channels are reOPENED.

For X-Midas clients, the /RECONN switch allows RMIF to try to reconnect to
servers that disconnect and return. All pipes must be the same format between
the two instances since X-Midas can't change pipe headers on the fly. The client
decided that the server has disconnected if it doesn't respond to a PING packet
within the timeout or if no pipe data has been transferred during this time. The
latter case could happen if the server were recycled between two PINGs. If the
connection has been dropped and you don't want to wait for the timeouts, you can
send an OPEN message (X-Midas client only) to force a reconnect.

LIMITATIONS
===========
Packet Size:
Note that RMIF has an internal 32 KiB buffer and, while it can transmit
piped data with frame sizes or record lengths greater than this (by
splitting the frames into multiple packets), they are subject to misalignment
if any packets are lost. There is no internal means to realign the data, so
use of RMIF with large buffer size is not recommended.

The 32 KiB limit comes from the max size of a IP packet used for UDP. The IP
packet includes IP header, UDP header, RMIF header (fixed), RMIF adjunct
header (internal use only). The remaining space is available for RMIF data.
Buffer sizes slightly larger than 32KiB will often fit, but this should not
be counted on.

RMIF uses RDP (over UDP) for sending control messages (this includes any
messages sent via the macro). Consequently, it is subject to the same 32 KiB
limitation.

RMIF was designed to transmit plot data and small control messages associated
with the same data. RMIF is not intended as a means of reliable transport for
other types of data (such as database queries, imagery, HTML, etc); there are
many other protocols (TCP, HTTP, FTP, SCTP, etc) that are designed for this
type of application.

Network Bandwidth:
The network bandwidth along with the max read/write rate limits the actual
transmission rate of the UDP packets. If too many packets are sent at once,
some of them will be lost.

RMIF uses RDP to counteract this by retransmitting the lost packets, but this
can only do so much (a saturated network is likely to drop many of the packets
on retransmit).

The WINDOW= (in the /PPT= table) controls the maximum number of RDP packets
outstanding (sent, but not yet receipted). RMIF will buffer outgoing packets
when the window fills up. This prevents RMIF from over-saturating the network
with its own packets. Making the window too large (even sizes >32 can be "too
large" on many networks) will result in RMIF saturating the network which
then causes the RMIF packets to be lost.

The RETRY= parameter in the /PPT= table controls the number of retries that
will be attempted. If /WINDOW= is too large, increasing RETRY= only makes a
bad problem worse.

Network Latency:
Increasing WINDOW= (in the /PPT= table) on networks with high latency will
improve performance since it allows more outstanding packets to be in transit
at the same time.

Faulty Network:
Increasing RETRY= (in the /PPT= table) on networks with a high rate of packet
loss or corruption will improve performance since it permits more transmission
attempts in the event of a lost/corrupted packet. (Remember, if loss/error
rate is 10%, the odds of a loss/error on retransmit are also 10%.)

Faulty Networks With High Latency:
This is what RMIF was designed for... the WINDOW= and RETRY= give users the
control they need to "tune" RMIF so that it will run well on these networks.
Just be careful not to oversaturate the network.

COMPRESSION (X-Midas or NeXtMidas server, NeXtMidas clients)
============================================================
Compression is meant to be used on pipes destined for plotting. Compression
only works on pipes with FIXED-POINT SB data. When using the NeXtMidas PLOT
command, the plot's rmif ID may be set to allow information to be sent so that
RMIF will compress the data to fill the plot screen.

There are two types of compression, ONLY ONE of which is currently supported:

1. Data - TBD
There are hooks in place for this type of compression but it it not yet
implemented. This is completely recoverable non-lossy data compression
(like zip).

2. Plot - This is commonly used for plotting.
In this mode, RMIF automatically chooses one of two modes based on the
number of points per pixel.
a.) BAND ( >= 3pts/pixel )
Computes the upper and lower bounds giving a compression of >=1.5 times.
For example, a 2k length frame would compress ~7 times in a plot window
300 pixels wide.
b.) PACK ( < 3pts/pixel )
Computes the MAX of first point, and then 4bit deltas giving a compression
of ~2x.
When zoomed, the data not visible will also be thrown out.

COPYING FILES from an RMIF server(N)
====================================

Files may be transfered from an RMIF server to a client using HTTP or MFTP, the
Midas File Transfer Protocol. For example,

nM> noop/gpw http://<host>:<port>/Files/<aux>/remotefile.tmp localfile.tmp
or
nM> noop/gpw mftp://<host>:<port>/Files/<aux>/remotefile.tmp localfile.tmp

RMIF can find and transfer any MIDAS file in its' current AUX path. To specify
the AUX, use the AUX qualifier or use the syntax:

nM> noop/gpw http://<host>:<port>/Files/<aux>/remotefile.tmp localfile.tmp

the MFTP protocol has additional qualifiers to tune the performance.
PKTRATE = target bytes per second to transfer over the link
PKTLEN = length in bytes of individual UDP data packets (typically 1K - 8K)
PKTTO = timeout in seconds for request responses

For example:

nM> noop/gpw mftp://remotename:9000/Files/DAT/world.prm{PKTRATE=1e5,PKTTO=3}
localfile.tmp

See library help on MFTP for more information.

Using an embedded server with the /HTTP switch
==============================================
If RMIF is run with the /HTTP switch, controls, files, and Queries can be
accessed from a remote node with the following syntax:
* http://<server:port>/Controls --> Returns HTML
* http://<server:port>/Files/<AUX>/remotefile.prm
* http://<server:port>/Query --> Returns HTML

For instance, to access a file on the server's DAT aux from a client,
nM> noop http://<server:port>/Files/DAT/remotefile.prm localfile.prm

To see an example of how this can be used run:

nM> sd360/server

then point your browser to http://localhost:9000/ and from there you will have
links to files, controls and more.

Messages: (X) = X-Midas Only, (N) = NeXtMidas Only, otherwise valid for both
In X-Midas, SETKEY, ACKKEY, GETKEY, and RETKEY are homogeneous messages
consisting of one 40 char address followed by pairs of 40 char keynames and
40 char keyvalues. The KEYMSGSTRUCT struct in rmif.inc maps this message
data. The NDATA field is dynamic depending on the number of keys per
message. Namely NDATA=1+2*NKEY. In NeXtMidas, these 4 messages are replaced
by sending a SET, ACK, GET, or RET message to the ID of the remote
itself. The system knows to route it through the RMIF connection.
In NeXtMidas, when RMIF receives a SET, ACK, GET, or RET message that has a
MSGNAME key in the data table, it's value is used as the message name to
send the data (with the MSGNAME key/value removed from the table) to the
upper level (i.e. the macro) instead of the SET, ACK, GET, or RET name.
In X-Midas, the ADDR, KEYS, PROPS, and PING messages uses the INFO field to
represent the index of the remote to send the message to. Valid input values
are 1 to MAXREMOTE(32).

NOTE: Any messages to a remote must be with FUNC=SEND (not SENDW). Messages to
the RMIF primitive can be with either SEND or SENDW. (N)

When sending messages to RMIF, the only why to know that it has been
fully processed (client-side and server-side) is via the corresponding
acknowledgments sent back to the macro. For example, an OPENED message
is the acknowledge for the OPEN message. See below for details.

ACK - Acknowledges a SET message. An ACK message sent to RMIF with a null
remote value will notify all remotes of the attribute change.
(X-Midas uses "ACKKEY" instead of "ACK")

ADDC - Add a channel to a property on a remote. (N)
ID=<remote>
NAME="ADDC"
INFO=<channel number, -1 for next available number>
DATA=<property to monitor or "Q:ACK">
A "channel" is a real-time attribute (a pipe or server-side change
to a result). If "Q:ACK" is specified, this setups a channel to
receive all ACKs from the remote (server) that are sent directly to
this RMIF or to all it's remotes (clients). Even though a table-like
syntax maybe be used when specifying a pipe to map (e.g.
"{_clientPipe=_serverPipe}"), RMIF treats the message data as a
string. Examples:

nM> message send ID=RID NAME="ADDC" INFO=1 &
DATA="{_clientPipe=_serverPipe}"
nM> message send ID=RID NAME="ADDC" INFO=2 DATA="SFREQ"

Note: This message should only be sent after an OPENED message is
received from the remote in the processMessage procedure
(i.e. it should not be send between PIPE ON ... PIPE OFF).

ADDC/M - Add a channel in multi mode to a property on a remote. This allows
multiple remotes writing into a single pipe. (N)

ADDR - Create a reference to an RMIF process on a remote machine.
ID=<RMIF ID>
NAME="ADDR"
INFO=<desired remote index number; 1-MAXREMOTE> (X)
DATA=<Table with properties for the remote to address> (N)
ID = ID to name created remote (good idea to keep unique).
HP = Host:Port string of remote, e.g. the Internet
address (IP/hostname and PORT) of the remote machine.
<ARGS>=1 (X)
<TYPE>=S[40] (X)
<VALUES=remote address IP/hostname:port string or hexadecimal
string of IP address/port (in network byte order). (X)

Note: The connection is not established until an OPEN message is
processed.
In X-Midas, care should be taken for the specified remote index,
otherwise an existing remote at that index may be overridden.

CLOSE - Close the connection to a remote. (N)
A CLOSED message acknowledges this request.
Note: An OPEN message to the same remote <Host:Port> should not be
sent until the CLOSED message is received, otherwise the new
remote may receive the server's acknowledgment to this remote
(i.e. it gets a CLOSED message that was still in transit on
the network to RMIF).

CLOSE/R - Close the connection to a remote and remove it from the table. (N)

DELC - Delete a channel to a property on a remote. (N)
ID=<RMIF ID>
INFO=<if > 0, channel number>
DATA=<else, name of exported property>

GET - Is used to request one or more key=value pairs. (X-Midas uses
"GETKEY" instead of "GET"). A RET message acknowledges this request.

KEYS - Requests a list of properties to be returned for specified remote.
ID=<remote> (N)
or
ID=<RMIF ID> (X)
INFO=<desired remote index number; 1-MAXREMOTE> (X)

MODIFY - Modifies parameters of an open channel (usually used for plot
compression). (N)
NOTE: Compression only works on pipes with fixed-point SB data.
nM> message FUNC=send ID=RID NAME=MODIFY &
DATA={PROPERTY=_serverPipe,COMP=2,PLOTWIDTH=200}
xM> rmsg send <addr> MODIFY,,
{PROPERTY=_serverPipe,COMP=2,PLOTWIDTH=200}
sets compression on the pipe for a 200 pixel wide plotter

nM> message FUNC=send ID=RID NAME=MODIFY &
DATA={PROPERTY=_serverPipe,TRIM1=plot.x1i,TRIM2=plot.x2i}
xM> rmsg send <addr> MODIFY,,
{PROPERTY=_serverPipe,TRIM1=plot.x1i,TRIM2=plot.x2i}
sets compression for a plot zoom window from frame index x1i to x2i

OPEN - Open a connection to a remote given the SERVER host and port.
An OPENED message acknowledges this request.
nM> message send RMIFID ,, OPEN ,, {ID=<rid>,HP=<host>:<port>}

Note: Since <rid> is not passed to the server side, the RMIF server
defaults the remote's message ID to "REMOTE". In most cases
it is not important to uniquely identify a client since the
server typically treats all clients the same (given that they
have the same channels open). Since NeXtMidas 2.5.3 it is
possible to specify an alternate ID for each remote client.
This is done by setting the remote's id to desired value when
processing the OPEN message in the server macro, for example:
nM> set msg.data.id "MY_REMOTE"

RADDR - Remove an address from RMIFs table of remotes. (N)

RET - Acknowledges a GET message. (X-Midas uses "RETKEY" instead of "RET")

RPKT - Is a more direct means to SEND or RECV an RMIF packet with less
restrictions (see nxm.sys.exp.rmsg.exp). This is for X-Midas only.
If the address field is blank, the packet is sent to all open
remotes ONLY if the /RECONN switch is set (this was done to
preserve the legacy, pre-/RECONN switch behavior).

PAUSE - Pause, specify the time (seconds) in the info entry. (X)

PING - Request a PING to be sent to specified remote.
ID=<remote> (N)
or
ID=<RMIF ID> (X)
INFO=<desired remote index number; 1-MAXREMOTE> (X)

PROPS - Same as KEYS message.

SET - Is used to set one or more key=value pairs. (X-Midas uses "SETKEY"
instead of "SET"). An ACK message acknowledges this request.

Examples:
1. X-Midas server setup:
rmif/pktmsg port _mypipe|myresult

2. NeXtMidas server setup with web server:
rmif/http port sfreq|_waveb /ppt={RETRY=2,TIMEPING=3}

3. NeXtMidas client setup with web server:
rmif/http/prange=5 port

4. NeXtMidas opening a connection to a remote server:
set remote "<host>:<port>"
message send RMIF ,, "OPEN" ,, {ID=XM,HP="^remote"}
message send XM ,, "ADDC" 1 {_WAVEB=_WAVEB}
message send XM ,, "ADDC" 2 "Q:ACK"

.... later in processMessage handler - sync up
if msg.name eqs "OPENED" then
message send XM ,, "GET" ,, {SFREQ=?,CFREQ=?}
endif

5. NeXtMidas sending a message to an un-opened remote:
message send "RMIF" ,, "ADDR" ,, {ID=RID,HP="^rhost:^rport"}
message send "RID" ,, "SET" ,, {FREQ=123,RATE=2345}

6. NeXtMidas replying to a GET message from a remote:
if msg.name eqs "GET" then

... fill in values for entries in the msg.data table
message send "REPLY" msg "RET"

7. NeXtMidas replying to a SET message from a remote:
if msg.name eqs "SET" then

... validate entries in the msg.data table and perform necessary actions
message send "REPLY" msg "ACK"

8. NeXtMidas client to monitor all Q:ACK (channel) on remote host:port
rmif -1 ,, {ID=REMOTE,HP="^host:^port"} "Q:ACK"

Many examples exists as part of the RMIF test cases, see:
$NMROOT/nxm/sys/test/rmif/test_rmif_*.mm

Switches: (X) = X-Midas Only, (N) = NeXtMidas Only, otherwise valid for both
/AUXLIST=l - List of AUXs to make available under
"http://host:port/Files/<AUX>/<filename>". By default all
AUXs in AUX.READ are listed (same as /AUXLIST="*"). Use
/AUXLIST=null to disable. [Note that for to backwards-
compatibility with older apps, the defaults for this
switch differ between RMIF and HTTPSERV.] (N)
/DEVICE=dev - Performs a network interface lookup to resolve server IP address
to bind on based on a network device name (e.g. eth0, eth1.101).
This switch takes precedence over the /HOST switch. (N)
Since NeXtMidas 3.1.2.
/HOMEPAGE=p - Homepage location for HTTP web server (p = path). [This
matches HTTPSERV.] (N)
/HOST=ip - Sets the host IP address to bind on.
/HTTP - Start HTTP server for application status, debug, and file
serving. Note that /AUXLIST= and /HOMEPAGE= have no affect
if this switch is not specified. (N)
/KEEPADJ - Keep adjunct header with the data. (X)
/KEYMSG - Convert SET,GET,RET,ACK packets to SETKEY, GETKEY, ... messages.
This allows the macro to take special action when a remote
interface sends or requests information instead of letting
RMIF handle this 'behind the scenes'. (X)
/LOG=fname - Logs all control activity to text file
/MSGID=id - The ID to process messages from the remote nodes (usually 1 in
X-Midas, usually MAIN in NeXtMidas). [DEF=MAIN in NeXtMidas]
/PAUSE=s - Time (sec) to pause at the end of idle loop (DEF=Mc.pause) (X)
/PKTMSG - Convert SET,GET,RET,ACK packets to RPKT messages. This is the
default if /MSGID is specified. (See nxm.sys.exp.rmsg.exp.) (X)
/PPT={tbl} - Port Parameter Table for tuning connections. (N)
Most setable attribute may be included but some typical
parameters are: RETRY,TIMEPING,TIMEOUT
TIMEDROP is not yet implemented in NeXtMidas.
/PRANGE=n - Range of port numbers above <port> to use if already allocated.
/RECONN - Reopens pipes after server recycle. (X)
/REOPEN=NO - Don't reopen same named pipes on client side when reconnecting.
This keeps plotters from resetting but should only be used if
the application is reconnecting to pipes with similar headers.
(N)
/RETRY=n - Set maximum number of retries (default=5). (X)
Use the /PPT switch for NeXtMidas.
/STATUS=lbl - Writes the current number of remote connections to the result
/TIMEDROP=s - Timeout to drop efforts to reconnect (default=600). (X)
Use the /PPT switch for NeXtMidas.
/TIMEOUT=s - Timeout (in seconds) to declare link down (default=15). (X)
Use the /PPT switch for NeXtMidas.
/TIMEPING=s - Timeout (in seconds) between pings (default=4). (X)
Use the /PPT switch for NeXtMidas.
/VERBOSE - Set verbose option.
/WINDOW=n - Set maximum window of messages to a given remote before RDP will
not send. (X) Use the /PPT switch for NeXtMidas.

See Also: nxm.sys.net.Rmif, SD360, nxm.sys.test.test_rmif.mm, HTTPSERV

</pre>

[[Category:NXM_Explain]]

TIMEX

2020-04-27T22:05:14Z

ConvertBot: perform various time transfer and conversion functions

perform various time transfer and conversion functions
<pre>
<in> Input time specification
<out1...outn> Output time specifications

Keyword Only Parameters:
[ROUND] - See below for description
[INFILE] - See below for description
[INACQ] - See below for description
[INQUAD] - See below for description

This intrinsic performs a number of time transformations with support for
multiple output formats in a single call.

Input:
The input time specifications are:
NOW - the current system or CPU time (J1950)
SSM - the seconds since midnight (this is similar to the
SECNDS() function in Fortran)
DAY - the beginning of the current day
<time> - any valid time specifier:
o Time object
o "yyyy:mm:dd::hh:mm:ss"
o "<sec>" (seconds since 01-JAN-1950)
o "(<sec>)" (seconds since 01-JAN-1950)
o "(<wsec>,<fsec>)" (seconds since 01-JAN-1950)
o "<time string>" (as specified by /INFMT=)
ROUND=<seconds> - round the output to the specified number of sec
INFILE=<filename> - the timecode field in a file
INACQ=<filename> - TBD (the ACQDATE/ACQTIME keywords in a file)
INQUAD=<filename> - the quadword epoch fields

Output:
The output time specifications include (see nxm.sys.lib.Time for details):
TERMINAL - Displays time in the current terminal display
<resname> - Saves Time object in <resname>

FILE=<filename> - Stores time in the timecode field of a BLUE file
ACQ=<filename> - TBD (the ACQDATE/ACQTIME keywords in a file)
QUAD=<filename> - Stores time in the quadword epoch fields of a
Type 5000 BLUE file (for ECR reference frame GHA)

YEAR=<resname> - year (1950,...)
MONTH=<resname> - month of year (1..12)
MONTHNAME=<resname> - month of year (January,...)
MONTHTRIGRAPH=<res> - month of year (JAN,FEB,...)
DAY=<resname> - day of month (1..N)
HOUR=<resname> - hour of day (0..23)
MINUTE=<resname> - minute of hour (0..59)
SECOND=<resname> - second of minute (0..59)
DAYOFWEEK=<resname> - day of week (1=SUN,2=MON,...,7=SAT)
DAYOFWEEKNAME=<res> - day of week (Sunday,...)
DAYOFWEEKTRIGRAPH=<r> - day of week (SUN,MON,...)
JD=<resname> - Julian day (or JUL=)
(NOTE: Julian Date Epoch is 12:00 1 Jan 4713BC)
MJD=<resname> - Midas Julian day (since J1950)
(NOTE: NOT the Modified Julian Day defined by SAO.
Modified Julian Day = Midas Julian Day + 33282.0)
MJS=<resname> - Midas Julian second (since J1950)
SEC=<resname> - seconds since 00:00 1 Jan 1950 (same as MJS)
YIS=<resname> - year in seconds
DOY=<resname> - day of year (0..364/365)
SOY=<resname> - seconds of year
SOD=<resname> - seconds of day
FOD=<resname> - fraction of day (0.0 to 1.0)
GHA=<resname> - Greenwich hour angle (in radians)
WSEC=<resname> - Whole Seconds since J1950
FSEC=<resname> - Fractional Seconds since J1950
LEAPYEAR=<resname> - Indicates if it is a leap year (true/false)

Rounding:
The input time can be rounded to a desired precision before output processing
via the ROUND=<precision> parameter. This parameter causes the input time to
be rounded to the nearest <precision> seconds. For example: ROUND=1 rounds to
nearest second, ROUND=1:00:00 to the nearest hour, and ROUND=1e-3 rounds to
the nearest millisecond. Restrictions: precision must be an integer number
of seconds or divide evenly into 1 second.

Formatting:
Since NeXtMidas 2.5.0 the TIMEX command supports a wide variety of time/date
formats made available via the MFormat class. Acceptable in/out formats can
be either a standard Midas format:
Type Format Example (1993-FEB-25 14:42:57.123456)
-----------------------------------------------------------------------------
"STD" yyyy:MM:dd::HH:mm:ss[.SSS] 1993:02:25::14:42:57.123456
T:yyyy:MM:dd::HH:mm:ss[.SSS] T:1993:03:25::14:42:57.123
"ACQ" [yy]yy.DDD:HH:mm:ss[.SSS] 93.056:14:42:57.123456
"EPOCH" yyyy:sec_in_year 1993:4804977.123456
"FILENAME" yyyyMMdd_HHmmss[SSS] 19930225_144257123456
"NORAD" yyDDD.frac_of_day 93056.61316115
"TCR" D:HH:mm:ss.SSS 56:14:42:57.123456
"VAX" dd-MMM-yyyy:HH:mm:ss.SSS 25-FEB-1993:14:42:57.123456
"HMS" HH:mm:ss.SSS 14:42:57.123456
"YMD" yyyy:MM:dd 1993:02:25
"ISO8601" yyyy-MM-ddTHH:mm:ss.SSSZ 1993-02-25T14:42:57.123456Z
"FULL_STD" yyyy:MM:dd::HH:mm:ss.SSS 1993:02:25::14:42:57.123456

Or they can be any of the patterns accepted by the java.text.SimpleDateFormat.
This gives maximum flexibility when converting between various time/date
formats. Here is mini-guide to above format/SimpleDateFormat pattern letters:
D=Day in year (1-366), d=Day in month (1-31), M=Month in year (1-12),
H=Hour in day (0-23), h=Hour in am/pm (1-12), m=Minute in hour (0-59),
s=whole seconds in minute (0-59), S=fractional seconds (up to femtosecond),
(NOTE: above doc difference vs S for milliseconds in SimpleDateFormat).

Note: When the time is one day or less, time formats STD, ACQ, EPOCH, and VAX
do NOT output the year, month, and day, but only the hours, minutes, and
seconds. ISO8601 time format in NeXtMidas 3.3.0 to 3.5.3 also had this
behavior, but was change to always output full date and time in 3.5.4.

For details, please see nxm.sys.lib.MFormat, nxm.sys.lib.Time.formatList and
java.text.SimpleDateFormat.

Examples:
1. Display the current time at the terminal.
nM> TIMEX
Time = 2004:05:09::16:04:53.416
or
nM> TIMEX NOW terminal
Time = 2004:05:09::16:04:53.416

2. Display the current time rounded to the nearest second.
nM> TIMEX round=1 terminal
Time = 2004:05:09::16:04:53.000

3. Writes the current system time to the epoch timecode fields of MYFILE
and also to the result LOCALTIME.
nM> TIMEX NOW file=myfile localtime

4. Copies the epoch timecode in MYFILE to the epoch timecode in YOURFILE
and the YOUROTHERFILEs acquisition fields.
nM> TIMEX infile=myfile file=yourfile acq=yourotherfile

5. Breaks out the acquisition date/time keywords for MYFILE into its
Julian day components for system modeling functions.
nM> TIMEX acq=myfile jd=julianday soy=secofyear gha=greenwichHourAngle

6. Uses the timecode field in MYFILE as the quadword epoch time for
the ECI reference frame. This affects the epoch_year, epoch_seconds,
and epoch_hour_angle quadwords of the file, quadwords(10-12).
nM> TIMEX file=myfile quad=myfile

(There are no restrictions on the number of output parameters.)

7. Converts a time string to a DOUBLE.
nM> timex "2004:11:15::13:55:31.503" d:mytime
nM> res mytime
D: MYTIME = 1.731678931503E9

Could also use (note this only works when the time is not quoted):
nM> res d:mytime 2004:11:15::13:55:31.503
nM> res mytime
D: MYTIME = 1.731678931503E9

8. Converts a time string to a long LONG.
nM> timex "2004:11:15::13:55:31.503" L:mytime
nM> res mytime
L: MYTIME = 1731678932

Could also use (note this only works when the time is not quoted):
nM> res d:mytime 2004:11:15::13:55:31.503
nM> res mytime
L: MYTIME = 1731678931

Note that TIMEX will round the time to the nearest second while RESULT
will always do a type cast (i.e. round down).

9. Use Java input and output formats (since NeXtMidas 2.5.0).
nM> timex now /fmt="yyyy-MM-dd hh:mm:ss.SSS"
Time = 2007-08-06 10:30:14.745

nM> timex "2007-08-06 10:30:14.745" /infmt="yyyy-MM-dd hh:mm:ss.SSS"
Time = 2007:08:06::10:30:14.745

nM> timex "1994-01-01T00:00:00Z" /infmt="yyyy-MM-dd'T'hh:mm:ss'Z'"
Time = 1994:01:01::00:00:00

nM> timex "1994-01-01T00:00:00Z" /infmt="ISO8601" !since NeXtMidas 3.3.0
Time = 1994:01:01::00:00:00

10. Get current time in Hour-Min-Sec time format into results TIMEHMS.
nM> timex now timeHMS /fmt="HMS"
nM> res timeHMS
12S: TIMEHMS = 17:44:27.293

11. Comparison of time of day (since midnight) in STD versus FULL_STD
nM> TIMEX SSM /fmt="STD"
Time = 19:56:12.337
nM> TIMEX SSM /fmt="FULL_STD" !since NeXtMidas 3.5.2
Time = 1950:01:01::19:56:12.337

12. Up to femtosecond precision is available !since NeXtMidas 3.5.2
nM> timex "2014:04:03 02:34:56.123456789012345" &
/infmt="yyyy:MM:dd hh:mm:ss.SSSSSSSSSSSSSSS" &
/fmt="d MMM yyyy HH:mm:ss.SSSSSSSSSSSSSSSSSS"
Time = 3 Apr 2014 02:34:56.123456789012345

13. simpleDateFormat milliseconds used when 3 or less Ss are specified
nM> timex "2014:04:03::02:34:56.1234" /fmt="d MMM yyyy HH:mm:ss.S"
Time = 3 Apr 2014 02:34:56.123

14. T:<std_format> as STD Time
nM> timex T:2015:03:14::09:26:53.589793238462 /PREC=12
Time = 2015:03:14::09:26:53.589793238462

Switches:
/FMT=<str> Output format to use. If present, the output is a formatted
time/data string, otherwise it will be a Time object. See the
above section titled "Formatting" for details.
/INFMT=<str> Input format to use. If present, the input value is parsed from
a time/data string, otherwise it will assume one of the time
specifiers listed above. See the "Formatting" section for
details.
/PREC=<n> Number of places after the decimal point to display when given
one of the "standard" formats on the /FMT= switch.

See Also: nxm.sys.lib.Time, nxm.sys.lib.MFormat

</pre>

[[Category:NXM_Explain]]

IMPLICIT

2020-04-27T22:05:13Z

ConvertBot: declares macro results name checking mode (deprecated)

declares macro results name checking mode (deprecated)
<pre>
resname

This is a place holder intrinsic from XMidas. It has no effect within
NeXtMidas and will cause an Error to be generated when used.
</pre>

[[Category:NXM_Explain]]

ELSEIF

2020-04-27T22:05:13Z

ConvertBot: starts macro block to be executed when prior IF conditions fail

starts macro block to be executed when prior IF conditions fail
<pre>
<value1> Left side of expression
<test> Logical test to be performed
<value2> Right side of expression

ELSEIF begins an alternative execution block for the macro IF statement. It
performs the same logical tests available for the IF statement. An example of
its use to take operating system-specific action follows:

if ENV.OStype eqs VMS
! perform VMS actions
elseif ENV.OStype eqs UNIX
! perform UNIX actions
else
SAY "Not supported for operating system ^ENV.OStype"
endif

SEE ALSO: IF, ELSE, ENDIF

</pre>

[[Category:NXM_Explain]]

INFO

2020-04-27T22:05:13Z

ConvertBot: causes a macro to issue an informational message

causes a macro to issue an informational message
<pre>
<TEXT> - message to print to screen

Prints the given informational message to the terminal, preceded by the string
"INFO:" and followed by the name of the invoking macro in square brackets (e.g.
"[%MYMACRO]"), if used in a macro.

Informational messages are treated as low priority messages for the purposes of
filtering.

See Also: SAY, WARN

</pre>

[[Category:NXM_Explain]]

NMSTART

2020-04-27T22:05:12Z

ConvertBot: Starts a new NeXtMidas session.

Starts a new NeXtMidas session.
<pre>
Starts a new NeXtMidas session. This briefly starts the Java VM to initialize
environment settings and to execute the optional %nmstartup macro in the
user's home directory. This creates the NeXtMidas State File (NMSF) used
throughout the session.

Use of nmstart is technically optional. NeXtMidas can be run in "independent"
mode without using nmstart or nmend (this is typically done when launching
NeXtMidas from a script). Type "nm -H" at the OS command line for details.

Note that some users alias nms to nmstart.

**************************************************************************
* This is an operating system command (aliased when nmstart is run), it *
* can only be used outside of the NeXtMidas shell. *
* *
* If run from inside the NeXtMidas shell, bad things will happen. *
**************************************************************************

Examples:
1. Start a new NeXtMidas session and enter the shell:
$ nmstart
<prints version information and copyright>
$ nm
nM>

See Also:
NMEND, NM

</pre>

[[Category:NXM_Explain]]

STARTMACRO

2020-04-27T22:05:12Z

ConvertBot: mark the start of the command section of a macro

mark the start of the command section of a macro
<pre>
<parameter 1> First macro parameter
.
.
.
<parameter N> Nth macro parameter

The STARTMACRO command performs identifies formal macro parameters that
will be substituted at runtime by actual parameters. It is not necessary
for a macro to have any parameters.

At runtime, the STARTMACRO command does nothing, but NeXtMidas issues an
error if it encounters this command when a macro is not being executed or
if this command is not at the root level of the macro.

Switches:
/MSGLOG - Set the midas messagelog

See also: ENDMACRO

</pre>

[[Category:NXM_Explain]]

HISTOGRAM

2020-04-27T22:05:12Z

ConvertBot: computes the histogram of input data

computes the histogram of input data
<pre>

<IN> - Input file name
<OUT> - Output histogram
<START> - Center of bin containing lowest ordinate value
<END> - End of range of interest
<DELTA> - Width of each bin

Keyword Only Parameters
[BINS] - (Since 3.1.0) The number of bins to use (overrides <DELTA>
as needed)
[CXMODE] - (Since 3.1.0) The format mode when using complex data. Must be in
"MAG,PHASE,REAL,IMAG". Default is MAG.

HISTOGRAM computes a histogram of the input data whose value falls between
<START> and <END>. Values outside this range are not counted, and the number
of points that could not be counted is displayed, along with the total number
of points and number of bins. (This output is suppressed when in a macro and
/VERBOSE is not specified).

(Since 3.1.0) If <START> and <END> are omitted (or set such that
<END> <= <START>) the <START> and <END> values will be set to match the
range of values for the input data type.

(Since 3.1.0) If <DELTA> is not set and <BINS> is not set, a default of
BINS=512 will be used.

If the input is a pipe, a histogram is computed on each transfer length.

Switches:
/BITS - (Since 3.1.0) Count the bit values (usually used with 'SP' data).
This implicitly sets START=0, END=1, BINS=2.
/TL - Set the transfer length in elements

</pre>

[[Category:NXM_Explain]]

LOOP

2020-04-27T22:05:11Z

ConvertBot: implements a basic counting loop within a macro

implements a basic counting loop within a macro
<pre>

<count> Number of times to loop
<label> Result label to hold count (optional)

The LOOP loop is a simplified version of the DO loop that is provided for
compatibility with X-Midas.

A LOOP-ENDLOOP combination is used in a macro to loop through a sequence of
commands <count> number of times. If specified, the results parameter <label>
will contain the current loop count. When the loop is finished, <label> will
be equal to <count>.

<label> starts at 1 and continues up through <count> inclusively. Thus for
<count>=3, <label> becomes 1, 2, 3, and then the loop stops.

There are no restrictions nesting LOOP loops.

Examples:
1. Initialize the results MYRES_1 ... MYRES_7.

LOOP 7 i
result myres_^i 0
ENDDO

SEE ALSO: DO, ENDLOOP, BREAK, CONTINUE

</pre>

[[Category:NXM_Explain]]

MAPDEMO

2020-04-27T22:05:11Z

ConvertBot: Demonstrates NeXtMidas Client-Side Mapping Capabilities

Demonstrates NeXtMidas Client-Side Mapping Capabilities
<pre>
<URL> - URL of the server to connect to [DEF=http://nextmidas.techma.com:...]
<TYPE> - Type of map server ("WMS","NMS","GMap") [DEF=WMS]

The NeXtMidas PLOT command supports connecting to several types of map servers.
These include:

WMS - OpenGIS-compatible Web Map Server (WMS version "1.1.1" or "1.3.0")
NMS - NeXtMidas Map Server (MAP option tree)
GMap - Google Maps

Of these the most full-featured (and newest) is the WMS client. It features
individual layer selection, layer reordering, style selection, brightness and
contrast. All of these are configurable from a macro or from an easy-to-use
popup.

When the window comes up click the 'Configure' button to configure the WMS
maps. Note that, by default no maps are selected. Different WMS servers can
support numerous types of maps (charts, imagery, shape files, etc).

The GMap and NMS servers use a protocol that is more limited and does not
provide the clients with the same level of control. These clients come up
with a default set of imagery that has few configuration options.

For more information please see the PLOT explain file and please see the
mapdemo.mm macro in the MCR area of the SYS option tree.

WebStart:
There is a sample JNLP file that can be used to launch this macro from
Java Web Start. The file is located at $NMROOT/htdocs/mapdemo.jnlp. You
will need to edit the file with the following changes before using it:

(1) Change the "codebase" URL for the host server (line 17).
(2) Change the "href" (relative to "codebase" or absolute URL) if the
JNLP file is at a different location/name (line 18).
(3) Change the URL for the map server in the argument tag enclosed within
the application-desc tag (line 43).

For more details on using Java Web Start to launch a NeXtMidas application,
please see the "NeXtMidas User's Guide".

WMS Servers:
There are a number of WMS servers available on the Internet, a few that
are interesting include:

Fulton County Government (http://wms.co.fulton.ga.us/wms/public)
- Maps of streets and zoning information for Atlanta, GA.
- Need to zoom in closely on Atlanta before anything will show up.

Geography Network Canada (http://www.geographynetwork.ca/wmsconnector/
com.esri.wms.Esrimap/OBM_Full_I)
- Maps of streets and public utilities around Toronto, ON.
- Demonstrates connecting to an ESRI server.
- Need to zoom in closely on Toronto before anything will show up.

NASA World Wind (http://wms.jpl.nasa.gov/wms.cgi)
- Imagery of the world and elevation data.
- Demonstrates connecting to a NASA World Wind server.

USGS EO see http://eoportal.cr.usgs.gov/EO/gis.php for updated URLs)
- e.g. http://gisdata.usgs.gov/wmsconnector/com.esri.wms.Esrimap/&
USGS_EDC_Ortho_StateLocal

To debug your WMS server and see it's capabilities, append the following to
the WMS URL "?SERVICE=WMS&REQUEST=GetCapabilities" and open it in your browser
to see an XML document. e.g.
http://nextmidas.techma.com:8888/wms/mapServer?SERVICE=WMS
&REQUEST=GetCapabilities

Examples:
1. Connect to OpenGIS-compatible Web Map Server (WMS):
nM> mapdemo "http://nextmidas.techma.com:8888/wms/mapServer"

2. Connect to NASA's WMS server:
nM> mapdemo "http://wms.jpl.nasa.gov/wms.cgi" "WMS"

3. Connect to NeXtMidas Map Server (NMS):
nM> mapdemo "http://nextmidas.techma.com:8080/nms" "NMS"

4. Connect to OGC-compatible Web Map Server (WMS):
nM> mapdemo "http://nextmidas.techma.com:8800/wms/"

Switches:
/LOOK=<look> Change the look and feel on startup (for use via WebStart).

See Also: PLOT, nxm.sys.libg.LayerMap, nxm.sys.libg.LayerWMS

</pre>

[[Category:NXM_Explain]]

CONFIDENCE

2020-04-27T22:05:11Z

ConvertBot: Runs a set of NeXtMidas test macros on an option tree

Runs a set of NeXtMidas test macros on an option tree
<pre>
<opt> Option tree name to test

Optional Test Configuration File:
test_config.tbl - Input file to add to/modify tests in test area of <opt>.

CONFIDENCE runs the any configured unit tests and test macros located in the
test area of the specified option tree. This test suite returns an overall
PASS / FAIL message for each command tested.

Each test typically exercises multiple aspects of the command it is testing.
If any of these constituent tests associated with the command fail, CONFIDENCE
returns a FAIL message to the user. ALL constituent tests associated with a
command must pass in order for CONFIDENCE to return a PASS message for that
command.

CONFIDENCE is actually a wrapper macro that runs tests for all commands in the
option tree that have a test_<command> macro in the test subdirectory. If the
file test_config.tbl exists in the test area/subdirectory, it can be used to
modify the default behavior (see Configuration Table File Definition section
below for more details). To run the individual tests, type;

nM> home test <opt>
and run:
nM> %test_<command>

If in the course of running the CONFIDENCE macro a FAIL message is returned,
and the user wishes to get PASS / FAIL information for the constituent tests
for that particular command; the macro in the nxm.<opt>.test area should be run
individually. For example, with one's home path set to the test area you can
run:
nM> %TEST_CALCULATOR
to see the individual results of the calculator command tests.

Since 2.7.1: All test failures are printed (instead of rolled up into one FAIL
message for that command so that user does not need to re-run failed test cases
to get more detailed information.

Since 3.1.0: the /baseline, /interactive, and /debug (using value of /dbg)
switches are propagated to all test macros and their sub-test macros.

Configuration Table File Definition
-----------------------------------
The configuration table file (test_config.tbl) can be converted directly
to a NeXtMidas Table and consists of a number of TAG=VALUE lines.
Where TAG=VALUE can be:
1) A quoted and comma separated list of additional test <name>'s.
TESTLIST="<name1>,...,<name2>"
where <nameN> is TEST_<nameN>.mm. This allows TEST_<name>'s to be run
when <name> does not correspond to a command in the option tree.

2) Any command in the command dictionary followed by a tag.
<cmd>=[BROKEN|NOTEST|WEB|<cmd2>]
where
BROKEN - Test is KNOWN to be broken so you want to skip it
NOTEST - Do not desire to have a test for this command
WEB - Test requires a WEBSERVER to be running
<cmd2> - NO test required for <cmd>, it is tested when test for
<cmd2> is run.

Examples:
Run only NON-INTERACTIVE tests (all interactive tests will show as passed)
nM> confidence

Run INTERACTIVE and NON-INTERACTIVE tests
nM>confidence/interactive

Run NON-INTERACTIVE tests and show any commands MISSING tests
nM>confidence/miss

Run NON-INTERACTIVE tests and stop at the ASK command
nM>confidence/stopat=ASK

SWITCHES:
/BASELINE - Run this before baseline release, enables additional
non-interactive testing and turns on /INTERACTIVE. [DEF=FALSE]
/DBG - Show detailed status line for tests in sub-macros. [DEF=FALSE]
/DEBUG - Show status line for each test. [DEF=TRUE]
/INTERACTIVE - Non-interactive and interactive tests. [DEF=/BASELINE]
/MISS - Show commands which are missing tests. [DEF=TRUE]
/RESUME=cmd - Skips test macros prior to specified command.
/STOPAT=cmd - Stops at specified command (does not run given command).
/WEB - Run tests which require HTTPD, see HELP WEBSERVERS

SEE ALSO: HOMEPATH, ASSERT, UNITTEST

</pre>

[[Category:NXM_Explain]]

MACROFUNC

2020-04-27T22:05:10Z

ConvertBot: create or list macro for debug

create or list macro for debug
<pre>
<U:name> Name of macro [DEF=CURRENT]
<U:func> Function to perform (ENTER,LIST) [DEF=LIST]
<L:wind> Number of lines displayed for LIST function inside a macro [DEF=5]

Provides some utilities for manipulating macros. When executed the given macro
definition is loaded and the specified function is performed on the macro text.

FUNCTIONS:

ENTER - macrofunc <name> ENTER
Allows a user to enter a macro directly from the command prompt. If <name>
is given, the macro is written to the current homepath as a user macro. If
<name> is blank, the macro is entered and executed.

LIST - macrofunc <name> LIST
Displays the contents of the macro to the terminal with line numbers to the
left of each line. If <name> is blank and called within a macro, the lines
+-<WIND> about the current macro index are displayed. If name is not
blank, the entire parsed macro is displayed.

Switches: NONE

</pre>

[[Category:NXM_Explain]]

DEMO

2020-04-27T22:05:10Z

ConvertBot: NeXtMidas software demonstration macro

NeXtMidas software demonstration macro
<pre>
This is a demonstration macro designed to present some of the capability of
NeXtMidas in the following areas:
1) GUI development
2) Signal Processing
3) Graphics - Geoplots, rasters and spectra
4) Macro-level command-line interface

While the DEMO macro is in fact only a demonstration, it can be used by
users and developers as an example on how to put together graphics-based
macros. Within the DEMO macro a wide range of NeXtMidas capability is
hi-lighted.

The left-most section of the window is the control area for the graphics
macro. This control section consists of the following parts:
MACRO - Run, Pause and Stop buttons for the macro
Waveform - Control section for the Real-Time Spectra display in the
right-most part of the window and the Audio Spectra
display below it. Provides the ability to change the
wave shape and the sine frequency of these spectra.
GeoPlotter - Provides the means to change the view of the geodetic
plot of the earth in the center screen. It also
provides feature control (adding new, moving, clearing).
Demodulator - Provides the means to change the demodulation mode
(i.e., FM, AM, etc). See the DEMOD explain file
for more detail on this capability.
Audio Mixer - Provides the means to change Gain, Low, Mid and High
filters for the audio spectra.
Audio Spectra - Sample plot of a piped audio file.
Other - Sample of a graphical monitor for a data pipe.

Notes:
1) These control sections may be rolled up/down by clicking on the title areas
MACRO, Waveform,... This is particularly useful for saving screen space.

2) Numeric values may be entered/changed by:
a) RIGHT-MOUSE(RM) click on the number an enter desired value
b) LEFT-MOUSE(LM) click on a number place and then changing the values
by clicking on the diamond. The values go UP/DOWN with a LM click or RM,
respectively.

The center section of the window consists of the following:
Map Display - A plot of the earth in geodetic view. The view of the
earth can be changed via the GeoPlotter control section
described above or by right-clicking on the pane to
display a multi-level pop-up window. Also by right-
clicking, holding, and moving the mouse the earth will
rotate. By left-clicking and dragging the mouse, the
plot will be zoomed to the section selected (as defined
by the "box" constructed via the mouse movement). By a
combination of rotating and zooming any point of interest
on the earth can be viewed.
Macro Window - This is labeled "RunTime Macro Language Interface", and
is actually a mini command-line interface. Any NeXtMidas
command can be typed into the small rectangular window
below the horizontal scroll bar and the results of that
command will be display in the window above (with the
nMP> prompt). This is particularly useful for displaying
files via the FILES command.

The left section of the window consists of the following:
Real-Time Spectra - A mini spectral display. Its parameters can be
controlled via the control area as described above.
Static Raster - This is a plot of the MIDAS type 2000 file called
apenny.prm. This plot demonstrates the capability of
NeXtMidas color-mapping. As with any NeXtMidas plot
it can be zoomed via left-clicking-and-dragging and it
can be altered via a right-mouse click that presents
a multi-level pop-up window.

Additionally, developers can examine the GUI definition file associated with
the DEMO macro (called demo.mmp and located in the nxm.sys.mcr directory) to
determine how to define the geometry of NeXtMidas GUI displays, as well as to
see how the .mmp file is linked to the macro code (in the .mm file).

Switches:
/SERVER=port - Enable RMIF and HTTP server listening on given port. [DEF=OFF]

SEE ALSO: SD360, nxm.sys.mcr.demo.mmp

</pre>

[[Category:NXM_Explain]]

FCALCULATOR

2020-04-27T22:05:10Z

ConvertBot: implements a reverse polish calculator on elements of data files.

implements a reverse polish calculator on elements of data files.
<pre>
<LABEL> - Label for the output file.
<param 1:N> - Parameters for the fcalc function.

Evaluates the expression contained in the list of <variables/operators/files>
entries and stores the answer(s) in the output file(s). Reverse Polish Notation
is used (just like most HP calculators). The NeXtMidas version of calculator
extends the syntax to allow multiple outputs per calculation. If this syntax
is not used, it assumes the 1st argument is the name of the single output file
as in the X-Midas version. This version also allows results or expressions
to be recomputed as the files are processed by using the /MON switch.

If multiple input files are given with different lengths, the computations
will stop after then end of the shortest file is reached. The resulting output
file will have the same size as the *shortest* input file.

Though at least one input for an operator needs to be a file, there is no restriction on order.
(As of 3.5.1 there is no longer a requirement that the first input be a file)

3 input operators can have 2 of their 3 inputs be constants (as of 3.5.1).

Note1: Since NeXtMidas 2.5.0, the string infinity can be used in computations.
Note2: Since NeXtMidas 2.6.0, the LOG, LN, and DB operators may return NaN
(Not a Number) for negative arguments, and also treat zero arguments as
if they were very small positive values, in order to avoid returning
-infinity for log(0.0). The old pre 2.6.0 backwards compatible behavior
(incoming arguments were bounded at 1.0e-12 and the absolute value was
always taken) is available via the LOG/B, LN/B, and DB/B operators.
Note3: Note that at the start of each JVM session, the initial seed value is set
to 12345678 and this seed is used for the uniformly distributed RANDOM
number generation. This consistent non-random setting of seed allows for
consistent random data generation for testing across repeated session.
SETSEED must be used if a truly random seed is required for each session.
Since NeXtMidas 3.1.1: The RANDOM/P are RANDOM/S operators provide
alternative random number generation that always are with a random seed.

Operators:
+ : addition - : subtraction
* : multiplication / : division
~ : conjugate of complex ~* : complex conjugate multiplication
~/ : complex conjugate division
** : power

Comparators:
-----------
EQ : equal to
LT : less than GT : greater than
LE : less than or equal to GE : greater than or equal to

Trigonometric and Angle Functions:
---------------------------------
COS : radians ACOS : principal value (radians)
SIN : radians ASIN : principal value (radians)
TAN : radians ATAN : principal value (radians)
ATAN2 : principal value (radians)
POLAR : complex rect to polar RECT : complex polar to rect
PHASE : phase of complex

All functions dealing with angles are by default in radians.
To express in degrees, append a D to the operator.
To express in cycles, append a C to the operator.
This applies to SIN,COS,TAN,ASIN,ACOS,ATAN,ATAN2,PHASE,POLAR,RECT

COMPLEX NUMBERS
---------------
ADDC : Alias for ~+
CMPLX : Convert a real number <r> into a complex number (<r>,0)
CONJ : Alias for ~
DIVC : Alias for ~/
MULC : Alias for ~*
REAL, IMAG : Get the REAL or IMAGINARY part of a complex number
SUBC : Alias for ~-

Bit Manipulations:
-----------------
BOR : bitwise OR BAND : bitwise AND
BXOR : Exclusive OR BNOT : Complement

Miscellaneous (in alphabetical order):
-------------------------------------
ADD : Alias for +
ABS : absolute value
CEIL : Get the closest fixed point number above given real number
CLIP : CLIP value to within a MAX,MIN range, i.e. MIN (b, MAX(c,a)) where
a=value, b=maximum, c=minimum
DB : Convert number to DB (precise)
DB/B : Convert number to DB (precise & bounded - see Note2 above)
DBF : Convert number to DB (fast, less precise)
DEMUX : demux complex into 2 scalars
DIV : Alias for /
DOT : dot product of two vectors
EXP : natural exponential
FIX : real to integer truncation
FLOOR : Get the closest fixed point number below given real number
LOG : base 10 logarithm
LOG/B : Base 10 logarithm (bounded - see Note2 above)
LN : natural logarithm
LN/B : Natural logarithm (bounded - see Note2 above)
MAG : magnitude of complex
MAG2 : magnitude squared
MAX : maximum of 2 values (Alias is MAXIMUM)
MIN : minimum of 2 values (Alias is MINIMUM)
MUL : Alias for *
MUX : mux 2 scalars into complex
MOD : Same as MOD/T
MOD/E : Euclidean Modulo function (always positive)
MOD/F : Floored Modulo function (sign follows divisor)
MOD/T : Truncation Modulo function (Java % operator)
POW : Alias for **
POWER2 : Gets the power of 2 number >= given number
RANDOM : Pseudo-random number (0, 1). See Note3 above.
RANDOM/P: Pseudo-random number [0, 1) (see java.util.Random - Since 3.1.1)
RANDOM/S: Cryptographically secure-random number using [0, 1)
(see java.security.SecureRandom - Since 3.1.1)
ROUND : real to integer rounding
SQRT : square root
SQUARE : Square a number
SUB : Alias for -
VMUX : mux 3 scalars into vector
VDEMUX : Demux vector into 3 scalars
WRAP : Wrap data to a range (usually phase to -180 to 180)
UNWRAP : UnWrap data from a range (usually phase to -180 to 180)

Stack Operations:
----------------
PUSH : push top of stack (duplicate)
POP : pop the top of stack (discard)
<> : swaps the top two values on the stack
?: : compare top of stack to zero and select top-1 if > or top-2
if not "D=(C>0)?A:B"

>name : pops the top of the stack to the named output file
<name : pushes contents of named input file onto the stack

All entries are treated first as operators. If the entry does not match any
of the supported operators, it is tested to be a results parameter. If it can
not be evaluated as a result, it is assumed to be a file name. Therefore, the
operators identified above cannot be used as variable names. The <name form
for input files avoids trying to parse them as operators or constants.

NOTE: When using in-line file trimming the <name input file form may be
necessary to avoid generating errors while trying to parse them as constants
or operators.

The conversion of each numeric input parameter is handled by the Convert.s2o()
routine. Thus, in-line calculations can be used within a parameter even though
that argument is treated using reverse polish by the rest of the fcalculator
command.

NOTE: FIX and ROUND do NOT convert the file format to fixed point. Use the
/type switch to alter the output file format.

NOTE: Operations are defined in the Operators.cnf file. New operators may be
added and defined in this file and the code is generated with the
command:
nM> GENERATE OPER ALL

Examples:
1. Standard form:
fcalc/type=l outfile infile1 infile2 + infile3 *

2. Explicit form (for 1st difference):
fcalc <infile1 <infile1(1:) - >outfile

3. Explicit form multiple output:
fcalc <infile push 2 / >outfile1 10 * >outfile2

4. Code snippet to show how this command can be used in a pipe and results and
expressions. In this example, the output of fcalc changes as the Multiplier
control (gc.multiplier) is changed (see nxm.sys.test.test_fcalculator for
a detailed implementation of this example).

...
pipe on
panel/setup/controls=gc
gcontrol lval multiplier "Multiplier" 2 1 10 1
...
waveform,OUT=_wave,FORM=SF,ELEM=5e9,SHAPE=CONST,AMP=1
fcalc/mon _out _wave gc.multiplier.value-1 *
pipe off

Switches:
/MON - Treat results and expressions as variables that can be changed
as the file(s) are processed. Usually used in a pipe section.
/TL - The number of elements to be read each process loop [DEF=1024]
/TYPE=D|F|L - Data type for calculations (defaults to F)

SEE ALSO: CALCULATOR, nxm.sys.libm.Operators.cnf, nxm.sys.libm.ArgStack.java,
SEE ALSO: nxm.sys.test.test_fcalculator.mm

</pre>

[[Category:NXM_Explain]]

STATUS

2020-04-27T22:05:09Z

ConvertBot: outputs the header information of a Midas or other file types

outputs the header information of a Midas or other file types
<pre>
<file> - name of file (Midas BLUE, text, shape, image,...)

Outputs the header of the file named <file> to the terminal. Typically, this is
used on Midas BLUE files but in NeXtMidas one can status any file that extends
nxm.sys.lib.BaseFile and implements a listHeader method. For example:

nM> status world.shp

works because nxm.sys.lib.ShapeFile has a listHeader method. Other examples of
classes with this ability are:

* BaseFile.java - The default implementation
* CsvFile.java - For CSV files (CSV)
* DataFile.java - For Midas files (TMP,PRM)
* DbfFile.java - Companions to shape files (DBF)
* ImageFile.java - Image files: JPEG, PNG,...
* JarFile.java - Java Archive (JAR) files
* TextFile.java - Text files (TXT)
* ZipFile.java - Compressed Zip Files (ZIP)

If the user supplies other arguments of the form TAG=LABEL, these values
will be written to the results table and the terminal output is skipped.

NOTE: For most of the tags (except some legacy tags to match X-Midas), you will
not find them in the STATUS intrinsic itself. Java reflection is used to find
any "get" method in the class. For instance,

nM> stat world.shp type=xxx

finds the getType method in nxm.sys.lib.ShapeFile. Where appropriate, digraphs
or trigraphs can be used to provide shorter syntax. For instance, the NC tag
finds the method getNumberComponents in DataFile for type 5000 files. The NSR
tag finds the method getNumberSubRecords in DataFile for type 3000 files.
While short tags are convenient from the command line, generally, it is
recommended that the full method name is used in macros.

For 3000 and 5000 record oriented files, the record formats are also shown.
For 5000 files, the frame of reference and any information pertinent to the
frame is displayed.

Common tags in the DataFile class (all Midas BLUE files) are:

TAG Longname Description
------------------------------------------------------------------------------
TYPE TYPE Type of file
SIZE SIZE Size in logical elements
SZ SIZE Same as SIZE. Special tag for X-Midas backward compatibility
DS DATASTART Data start in bytes (usually 512)
DR DATAREP Data representation
FORM FORMAT Data Format
-- XUNITSNAME X or Abscissa units name (PREFERRED)
XS XSTART X or Abscissa start
XD XDELTA X or Abscissa delta
-- YUNITSNAME Y or Abscissa units name (PREFERRED)
YS YSTART Y or Secondary start
YD YDELTA Y or Secondary delta
TC TIMECODE Timecode

also available through tags are:

TAG Longname Description
------------------------------------------------------------------------------
FS FRAMESIZE Frame size
RL RECLENGTH Record length (type 3000/5000)
NSR NUMBERSUBRECORDS Number of subrecords (3000/5000)
SR(NAME) N/A Subrec specs table by name (PREFERRED)(3000/5000)
SR(i) N/A Subrec specs table {NAME,FORMAT,OFFSET}: i=1..n
NC NUMBERCOMPONENTS Number of components (type 5000)
RF REFERENCEFRAME Frame of Reference (type 5000)
C(i) N/A Component specs table: i=1..n
{NAME,FORMAT,TYPE,UNITS}
QW(i) N/A One-based version of QUADWORD(i) for legacy
X-Midas compatibility: i=1..n
-- QUADWORD(i) Quadword value: i=0..n-1 (type 5000)
QW(0)=ref frame QW(1)=altitude QW(2)=latitude,
QW(3)=longitude QW(4)=azimuth QW(5)=elevation,
QW(6)=roll, QW(7)=unused QW(8)=unused,
QW(9)=epoch_year QW(10)=epoch_sec QW(11)=epoch_hour_angle

common PIPE tags are:

TAG Longname Description
------------------------------------------------------------------------------
PS PIPESIZE Pipesize in bytes
INB INBYTE Pipe input or writer byte
OUTB OUTBYTE Pipe output or reader byte

DEPRECATED tags:

TAG Longname Description
------------------------------------------------------------------------------
XU XUNITS X or Abscissa units number (Use XUNITSNAME instead)
YU YUNITS Y or Secondary units number (Use YUNITSNAME instead)

The tags may be used in conjunction with the file command. See example below.

The EXIST qualifier may be used to change the behavior of the exists algorithm.
For example,

nM> status http://localhost/nextmidas/nxm/sys/dat/world.prm{EXIST=NONE}

turns off explicit existence checking, i.e. assume file exists. The EXIST
qualifiers are CGI,STATUS,LIST and NONE and ALL may be used to select no or all
options, respectively. See help qualifiers for more details.

Examples:
* Put the frame size in result NFRAME.
nM> status myfile framesize=nframe

* Test for a specific Midas file type and format.
nM> file open/d mytag testxy3000
nM> if mytag.type eq 3000 and mytag.format eqs "NH" then

* List information about the NeXtMidas version.txt text file
nM> stat ^{ENV.NMROOT}/nxm/sys/version.txt
TextFile : file:/home/midas/nxmxxx//nxm/sys/version.txt
Size : 457.0 bytes

Switches:
/ALL List additional main header fields for debugging (since 3.1.1)
/D=n List n elements of data after the header (using DATALIST)
/DATA=n Equivalent to /D (since 2.7.3)
/K Equivalent to /KEY
/KEY Show keywords in the main and extended headers
/PREC=n Equivalent to /PRECISION= (since 3.3.0)
/PRECISION=n Used only with /TIME to specify the number of decimal places to
display for timeline entries. (since 3.3.0) [DEF=3]
/T Equivalent to /TIME
/TIME Show a dump of any TimeLine keywords

See Also: FILE, HEADERMOD, nxm.sys.lib.DataFile, nxm.sys.lib.BaseFile

</pre>

[[Category:NXM_Explain]]

MEDIT

2020-04-27T22:05:09Z

ConvertBot: opens a macro's source file for editing

opens a macro's source file for editing
<pre>
<name> name of macro to edit

MEDIT opens an editing session for the named macro's primary source file.
The path is determined from the dictionary lookup. When the edit session
is completed, the file is translated to check for structural errors.

This macro is a wrapper to the EDIT command.

SEE ALSO: EDIT

</pre>

[[Category:NXM_Explain]]

PATH

2020-04-27T22:05:09Z

ConvertBot: Configures dictionary to resemble hierarchical search path

Configures dictionary to resemble hierarchical search path
<pre>
<FUNC> - SHOW, SET, GET, ADD, ADD+, REMove, REDO, PUT, +, - [DEF=SHOW]
<option 1:N> - Option or space separated list of options
<resname> - Result name for GET function.

This command is a way of emulating the behavior of a hierarchical search path
with the option-driven configuration control. The options are listed from left
to right with the leftmost option taking precedence over those to the right.

Functions:
PATH GET <option> <resname>
Gets the path for <option> and places it in the result <resname>.
If no <resname> the path is printed to the screen.

PATH SET <option1> <option2> ... <optionN>
Commands from <option1> have precedence over <option2> commands which have
precedence over SYS commands. Note that the final "SYS" is not necessary
since it is always implied.

PATH ADD <option 1:N>
PATH + <option 1:N>
Puts the <option> option on the front of the existing path. This means
that the <option> option will be searched before any other. If the option
already exists elsewhere in the path, it is moved from where it is
to the beginning.

PATH ADD+ <option 1:N>
Puts the <option> on the end of the existing path but before SYS. If the
option already exists elsewhere in the path, it is moved from where it is to
the end but before SYS.

PATH PUT <option 1:N>
If <option> already exists on the path, does nothing (except notify the
user). If <option> is not on path, performs an ADD.

PATH REMove <option 1:N>
PATH - <option 1:N>
Removes <option> from the existing path.

PATH REDO
Refreshes the current path using updated COMMANDS.CNF files.

PATH SHOW
Prints your current configuration.

PATH
Without any arguments, prints your current configuration.

PATH is for purposes of interface compatibility; it is composed simply of a
series of CONFIGURE commands. To see what can be done with the NeXtMidas method
of configuration control, see EXPLAIN CONFIGURE.

The REDO function causes PATH to read the same series of COMMANDS.CNF files as
before. This is useful if you happen to change one or more of your COMMANDS.CNF
files and you want to redo your same configuration (so that your in-memory
dictionary will reflect the change) without having to type all your same
arguments again.

PATH keeps track of its configuration with an environment symbol called
ENV.PATH. Any changes to your dictionary through individual CONFIGURE or UPDATE
commands will not be reflected in this symbol; PATH should be the only command
that changes it.

To use a raw java jar (or directory of classes) with NeXtMidas, simply define
the jar as an option. For example,
nM> option jython /path/to/jython.jar
nM> path add jython

Examples:
nM> PATH GET UCL uclpath
Gets the path for UCL and places it in the result uclpath.

nM> PATH SET site sys
Allows site commands to have precedence over system commands.

nM> PATH SET site user
Allows SITE commands to have precedence over USER commands which have
precedence over SYS commands. Note that the final "SYS" is not necessary
since it is always implied.

nM> PATH SET user site proj sys
Allows commands under the option PROJ to have precedence over system; SITE
to have precedence over PROJ, and USER to have precedence over all of them.

nM> PATH ADD ucl
Puts the UCL option on the front of the existing path.

nM> PATH ADD dsp ucl audio
Puts the DSP option on the front of the existing path, then puts UCL on the
front of that, then puts AUDIO on the front of that. The new path is now:
AUDIO,UCL,DSP,<existing path>

nM> PATH ADD+ ucl
Puts the UCL option on the end of the existing path but before SYS.

nM> PATH PUT ucl
Puts the UCL option on the front of the path UNLESS it already exists
somewhere on the path, in which case it does nothing.

nM> PATH REMOVE user
or
nM> PATH REM user
Removes the USER option from the existing path.

nM> PATH/REDO
Refreshes the current path using updated COMMANDS.CNF files.

nM> PATH/RERUN
Prints the current path and runs any optstart.mm macros in the option trees.

nM> PATH
Prints your current path configuration.

Switches:
/REDO - Refreshes the current path using updated COMMANDS.CNF files.
/RERUN - Reruns the optstart.mm macros in the option trees on the path.
/SKIPRUN - Skip running optstart.mm macros in the option trees that are new
on the path. (Since NeXtMidas 2.9.1) [DEF=FALSE]

See also: CONFIGURE, UPDATE, OPTION

</pre>

[[Category:NXM_Explain]]

BUILD

2020-04-27T22:05:09Z

ConvertBot: Builds an NeXtMidas command or library

Builds an NeXtMidas command or library
<pre>
<NAME> Name of the command/library (or "ALL", or a '|' separated list of files
in the same area)
<AREA> Area of the option tree containing file (or "ALL")
<OPT> Option tree containing file [DEFAULT=SYS]

This command is used to compile a command or library under the NeXtMidas
framework. It looks for .java, .c, .clib, .cpplib, or .flib extensions and
compiles the routines found using the appropriate compiler.

If AREA="ALL" or "*" then all of the following areas will be included in the
build (since 3.1.2: this list is read from the build.codeareas.libs and
build.codeareas.other properties in the build.props file):
inc,lib,libg,libm,net, intr,prim,host,test,mcr

For .java, .c, .clib .cpplib, and .flib files, the name "ALL" or "*" can be used
to compile all of the routines found in the specified <AREA>. Note that if using
XBC to compile host primitives "ALL" will not include those host primitives not
in the commands.cnf file (this is done for compatibility with X-Midas).

If only <NAME> is specified then the command with the given name will be built.
This provided a quick way to rebuild a primitive that has been modified.

The build.props File
--------------------
Default definitions for compiler defaults used by BUILD can be found in
$NMROOT/nxm/sys/cfg/build.props. This file is defined as a normal Java
properties file and contains values for specific compiler options for each of
the supported environments. Additional properties can be added either to this
file (to change build behavior for SYS) or to <OPT>/cfg/build.props. Property
values defined in an option_tree build.props will override the defaults in SYS
(this is the preferred way of changing the flags used for a given option
tree).

The .append operator can also be used to add any existing properties
definitions (since NeXtMidas 2.9.2). A properties file in
<OPT>/cfg/build.props containing:

cflags.UNIX.append = -DFOO

will append the "-DFOO" compiler definition to the existing Unix CFLAGS
(cflags.UNIX) compiler flags, but before the native.UNIX.cflags property.

The .append.<machine_arch>bit (e.g. .append.32bit or .append.64bit) operator
allows additional flags to be added for 32-bit or 64-bit machines. E.g.

ifort.comp.append.32bit = -i-static

will append the "i-static" Intel compiler flag only on 32-bit machines for the
"ifort.comp" property (i.e. the Intel Fortran compiler and flags).

The .prepend operator can also be used to prepend any existing properties
definitions (since NeXtMidas 2.9.2). This is useful to override the default
native libraries to link against (since the linkers link libraries in the
order they are specified on the command line).

The fflags.host property in build.props can be used by an option tree's
build.props to provide additional compile and link flags to for their Fortran
HOST primitives (when using XBC).

Reminder: When you use -l<libname> the linker looks for lib<libname>.[a|so].
The linker searches and processes libraries and object files in the order they
are specified.

Building Native Code
--------------------
Classes with native components (e.g. NTerminal.java, NTerminal.c in SYS) are
automatically compiled and linked into a shared object library by the name
<NAME>_<ostag><osarch>.<so|dll> to be loaded by the java class when
instantiated. The <ostag> is "lin" for Linux, "win" for Windows, etc. (view
the build.props file for a more complete list of these tags). The <osarch> is
32 for 32-bit and 64 for 64-bit systems. The addition of the OS tag and
<osarch> are intended to allow versions of the libraries for different
platforms to coexist on a shared drive. Some examples: "Native_lin32.so,
Native_lin64.so, Native_win64.dll, NTerminal_sol32.so"

The linker stage also automatically looks for a
lib<NAME>_<ostag><osarch>.<so|a|dll> or a libAll_<ostag><osarch>.<so|a|dll>
and adds them to the linker stage if found.
These libraries are typically created by an option tree specific buildopt.mm
macro or through the use of a .clib, .cpplib, or .flib file (see below).

Building Native Libraries Using .clib, .cpplib, and .flib (.[c|cpp|f]lib) Files
-------------------------------------------------------------------------------
This feature allows easy creation of shared object libraries without the need
for a complicated build script or Makefile (since NeXtMidas 2.1.1).
The .[c|cpp|f]lib file simply list the names of the native files to be
included in the library. A typical file will look similar to this:

# Defines the files included in the libMyLib library,
# files are listed one-per-line.
file1.c
file2.c
preCompiled.a

Any blank lines or lines that start with a pound sign ('#') are treated as
comments and ignored. All other lines are expected to list each of the
component files one-pre-line. Files with a typical source code
extension (e.g. ".c", ".for") are compiled automatically before linking them
into the shared object. Any other files (e.g. ".a") are assumed to be pre-
compiled libraries that will be linked in. The resulting shared object will
be named <fname>_<ostag><osarch>.<so|dll> where <fname> matches the name of
the .[c|cpp|f]lib file.

Wildcards (* and ?) are supported for the files in the .[c|cpp|f]lib file.
The * (star) wildcard is use to match any character zero or more times.
The ? (question mark) wildcard is use to match any character exactly one time.
Files with sub-directories (e.g. mylib/xyzlib.c, mylib/*.for) and even files
with relative references to sibling directories (e.g. ../lib/abc*.c)

Absolute paths to files are supported (e.g. /path/to/alib/mystaticlib.a) and
BETA support for references to other .[c|cpp|f]lib files was also added
(e.g. libxyz.flib) (since NeXtMidas 2.7.0).

The difference between .clib, .cpplib and .flib files is that the C compiler
is used to link .clib files, the C++ compiler is used to link the .cpplib
files, and the Fortran compiler is used to link .flib files.
The .flib files are only intended for use with XBC.

Warning: For static libraries (*.a), only functions that are referenced in
your listed files will be included into the shared object by the linker. One
trick to get the necessary functions into your shared object is to have a
dummy module (e.g. refs_to_funcs_in_staticlib.c) that calls all the functions
from the static libraries and include that in your .[c|cpp|f]lib file.

The <opt>/cfg/primitives.cfg File (BETA)
----------------------------------------
Support for the primitives.cfg file in the cfg area of an option tree for host
primitives (i.e. X-Midas style build configuration) (since NeXtMidas 2.7.0).
The <opt>/cfg/libraries.cfg is also parsed (BUT NOT BUILT) to resolve all the
library names for the specified option tree (via the libdepend directive). All
valid primitives.cfg and libraries.cfg directives and conditionals are parsed.

Here are the valid directives and their description:
cflags - Compile flags for the compiler.
comment line - Lines starting with a "!" character are ignored
conditionals - Targets or directives intended to build conditionally based
on the current OSNAME or OSTYPE using the "->" arrow syntax.
Can also use "NEXTMIDAS" as a conditional value.
Can also use existences of OS environment variables as a
conditional (since NeXtMidas 3.1.2).
lflags - Link flags for linker.
libdepend - Libraries from other option trees to link the target against.
headers - Associates header files with a particular target.
This does not effect build. For documentation only.
optdepend - (primitives.cfg only) Indicates what the PATH should be when
CONVERT MSGCFG2INC generates the configured messages
C/C++/Fortran include files.
This does not effect build. For documentation only.
libname - (libraries.cfg only) parsed but ignored
modules - Associates code files with a particular target.
(parsed BUT NOT supported yet)
<targets> - host primitive or library target

Directives that are not indented below a <target> are considered global to all
targets that follow them.

See $NMROOT/nxm/sys/hlp/using_libraries.doc for a copy of X-Midas's docs for
a detailed description, syntax, and examples usages of primitives.cfg and
libraries.cfg (NOT SUPPORTED yet).

Note: OS environment variables (preceded with '$') are automatically
expanded in the following directives: cflags, lflags and libdepend for
third party libraries (since NeXtMidas 3.1.2).

Things to Note
--------------
- The /DEBUG flag will show numerous messages about the compile arguments used
which might be helpful in debugging any potential problems.

- By default the nm shell will be restarted at the end of a compilation to
ensure that the new classes are reloaded correctly. To prevent this
(especially inside a macro) use the /NOEXIT flag.

- When building with XBC support (support for host primitives in Fortran/C++)
the XBC option tree must be on the path. BUILD will automatically check for
the XM_FORTRAN or NM_FORTRAN environment variable to specify the Fortran
compiler to use. Please read the "XBC" section in the "NeXtMidas User's
Guide" for more details.

The NM_CC and NM_CXX environment variables can be used to override the
configured C or C++ compilers specified in build.props, respectively
(since NeXtMidas 2.9.2). E.g. to use Intel's icc over gcc and g++ without
having to update build.props, setenv NM_CC icc and setenv NM_CXX icc.

The NM_CC_OPTIONS and NM_CXX_OPTIONS environment variables can also be used
to add additional C or C++ compiler flags/options to append to end of
compile flags, respectively (since NeXtMidas 2.9.2).

WARNING: Native (C, C++, Fortran) libraries (*.so for dynamic or *.a static)
built in X-Midas and/or other versions of NeXtMidas SHOULD NOT be mixed and
matched and/or linked into your library or host primitive(s). Doing so will
result in random segmentation faults or errors. The reason for this
is that different version of X-Midas and NeXtMidas have different link level
API binding that are not necessarily compatible. Your code may seem to work
on occasions but don't count on it working in a production environment.
Be careful NOT mix and match these libraries, e.g. adding
-l<name_of_xm_built_lib> link flags or including anXmidasBuiltlib.[a|so]
in your .[c|cpp|f]lib. Independent libraries without any X-Midas/NeXtMidas
dependency are normally safe to link against via the -l<libnam> link flag
or in a .[c|cpp|f]lib file.

- Users who are building files that are on a shared NFS mount will need to
verify file permissions before and after the build. NeXtMidas will always
use the file system's default file visibility flags for files it creates.
Those flags may or may not match the ones required for other users to read
(or write, in the case of developers) the files.

Examples:
1. Build the class $NMROOT/nxm/sys/lib/DataOp.java:
nM> build DataOp lib

2. Build the classes Layer1D and Layer2D in the LIBG area of SYS:
nM> build Layer1D|Layer2D libg sys

3. Build all of the primitives in the ICE option tree:
nM> build all prim ice

4. Build the class $NMROOT/nxm/sys/libg/MPlot.java:
nM> build MPlot libg sys

5. Show all the compile time flags and other information to track the
build process (useful for debugging build issues):
nM> build/debug NTerminal lib

6. Build an area not in the default list of those automatically built:
nM> build all myarea myoption

7. Build all of the files in the LIB area of MYOPT but include some extra
compiler flags when building any C libraries and turning on XLint warning.
nM> results FLAGS {CFLAGS_UNIX="-DHEADLESS -DNOSPECIAL -Wall",&
LFLAGS_UNIX="-I/home/smith/clibs",&
JAVA_FLAGS="-Xlint -Xlint:-rawtypes"}
nM> build/BLDFLAGS=^FLAGS/keep * lib myopt

8. Build all the files, in all areas of the DSP option tree:
nM> build all all dsp

9. Build nxm.sys.test.junit.lib.FileUtilTest.java unit test:
nM> build FileUtilTest test/junit/lib sys
-OR-
nM> build junit/lib/FileUtilTest.java test sys

10. Build just the native (C/C++) files for SYS:
nM> build/bldtypes=native * * sys

Switches:
/BLDFLAGS= - Extra build flags to use. This is a table of values matching
the names in build.props (except the names in the table use '_'
in place of '.' and are in upper case) where the values are
extra compiler/linker options to prepend to the build.props
value. (Since 2.1.0).
/BLDTYPES= - Types of files to build (Java,Native,Host). Takes precedence
over /DOHOST and /DONATIVE. (Since 3.3.1) [DEF=ALL]
/COUNT=<res> - INTERNAL USE ONLY: Store a count of the number of files
explicitly built/compiled. A negative count generally means
there is an error. (Since 3.3.1)
/DEBUG - Turn on debugging.
/DOGENERATE - Generate new system math libraries. [DEF=TRUE]
/DOHOST - Compiles the host (C++/Fortran) files [DEF=FALSE, TRUE when XBC
is in PATH or when <AREA>=HOST].
Note: /DOHOST and /DONATIVE should usually be used together.
/DONATIVE - Compiles the native (C/C++) files. [DEF=TRUE]
/KEEP - Keep intermediate files when building. Keeps the function
prototypes nxm_<opt>_<area>.h, .o files
/NOEXIT - Prevent class reloading via shell restart. [DEF=TRUE in macro,
FALSE at command prompt]
/WARN=OFF - Suppress warning messages (e.g. when there are no java/native
source files to build). (Since 3.3.0). [DEF=TRUE]

See Also: MAKE, BUILDOPT, BLD

</pre>

[[Category:NXM_Explain]]

FOREACH

2020-04-27T22:05:08Z

ConvertBot: implements a foreach iteration loop within a macro

implements a foreach iteration loop within a macro
<pre>
<ITEM> Result label to hold item
<FUNC> Function type [INDF,INFILE,INLIST,INSIZE,INTABLE,INTF]
<IN> Variable containing input values

A FOREACH-ENDFOR combination is used in a macro to loop through each
value in a set defined by either a List, Table, or File.

Each pass through the loop, the result <ITEM> will contain the next
member of the set.

Modifiers may be added to the end of the <FUNC> name to modify behavior.
For example, INTABLE/V for key values instead of key names.

There are no restrictions nesting FOREACH loops.

Since 2.5.0 the generic IN function has been added that can iterate over
a large number of Java objects, including:
o java.util.Map (includes Table, Hashtable, HashMap, ...)
o java.util.Collection (includes List, Vector, LinkedList, ...)
o java.util.Iterator (any implementation of the Iterator interface)
o java.util.Enumeration (any implementation of the Enumeration interface)
o java.lang.Object[] (any generic Java array)
o nxm.sys.lib.Data (the values in a Data object via Data.toVector())

Notes:
o Using IN for a Map iterates over the keys in the Map, using IN/V
iterates over the values in the Map.
o The IN function only supports /REV when using an Object[].

FUNCTIONS:
INDF - Each element in a Midas data file
INFILE - Alias for INDF
INLIST - Each element in a comma separated list
INSIZE - Iterate for IN=<size>
INTABLE - Each key in a table or KeyVector
INTABLE/V - Each value in a table or KeyVector
INTF - Each line in a text file
INKW - Each keyword in a Midas file with scope
IN - Each item in a Java object (see above)
IN/V - Each value in a Java Map object (see above)

EXAMPLES:
1. Erase all files whose names are in a given data file
foreach name INDF mydatafile
erase name
endfor

2. Iterate through each item in a LIST
foreach area INLIST "MYOPT,SP,GEO,SYS"
configure c ^area
endfor

3. Iterate through each element in a FILE (0 to SIZE-1)
foreach offset INSIZE FILE(fftdemo).size
say "Data at ^offset is ^{FILE(fftdemo).data(offset)}"
endfor

4. Iterate through each KEY in a table
foreach key INTABLE msg.data
say "Key ^key = ^msg.data.^key"
endfor

5. Iterate through each KEY in a KeyVector. Produces values for layName of
GRID, WORLD and CITIES
plot/bg world|cities
foreach layName INTABLE reg.PLOT.layers
say "Layer name = ^layName"
endfor

6. Iterate through each VALUE (KEY=VALUE) in a table
foreach val INTABLE/V msg.data
say "Value = ^val"
endfor

7. Iterate through each line in a TEXT file
foreach line INTF mytextfile
say "Next Line is: ^line"
endfor

8. Iterate through each keyword in a Data file
foreach kwi INKW env.hwfile /scope=tag=alias
say "Next Key: ^kwi.name Value: ^kwi.value"
endfor

9. Iterates over a Java Vector
new java.util.Vector vect
...
foreach val IN vect
say "val = ^{val}"
endfor

Switches:
/REV - process elements in reverse order (not implemented)
/SCOPE - For INKW only. Sets the SCOPE. See KEYWORD command.
/SORT - process elements in sorted order (applies only to Tables)
/VAL - Same as INTABLE/V or IN/V

SEE ALSO: ENDFOR, BREAK, KEYWORD

</pre>

[[Category:NXM_Explain]]

BEEP

2020-04-27T22:05:08Z

ConvertBot: Emits an audio beep.

Emits an audio beep.
<pre>
<func> - ON|OFF|n, where n = number of beeps
<delay> - Delay between beeps [SECS] (<func> = n only)

Causes the system to beep. The <func>=ON and <func>=OFF may be used to turn
ON/OFF verification beeps after a command is executed (these have the same
effect as using "VERIFY ON BEEP" and "VERIFY OFF BEEP").

Examples:

nM> beep 2 2 ! Beep 2 times with 2 seconds between beeps.

nM> beep on ! Beep after completion of each command.

SEE ALSO: VERIFY

</pre>

[[Category:NXM_Explain]]

MESSAGE

2020-04-27T22:05:08Z

ConvertBot: send or get a message to/from a message queue

send or get a message to/from a message queue
<pre>
<FUNC> function to perform [QUERY]
<ID> message queue ID
<MSG> name of message object (to be) stored in results table
<NAME> message name
<INFO> message info field
<DATA> message data object

Keyword-Only Parameters:
[FROM] sender object template
[QUALS] Additional message qualifiers for SEND and REPLACE function.
(Since NeXtMidas 2.7.2)

The MESSAGE intrinsic performs numerous message handling functions at the macro
level according to the value of <FUNC>.

Not all parameters are required with every <FUNC>. Common command variations
include:
0. MESSAGE SEND[x] <ID> <MSG>
1. MESSAGE SEND[x] REPLY <MSG>
2. MESSAGE SEND[x] <ID> , , <NAME> <INFO> <DATA>
3. MESSAGE SEND[x] <ID> NAME=<NAME> INFO=<INFO> DATA=<DATA>
4. MESSAGE GET , , <MSG>
5. MESSAGE GET[x] , , <MSG> <NAME> FROM= /WAIT=
6. MESSAGE PASS <ID> <MSG>
7. MESSAGE PRUNE , , <MSG>
8. MESSAGE SYNC <ID>
9. MESSAGE QUERY

Of the above options, the two most common are #2 and #3 are the most commonly
used with #2 seen more in older code and #3 seen more in newer code.

<ID> is the id value given to a target primitive as specified by the /ID=<id>
switch on the primitive's command line. The id name can a string of any length
composed of letters, numbers, or the underscore (e.g. "MAP", "WORLD_MAP", etc.).
The use of numeric-only ids (e.g. "7") is discouraged, except when running an
X-Midas host primitive via XBC (X-Midas required numeric ids). The id of "MAIN"
is reserved for the macro that created the local registry. The list of active
ids can be seen via the REGISTRY command. The id of "REPLY" is reserved for the
macro to respond back to the sender of the message.

Messages can be sent to:
"<id>" - A command in the macro's registry with /ID=<id> or "MAIN"
for the macro itself.
"GLOBAL.<id>" - A command in the global registry. (Since NeXtMidas 3.3.0)
"PARENT.<id>" - A command in the macro's parent's registry or "PARENT.MAIN".
for the parent macro itself. (Since NeXtMidas 3.3.0)
"XM.<id>" - The X-Midas global message queue slot number <id>. Note that
this only works when using NeXtOpt; XBC is not restricted to
use of slots in a global message queue and can send messages
directly to X-Midas host primitives.
----------------------------------------------------------------------------
"REPLY" - Sends a reply back to a sender, with optional alteration of
the <NAME>, <INFO>, and <DATA> fields. (<MSG> is required
when "REPLY" is used since MESSAGE it bypasses the normal
registry ID look-up and uses the <MSG>.FROM object as the
destination in this situation, unlike the above options
REPLY only works with the MESSAGE command.)
THIS.MSGID - The registered message handler for this macro as set by the
/MSGID= switch when the macro was called. This is used as a
generic way to send messages back to target message handler
for this macro. (Since NeXtMidas 3.3.1)

A message object has the following fields:
S: msg.name the name of the message
S: msg.tid the ID of the message recipient (read-only convenience field)
S: msg.fid the ID of the message sender (read-only convenience field)
L: msg.info message-specific information encoded in an integer
O: msg.data the data object, often a table containing multiple values
O: msg.to the object/command of the message recipient
O: msg.from the object/command of the message sender
O: msg.quals the message qualifiers object, often null or a table containing
multiple key/values (since NeXtMidas 2.7.2)

Normally messages sent to a macro are written to a result named MSG and
processed by the processMessage procedure (see the "NeXtMidas Training" for
detailed discussion and examples of using processMessage). The MESSAGE command's
GET[x] function is for special handling and rarely used.

There are several reserved <NAME> values that should not be used, as they can
cause unexpected behavior in your macro, including:
ERROR
EXEC
EXIT
MACRO

Due to legacy behavior, a few messages have special behavior when sent to RMIF,
including:
ADDR - Messages sent to RMIF with this <NAME> are treated as a SENDW
OPEN - Messages sent to RMIF with this <NAME> are treated as a SENDW

Special note for XBC users:
When using XBC to send messages to/from host primitives the <DATA> will be a
Table matching the structure of a configured message or a Table with the
values for an unconfigured message. Unconfigured messages need to be sent
with TYPE= and ARGS= specified. See the XBC section in the "NeXtMidas User's
Guide" for more details. Be sure to set /MSGID=MAIN for the host primitive
in order to see the messages in the macro.

Functions:
SEND[xwr] send a message to a message queue
SYNTAX:
MESSAGE SEND <ID> , , <NAME> <INFO> <DATA> [QUALS=]
MESSAGE SEND , , <MSG> [<NAME>] [<INFO>] [<DATA>] [QUALS=]
MESSAGE SEND REPLY <MSG> [<NAME>] [<INFO>] [<DATA>] [QUALS=]

- Appending an 'X' causes the message handler to send the
message directly from the current thread, bypassing the
message queue. The handler may put it on its own queue so
this does not guarantee execution of the message.

- Appending a 'W' causes the command to wait for a maximum time
given in seconds by the value of the /WAIT switch for the
message to be executed. If no /WAIT switch is present, it
defaults to one second. This is the same as following a SEND
with a SYNC.

- Appending a 'R' causes the command to try to replace first
matching message (name and from) in queue with this message.
If not found, then message is sent normally.
Note, that option 'X' to send message directly to the handler
takes precedence over this and hence cannot be used with this
replace option. If the message was replaced, the replaced
message is put back into results named specified by <MSG>.
(Since NeXtMidas 3.3.0)

GET[wnf] read a message from a message queue
SYNTAX:
MESSAGE GET , , <MSG>
MESSAGE GET , , <MSG> <NAME> FROM= /WAIT=

- Appending a 'W' causes the command to wait for a maximum time
given in seconds by the value of the /WAIT switch before
timing out.

- Appending an 'N' forces the next message to be fetched to
match <NAME>

- Appending an 'F' forces the next message to be fetched to
match FROM=

PASS Pass a message to a different message queue
SYNTAX: MESSAGE PASS <ID> <MSG>

PRUNE Purge messages in the queue
SYNTAX: MESSAGE PRUNE , , <MSG>

QUERY Report owner and availability of command's message queue
SYNTAX: MESSAGE QUERY

REPLACE Replaces matching message (name and from) in the queue with <MSG>
SYNTAX:
MESSAGE REPLACE , , <MSG>
MESSAGE REPLACE <ID> , , <NAME> <INFO> <DATA> [QUALS=]

Replaced message is put back into results named <MSG>, null if no
message was replaced. (Since NeXtMidas 3.3.0)

SYNC Put a null message on a queue and wait for it to be processed
SYNTAX: MESSAGE SYNC <ID>

More than one suffix letter can be appended to a given SEND or GET command.
For example, GETW waits for a message to arrive, and GETN means that the
message must have a specific name. Therefore GETWN means to wait until a
message with a specific name arrives.

In most cases, the MESSAGE intrinsic quietly ignores stray characters
following the <FUNC> values shown above; however, dependence on this fact is
discouraged to minimize the chance of future macro breakage.

Examples:
1. Get the next message off the macro queue:
nM> message GET ,, msg

The message fields are now accessible from the macro language using the
standard syntax for keyable objects:
nM> say "Got a ^msg.name message from ^msg.fid"
nM> say " the info is ^msg.info and data is ^msg.data"

2. Send a message to another primitive, use the /ID= of the receiving
primitive:
nM> plot/id=plot1 ...
nM> message send "PLOT1" ,, "OPENFILE" 1 mapdata

3. To pass a zoom message from one plot to another:
nM> message get ,, msg "ZOOM"
nM> if msg.tid eqs "PLOT1" then
nM> set msg.name "ZOOMX"
nM> message pass "PLOT2" msg
nM> endif

Switches:
/WAIT=<n> Max number of seconds to wait in GETW (indefinitely if < 0).
SENDW wait time < 0 means no wait. [GETW DEF=0; SENDW DEF=1.0]
/XMTYPE=<s> Specifies the message type to use if sending the message
to X-Midas (this is ignored for normal NeXtMidas messaging).
Options include:
NEXTMIDAS - Normal NeXtMidas message.
CONFIGURED - Configured X-Midas message.
UNCONFIGURED - Un-configured X-Midas message.
AUTO - Automatic configured or un-configured X-Midas
message. (default)

See Also: SENDTO, REGISTRY, nxm.sys.lib.Message

</pre>

[[Category:NXM_Explain]]

OPTION

2020-04-27T22:05:07Z

ConvertBot: displays or defines an option tree path

displays or defines an option tree path
<pre>
<NAME> - Name of the option tree (or * to define all under specified path)
<PATH> - Path to the named option tree (or physical path when /CREATE
is used and OPT.name is a link)

This command is used to define a NeXtMidas option tree path. Option trees in
NeXtMidas are implemented using Java packages. The root package name is "nxm",
followed by the "option name", and then functional subdirectories. Use the
/CREATE switch to create a new option tree (see below).

When OPTION is used with no arguments, it lists all configured option trees.
When used with just <NAME> it shows the location of the named option tree
(see below for examples).

NOTE: The association of an option name with a particular path lasts only
as long as your NeXtMidas session. When you log in the next day, that mapping
will be gone. Therefore, OPTION <optname> <path> definitions which are
intended to be permanent are usually put in the user's %nmstartup macro.

Option trees are typically set up in the user's nmstartup.mm macro, for example:
startmacro
option ice "/user/xmopts/ice279/"
option geo "/user/geo100/nxm/geo/"
path set ice geo
endmacro

Option trees located under $NMROOT/nxm or with a link from $NMROOT/nxm/<opt>
(see below) are automatically added to the list of options and can be viewed
using OPTION with no arguments.

REQUIRED DIRECTORY STRUCTURE
----------------------------
The Java package facility requires the source file directories to mirror the
package naming scheme. The option path must point to a directory that contains
an "nxm" directory with a directory below this MATCHING the option name.

The recommended approach is to create a base directory to hold all application
required option trees under an "nxm" directory structure outside $NMROOT.
Creating your option trees in a separate directory will allow you to easily
upgrade and/or switch NeXtMidas versions without having to modify anything
under the NeXtMidas baseline. For example:
/path/to/nmopts
+- nxm
| +- myopt
| | +- cfg
| | +- mcr
| | +- prim
| | +- test
| +- coolapp
| | +- cfg
| | ...
| +- yetanotheropt --> ../yetanotheropt102
|
+- yetanotheropt102 (version 1.0.2 of user option tree)
| +- cfg
| ...

Then define the above option trees:
nM> option myopt /path/to/nmopts/nxm/myopt
nM> option coolapp /path/to/nmopts/nxm/coolapp
nM> option yetanotheropt /path/to/nmopts/nxm/yetanotheropt
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
** Notice how the <optname> must match the directory basename **

Another approach on Unix is to have a symbolic link from $NMROOT/nxm/<optname>
to the base directory of the option tree (this is the recommend approach on
Unix since most IDEs will find these option trees automatically). For example:
$NMROOT
+- nxm
+- myopt --> /home/smith/myopt123
+- sys <existing>
+- ucl <existing>

/home/smith/myopt123
+- cfg
+- prim
+- mcr

On Unix systems, this may be a also be done via a "backlink", pointing back to
the top of the tree branching off to the areas inc/lib/cfg/prim/etc (this
approach is STRONGLY DISCOURAGED and WILL CAUSE ECLIPSE, JBUILDER, ETC. TO
CRASH). For example:
/home/smith/myopt123
+- nxm
| +- myopt --> ../ <recursive link>
+- cfg
+- prim
+- mcr

On Windows (which does not have symbolic links prior to Windows Vista and the
mklink and junction commands) the option tree must be physically located under
a nxm directory and have the option tree name as its base. The version.txt
file in the option tree's root directory is the only means of identifying the
option tree's version number. This approach works on all systems
(Windows/Unix/etc). For example:
/home/smith/myopt123
+- nxm
+- myopt
+- cfg
+- prim
+- mcr
JAR FILES
---------
To use a raw Java jar (or directory of classes) with NeXtMidas, simply define
the full path name as the option then use the PATH command to add this option
to the path. For example:
nM> option JYTHON /path/to/jython.jar
nM> path add JYTHON

"OPTION" vs "RES OPT"
---------------------
When you use this OPTION command it lists ALL option trees and shows the base
directory of the option tree (this is the directory that "cfg" and "prim" are
in). The OPTION command also shows any links used (Unix only).

When you use RES OPT you are shown only the option trees not located under
$NMROOT (option trees using a link pointing from $NMROOT/nxm/<opt> to the
location of the option tree are considered to be under $NMROOT). Also
RES OPT will show the root directory of the option tree (this is the directory
that "nxm" is in).

The reason for this difference is both practical and historical. The OPTION
command shows the directory that users will be working in (when you use
"nmd . <opt>" this is where you go). Using RES OPT shows the directory that
Java needs to use on the classpath (RES OPT excludes option trees under
$NMROOT since it is already part of the classpath).

In general users should only use OPTION to find out where an option tree is
located. Macros that need to find the location of an option tree should NOT
use RES.<opt> since it does not include all option trees and is not
platform-independent (future releases of NeXtMidas may deprecate use of the
OPT table). Macro users should use the following for getting directories in
an option tree:
nM> invoke path nxm.sys.lib.OptionTree.getOptPath(<opt>,<area>)

CREATING TREES AUTOMATICALLY
----------------------------
The /CREATE switch may be used to create the option tree defined by the
result parameter OPT.<optname> where tree is the name of the option tree.
There are a number of options for creating your option tree ALL of which must
obey the Java package naming rule.

1. Create a new option tree called myopt (this is the recommend approach on
Windows and works well on Unix too). This approach also allows you to
easily upgrade your NeXtMidas version without having to modify it:
nM> option/create myopt /home/smith/myopt123/nxm/myopt

Creates the following:
/home/smith/myopt123
+- nxm
+- myopt
+- cfg
| +- commands.cnf
+- prim
+- mcr

2. (Unix Only) Create a "flat" option tree (similar to X-Midas) called myopt
with a symbolic link to it from $NMROOT/nxm/<opt>. This approach is no
longer recommended since it requires you to create a symbolic link under
the NeXtMidas baseline (under $NMROOT/nxm/ directory):
nM> option/create/link=nxm myopt /home/smith/myopt123

Creates the following:
$NMROOT
+- nxm
+- myopt --> /home/smith/myopt123
+- sys <existing>
+- ucl <existing>

/home/smith/myopt123
+- cfg
| +- commands.cnf
+- prim
+- mcr

3. (Unix Only) Create a link outside of $NMROOT/nxm pointing to the physical
option tree path (this works well for existing X-Midas option trees).

nM> option/create/link="/home/midas/nxm/" myopt /home/midas/myopt123

4. (Unix Only) Create a new option tree called myopt with a recursive link.
This keeps the option tree "flat" (X-Midas style) but uses a "back-link"
to maintain the Java package names.
(** THIS WILL CAUSE ECLIPSE, JBUILDER, ETC. TO CRASH **)

nM> option/create/link=recursive myopt /home/smith/myopt123

Creates the following:
/home/smith/myopt123
+- nxm
| +- myopt --> ../ <recursive link>
+- cfg
| +- commands.cnf
+- prim
+- mcr

5. The entire option tree can be placed under $NMROOT/nxm/ (like the option
trees that come with NeXtMidas). This will work on all platforms, but is
strongly discouraged since your option tree may be lost when you upgrade
to a new version of NeXtMidas; hence, there is no OPTION/CREATE that will
do this for you.

CONFIGURING EXISTING X-MIDAS OPTION TREES (Unix Only)
-----------------------------------------------------
There are a number of ways to configure an existing X-Midas option tree
for NeXtMidas use.

1. The recommended approach is to create a base directory to hold your option
trees under an "nxm" directory structure outside $NMROOT (see "REQUIRED
DIRECTORY STRUCTURE" section above).

2. Create a link under $NMROOT/nxm which points to the existing option tree
(this is not recommend since it requires you to modify your NeXtMidas
distribution directory).

nM> opt/create/link=NXM myopt "/home/midas/myxmopt123"

3. Create a directory called 'nxm' which is at the same level as the existing
option tree. Then place a link under 'nxm' pointing to the existing tree.
(this approach is DISCOURAGED since it can cause Eclipse and JBuilder
to crash if used to edit the NeXtMidas files in the option tree).

nM> opt/create/link="/home/midas/xmopts/nxm/" myxmopt &
"/home/midas/xmopts/myxmopt123"

USE STAR OPTION NAME (to define all option tree under specified path):
----------------------------------------------------------------------
All option trees under a specified path can be defined using the star "*"
character as the name for the option tree. This will ignore sub-directories
with dots (since that is not a valid option tree name). Since NeXtMidas 2.9.3.

nM> option * /path/to/nmopts/nxm/

The above will define the following option trees using example
directory structure from the REQUIRED DIRECTORY STRUCTURE section above:
myopt = /path/to/nmopts/nxm/myopt
coolapp = /path/to/nmopts/nxm/coolapp
yetanotheropt = /path/to/nmopts/nxm/yetanotheropt

FIND and DEFINE OPTION TREE from CLASSPATH: (Since NeXtMidas 3.3.0)
-------------------------------------------
Option trees in the CLASSPATH can be found via the /FIND switch or found and
defined using reserved "CLASSPATH" (upper-case) word for the <path> argument.

1. Find and define option tree from CLASSPATH (errors if MYOPT is not found)
nM> option MYOPT "CLASSPATH"

2. Find option tree and save it's URL/path to results, and define it if found:
option/find=myres MYOPT
if myres NisNull then
option MYOPT myres
path add MYOPT
else
warning "Unable to find MYOPT option tree..."
endif

EXAMPLES:
(See above for examples of using OPTION/CREATE to create option trees.)

1. Show all configured option trees:
nM> OPTION
Available Option Trees (<n> = index on path):
AUDIO = /home/smith/nxm240/nxm/audio/
<1> DSP = /home/smith/nxm240/nxm/dsp/
<2> HWC = /home/smith/nxm240/nxm/hwc/
MAP = /home/smith/nxm240/nxm/map/ -> /home/smith/map120/
<3> SYS = /home/smith/nxm240/nxm/sys/
UCL = /home/smith/nxm240/nxm/ucl/

2. Show a single option tree:
nM> OPTION UCL
UCL = /home/smith/nxm240/nxm/ucl/

3. Define an option tree definition for MYOPT located under the
/midas/nmopts/nxm/myopt directory:
nM> option MYOPT /midas/nmopts/nxm/myopt/

4. Undefine (remove) the MAP option tree definition
nM> option/delete map

5. Define all option trees under the /path/to/nmopts/nxm/ directory.
nM> option * /path/to/nmopts/nxm/

SWITCHES:
/CREATE - Creates the subdirectories and a stub commands.cnf for the
option tree.
/DELETE - Logically remove the specified option tree definition. The
directory is NOT removed; that must be done explicitly with the
appropriate operating system commands. I.e. this will NOT delete
option trees created with links in $NMROOT. (Since 2.7.0)
/FIND=<res>- Find <name> option tree in CLASSPATH and save path to specified
results label if specified. (Since 3.3.0)
/GET=<res> - Get a comma separated list of ALL defined option trees (not
just those on the path)
/INFO=<res>- Get option tree information parsed from version.txt/manifest.mf
such as version and required option trees. If no results label is
given then info is displayed to terminal. (Since 3.3.0)
See nxm.sys.lib.OptionTree.getInfo(..) for details of output.
/LINK= - Creates a link named by the given option tree when using /CREATE.
[DEF=null]
Options are:
NXM - Creates a link in $NMROOT/nxm
BACK - TBD - Creates an nxm directory with a back link to the
option tree directory
<path> - Creates a link in the given <path>. The path must be
quoted, i.e. inside double quotes and should generally
end with a "nxm" directory name.
/NOEXIT - Prevent class reloading via shell restart when option tree is
defined that has ever been added to the PATH. (Since 2.9.3)
[DEF=FALSE in command-line;TRUE in macro]

See Also: PATH, CONFIGURE

</pre>

[[Category:NXM_Explain]]

SINKRTP

2020-04-27T22:05:07Z

ConvertBot: Streams data to a device supporting Real-Time Protocol for audio.

Streams data to a device supporting Real-Time Protocol for audio.
<pre>
<HOST> - Host name for connection [DEF=]
<PORT> - Host port number [DEF=]
<IN> - Input Type 1000 data file
<OUT> - Output Type 1000 data file

This command streams data to a device supporting Real-Time Protocol for audio.

Currently, accepts linear 8-bit or mulaw formatted input and always outputs
linear 16-bit data to the audio driver.

Examples: TBS

Switches:
/MODE - LEFT, RIGHT, BOTH, NONE, RESYNC [DEF=BOTH]
/PORT - Port number [DEF=7101]
/PRANGE - Datagram socket range[DEF=8]
/REOPEN - Num tries to reopen if closed. For legacy behavior, if it
is given without an argument the value is 5. [DEF=-1]
/TYPE - Input audio data type (LIN8,MULAW) [DEF=NULAW]
/TL - Transfer length in BYTES [DEF=2048]

</pre>

[[Category:NXM_Explain]]

LAYER

2020-04-27T22:05:07Z

ConvertBot: creates a new plot layer and adds it to a plotter

creates a new plot layer and adds it to a plotter
<pre>
<name> - The Layer type or fully qualified class name [required]
<label> - Results label to referencing the object [required]
<table> - Table of arguments to initialize the object via the setKey interface
<plot> - The ID of plotter in which to add layer [DEF=""]

This command creates a new Layer object for attaching to a plotter. If <name>
is not a fully qualified class name, a prefix of nxm.sys.libg.Layer is assumed
(i.e. Geo, T5, XY,...).

If <table> is specified, layer.setKey() will be called for each element in the
table.

If <label> is specified, the layer is stored in the results table.
If <plot> is specified, the layer is attached to the named plotter.

The Layer classes to support plotting various types of files are:
Layer - Parent/helper class of other Layers.
Layer1D - Supports plotting Midas type 1000 files.
Layer2D - Supports plotting Midas type 2000 files.
LayerGeo - Supports plotting of geo events with TDOA/DTDOA and FDOA/DFDOA.
NOTE: If using LayerGeo directly from Java, users need to call
setRef(Object ref) to set their Midas reference in order to
use files in the RAM aux.
LayerGrid - The Grid which can be applied to nearly all other layers.
LayerImage - Supports plotting of various image types: gif,tif,jpg,png,xpm,pdf.
LayerMulti - Supports plotting Midas type 3000 files with multiple Y traces.
LayerPoly - Supports plotting Midas type 1999 files (such as world.prm).
LayerShape - Supports plotting shape and companion files (*.shp, *.dbf).
LayerT5 - Supports plotting various types of Midas 5000/5010 files:
Position - Fields: POS/VD,NAME/1A
Ellipse - Fields: POS/VD,ELPS/VD,NAME/1A
EllipseFlags - Fields: POS/VD,ELPS/VD,NAME/1A,FLAG/8B
Cone - Fields: POS/VD,POSP/VD,CONE/VD,NAME/1A
ConeFlags - Fields: POS/VD,POSP/VD,CONE/VD,NAME/1A,FLAG/8B
View the "NeXtMidas User's Guide" for more details.
LayerXY - Supports plotting Midas type 3000 files as scatter plots.

Examples:
1. Create a new layer.
nM> plot/bg/id=GPLOT
nM> new "nxm.sys.libg.LayerGeo" gl
{NAME=GEO,TDOAMODE=CONTOUR,FDOAMODE=LINE}
nM> set reg.gplot.addlayer gl
or, more simply,
nM> plot/bg/id=GPLOT
nM> layer Geo gl {NAME=GEO,TDOAMODE=CONTOUR} GPLOT

NOTE: Although NAME= is used for the Layer name here, when plotting a file
TAG= is used to change the layer name. For example,

nM> plot world{TAG=mytag}

makes the layer name MYTAG instead of WORLD. A "*" may be used to
address all layers.

2. Modify properties of an existing layer.

The layers a plot currently has are contained in "reg.<PLOTID>.layers"
where <PLOTID> is the registry ID of the plot given by the /ID switch or
the instance number of the plot.
nM> plot/bg world|cities
nM> res reg.plot.layers
K: REG.PLOT.LAYERS = KeyVector of 3 entries
O: GRID = nxm.sys.libg.LayerGrid@1c0ec97
O: WORLD = nxm.sys.libg.LayerPoly@ecb281
O: CITIES = nxm.sys.libg.LayerT5@1bb60c3

Layer methods can be invoked directly, for instance
nM> plot/bg fftdemo
nM> set reg.plot.layers.fftdemo.color RED
changes the plot trace from the default color to RED.

Messages:
None

Methods:
None

Switches:
None

See Also: nxm.sys.libg.Layer
See Also: nxm.sys.libg.Layer1D, nxm.sys.libg.Layer2D,
See Also: nxm.sys.libg.LayerGeo, nxm.sys.libg.LayerGrid,
See Also: nxm.sys.libg.LayerImage, nxm.sys.libg.LayerMulti,
See Also: nxm.sys.libg.LayerPoly, nxm.sys.libg.LayerShape,
See Also: nxm.sys.libg.LayerT5, nxm.sys.libg.LayerXY

</pre>

[[Category:NXM_Explain]]

FFT

2020-04-27T22:05:07Z

ConvertBot: performs FFTs with overlap, windowing, and optional power spectral density

performs FFTs with overlap, windowing, and optional power spectral density
<pre>
<in1> Input 1 file name
<out1> File to receive FFT|PSD of input 1
<nfft> Desired transform size. Any factor supported [DEF=1k]
<win> Name of time window to be computed and applied to the data [DEF=HANN]
<over> The fraction of <nfft> to overlap blocks [DEF=0]
<navg> Num of transforms to average in computing each output FFT frame [DEF=1]
<in2> Input 2 file name [OPTIONAL]
<out2> File to receive FFT|PSD of <in2> [OPTIONAL]
<cross> File to receive FFT of <in1> * conjugate of FFT of <in2> [OPTIONAL]

This command performs Fast Fourier Transforms on a stream of data. It replaces
the X-Midas commands FFT, MFFT, SPECTRA, and UBIQUITOUS.

The transform size, <nfft>, is exact, and must be even if the input files are
real. Performance is best if factorable by 2, 3, 4, and/or 5. There is no
upper limit on the transform size.

To output magnitude squared of the FFT bins, use the /MAG switch.
To output power spectral density of the FFT bins, use the /PSD switch.
To output MAG or PSD in 20log format, use the /LOG switch.
The /MAG, /LOG, and /PSD switches do NOT affect the <cross> output.

If <win> is one of the special codes listed in the WINDOW;DSP command, it is
computed internally, otherwise it is assumed to be the name of a file
containing a time domain window to be applied to the data.

THE FOLLOWING IS A TABLE OF ALLOWABLE WINDOWS AND THEIR PARAMETERS.
Code Sidelobe Equivalent Rolloff Window Type
Max (dB) Bandwidth (dB/Octave)
NONE -13 1.00 6 Rectangle or boxcar
BARTlett -27 1.33 12 Bartlett (triangle)
HANNing -32 1.50 18 Hanning (cosine bell)
HAMMing -43 1.36 6 Hamming (bell on pedestal)
BLACkman -58 1.73 18 Blackman
BH61 -61 1.61 6 Blackman-Harris 3 weight
BH67 -67 1.71 6 Blackman-Harris 3 weight optimal
BH74 -74 1.79 6 Blackman-Harris 4 weight
BH92 -92 2.00 6 Blackman-Harris 4 weight optimal
(* see WINDOW;DSP for details)

<over> is the fraction of the transform size, <nfft>, to overlap blocks of
data from the input file. This parameter is > 0 if overlap is desired, 0 if
blocks are disjoint with no data skipped, and < 0 for disjoint blocks with
data skipped. Legal range is (-1K,1).

<navg> specifies the number of FFTs to average in computing each output frame.
If -1, all available input data is used to create a single output frame.

The /NEXP=n switch applies exponential averaging to the output frames. The
weighting factor is 1/N for each new output frame. This does not affect the
output frame rate as <navg> does.

To remove the DC bias before computing FFTs, apply the /AC switch. This
eliminates the DC spectral sidelobes that can mask certain features of interest.

The /1D switch causes processing to finish after one output frame has been
produced and sets the outputs to be type 1000 files. This is the behavior of
the X-Midas FFT command if <navg>=1 and <win>=NONE, and the default behavior of
the X-Midas FFT command if <nfft>=-1. Combining the /1D switch with the
/PSD switch gives the behavior of the X-Midas SPECTRA command and follows the
default behavior if <over>=.5 and <navg>=-1.

The input files may be complex or real. If supplied, the second input file must
be of the same type as the first input file. The <cross> output file is only
allowed if a second input file is supplied. Keywords are only propagated from
the first input file to the <cross> output file.

The /PACK switch controls how the nyquist bin is handled for real data. The
/PACK=UNPACK switch unpacks it into its own bin which may cause sub-optimal
transfer lengths. The /PACK=DC switch packs the real part of the nyquist bin
into the always zero imaginary component of the DC bin. The /PACK=ZERO simply
drops the nyquist bin. The default is UNPACK for single frame output modes and
ZERO for multi-frame output modes.

The /PARTIAL switch is used to enable or disable the output of an extra frame if
an input file or pipe ends before providing enough data to complete the current
averaged transform (by zero-padding the input). The default behavior
(/PARTIAL=START) is to force at least one frame of output if the input stops
short before any frames have been output, but partial data received after the
first output frame will be ignored. /PARTIAL=NONE will discard any partial
frames, and /PARTIAL=ALL will force an extra frame whenever partial input data
is received, whether or not an output frame has already been written.

For example, if the input file is 700 samples and the transform size
is 1K, then default behavior is to output no results; the /PARTIAL switch forces
the input data to be zero-padded to 1K and a single frame to be output.
Similarly, if the input file size is 8,000 samples, the FFT size is 1K and navg
is 4, then the default is to output one frame whereas /PARTIAL will generate two
frames.

Examples:

1. To perform the SPECTRA command which produces a single output frame
FFT/PSD/1D infile outfile 1k hann over=0.5 navg=-1

2. To perform the FFT command which produces a single output frame
FFT/1D infile outfile 1k hann

3. To perform the UBIQUITOUS cross spectral function
FFT in1=file1 in2=file2 cross=xfft nfft=4k

4. To perform the X-Midas FFT command with nfft=-1 (means all elements); use
the win=NONE, navg=1 (default), and /1D switch.
nM> FFT/1D infile outfile nfft=-1 win=none

Switches:
/1D Output a type 1000 file. Stops processing input after producing
one output frame.
/ABSC Align input files by abscissa, FALSE to align by index [DEF=TRUE]
/AC Take out DC bias before window and FFT
/DBF Compute dB Log output using fast exponent overlay method
(good to +-.5 dB)
/DP Do double precision buffers and output if present
/LOG Output 20log of power spectral density (does not apply to <cross>)
/MAG Compute magnitude squared of FFT
/NEXP= Number of exponential averages [DEF=1]
/PSD Compute power spectral density of FFTs (scale by 1/dF)
/PACK=x Packing mode for real data (UNPACK,DC,ZERO). See /PACK switch
docs above for more details.
/PARTIAL=x Padding option for incomplete input (NONE,START,ALL) [DEF=START]
/ROTATE=F Rotate bins of complex FFT to start at -NY/2 [DEF=TRUE]
/SCALE=f Specify a scaling factor
/SMOOTH=n Exponential smoothing of output N frames deep
/TL=n if transfer length is less than <nfft>, input will be zeropadded
All consume/overlap will be based on the /TL length. [DEF=<nfft>]

See Also: SPECTRA, nxm.sys.libm.Fft, WINDOW;DSP, nxm.sys.libm.Window

</pre>

[[Category:NXM_Explain]]

FIND

2020-04-27T22:05:06Z

ConvertBot: finds file and returns its full path name or URL

finds file and returns its full path name or URL
<pre>
<FILE> - Name of file to find
<FULLNAME> - Label for full filename, including path and file extension
<AUX> - TBD - Label for auxiliary file was found on (not yet implemented)

FIND searches for <file> on the current read auxes. The file name is
specified in the usual Midas way, i.e. no extension or path information
needed (although it can be supplied if desired).

If the file is found, its full name is printed to the screen and is also
returned in <fullname>.

If the file is NOT found, <fullname> will be blank,
and a WARNING that the file was not found is given.

NOTE: If you only want to test to see if a file is there or not, use the
FEXISTS (NFEXISTS) operator of the IF command so you can branch off of the
existence of the file.

Switches:
/URL - State switch: Form a URL if TRUE, otherwise an OS dependent path name is
returned [DEF=FALSE]
/VERBOSE - Show text output

See Also: IF

</pre>

[[Category:NXM_Explain]]

UNITTEST

2020-04-27T22:05:06Z

ConvertBot: Runs a set of unit tests.

Runs a set of unit tests.
<pre>
<OPT> The option to run the unit tests for or the name of the individual test
class to run. [DEF=SYS]
<RES> The table to write the results of running the tests to. [OPTIONAL]

This will run a complete set of unit tests for an option tree. At the conclusion
of running the tests the results will be written to the table named <RES> or
will be printed to the terminal (if <RES>="").

The names of the individual tests will be read in from the unittest_config.tbl
file that should be in the test/junit directory of the indicated option tree.
The structure of the option tree should look like this:
opt
+- lib
| +- Foo (The class to test, nxm.opt.lib.Foo)
+- libg
| +- Bar (Another class to test, nxm.opt.libg.Bar)
+- test
+- junit
+- unittest_config.tbl (List of the available unit tests)
+- lib
+- FooTest (JUnit test class, nxm.opt.test.junit.lib.FooTest)
+- libg
+- BarTest (JUnit test class, nxm.opt.test.junit.libg.BarTest)

To run the test cases for a single unit test file set <OPT> to the full name
of the unit test file (e.g. "nxm.sys.test.junit.lib.UtilTest") or give the full
name of the NeXtMidas class being tested (e.g. "nxm.sys.lib.Cache").

Examples:
1. Run the unit tests for the SYS option tree:
nM> unittest SYS

2. Run the unit tests for the SYS option tree but with limited output:
nM> unittest/verbose=0 SYS

3. Run the unit tests in the class file nxm.sys.test.junit.lib.UtilTest:
nM> unittest nxm.sys.test.junit.lib.UtilTest

4. Run the unit tests for the class nxm.sys.lib.Cache:
nM> unittest nxm.sys.lib.Cache

5. Build one of the unit tests in the SYS option tree
nM> build FileUtilTest test/junit/lib sys
-OR-
nM> build junit/lib/FileUtilTest.java test sys

Switches:
/VERBOSE Turns on/off the printing to the console of the results for testing
each method.

/FAILURE Prints an informational message about each failure (this is turned
on by default if VERBOSE is on and off if VERBOSE is off).

/ERROR Prints an informational message about each error (this is turned
on by default if VERBOSE is on and off if VERBOSE is off).

/ST Print a stack trace to accompany any error or failure error messages
(this has no affect if FAILURE and ERROR are both off).

SEE ALSO: CONFIDENCE, nxm.sys.test.junit.NMTestCase

</pre>

[[Category:NXM_Explain]]

MAXMIN

2020-04-27T22:05:06Z

ConvertBot: Find the maximum and minimum values in a data file

Find the maximum and minimum values in a data file
<pre>
<IN> Input file
<MAXOUT> Results value for maximum value output (optional)
<MINOUT> Results value for minimum value output (optional)

This is a simplified version of the STATISTICS command that is used to find
the the maximum and minimum values in a file.

Examples:
1. Get the min and max values from a file:
nM> MAXMIN nxm.sys.dat.fftdemo.prm MAXOUT=max MINOUT=min
nM> res max
D: MAX = 259.27180800015543
nM> res min
D: MIN = 0.038583756802216325

This is the same as using:
nM> STATISTICS nxm.sys.dat.fftdemo.prm MAX=max MIN=min

Switches:
/VERBOSE - If ANY output results label are given, output to the screen is
suppressed unless this switch is given.

See Also: STATISTICS

</pre>

[[Category:NXM_Explain]]

SHELLGUI

2020-04-27T22:05:05Z

ConvertBot: starts a shell in a graphical window

starts a shell in a graphical window
<pre>
This command starts a shell in a NeXtMidas terminal window. See
nxm.sys.test.test_shellgui.mm for details on usage of the SHELLGUI command

Messages:
Note use MESSAGE FUNC=SENDX to directly send these message to this command.
CLEAR - Clear text in terminal window (Since NeXtMidas 2.9.0)
EXIT - Exit the shell GUI window
RESIZE - Resize the shell GUI window

Methods:
clear() - Clear text in terminal window (Since NeXtMidas 2.9.0)

Keyboard:
SHELLGUI terminal keyboard shortcuts (hotkeys).
Backspace = delete one character to left of cursor
Delete = delete one character to right of cursor
Ctrl-A = Move to beginning of line (since 3.0.0)
Ctrl-C = Copy Selected Text
Ctrl-D = Interrupt (i.e. break any running macro and exit)
Ctrl-E = Move to end of line
Ctrl-H = Move to beginning of line
Ctrl-U = Clear current input line
Ctrl-V = Paste text from system clipboard
Down arrow = Recall next command in history
Left arrow = Move one space to left
Right arrow = Move one space to right
Up arrow = Recall previous command in history
Home = Move to beginning of line (since 3.0.0)
End = Move to end of line (since 3.0.0)

Examples:
nM> SHELLGUI/theme=BoW

Switches:
/ADDPLUS- Add a '+' at the end of a line of text that is wrapped. [DEF=TRUE]
/ATTACH - Attaches this terminal to the current shell [DEF=FALSE]
/COLS - Initial number of columns [DEF=100]
/EXIT= - Mask to allow exit by COMMAND|MENU|MESSAGE|WINDOW
/FONTSZ - Font size [DEF=12]
/LINES= - Number of lines allowed [DEF=2000]
/ROWS= - Initial number of rows [DEF=30]
/THEME - THEME defines the look and feel of the SHELLGUI created
Recognized THEMEs are: DeskTop, Default, WoB, GoB, BoW, Browser,
Gear1, Gear2, Gear3, Gear4, and Nak
/VERBOSE- Display "Welcome to NeXtMidas <version> ..." message at top
[DEF=FALSE in macro, TRUE in interactive shell]

See also: nxm.sys.libg.MWText, nxm.sys.test.test_shellgui.mm

</pre>

[[Category:NXM_Explain]]

AUXILIARY

2020-04-27T22:05:05Z

ConvertBot: sets NextMidas auxiliary disk/path assignments for data files

sets NextMidas auxiliary disk/path assignments for data files
<pre>
<write> The aux for writing Midas files
<read> The | separated aux list for locating/reading Midas files
<aux 0:N> Additional entries to add to or remove from the read AUX.

This routine is used to set the auxiliary disk paths for writing and locating
Midas data files. An auxiliary, or aux, is an entry in the AUX table
containing an OS specific disk path name. In general, NextMidas uses names for
auxes instead of numbers (as in X-Midas).

If no arguments are given, the current aux settings and associated paths are
displayed.

Some 'standard' auxes common for all NextMidas systems:
CWD - Points to the Current Working Directory.
HOME - The user's login area.
HOMEPATH - The current NextMidas HOME area (usually just for user macros).
DAT - The NextMidas DAT area used to store oft-used system files.
RAM - The current shell's data pipe area.
1 - Special aux where the user name is appended to the midas data path.

At any time, a NeXtMidas user references a single WRITE AUX (ID of the default
output AUX) aux and one or more READ AUXs (list of IDs of the AUX entries to
search for a file).

+--------------------------------------------------------------------------+
| SPECIAL NOTE WHEN RUN FROM X-MIDAS: |
| When NeXtMidas is running as an X-Midas option tree the AUX path is |
| shared with X-Midas. This limits users to only using numbered AUX |
| names other than the following NeXtMidas-managed names: |
| |
| XMPIPE - The mapping of the X-Midas pipes (like AUX.RAM) |
| CWD - Alias for AUX.0 |
| HOME - Alias for AUX.98 |
| RAM - NeXtMidas RAM AUX (used for pipes/in-memory files) |
| HOMEPATH - Same as the X-Midas HOMEPATH (Mc.home_path) |
| |
| Also note that NeXtMidas will always pair CWD and HOME as "0|CWD" and |
| "98|HOME" this is beacuse X-Midas will only be able to see the numbered|
| AUX's. Also "XMPIPE|RAM" will always be added to the front of the path.|
| |
| Any alteration of the AUX table or the READ and WRITE AUX settings are |
| mapped between X-Midas and NeXtMidas. Changes in one will affect the |
| other. |
+--------------------------------------------------------------------------+

Where New Files are Written:
When writing files, Midas first searches the read aux path(s) for the
specified file. If it is found (the file already exists) it is overwritten
in that path. New files are created in the <write aux> disk path.

When any file is opened in Midas, whether for read or write, all disks in the
READ AUX are searched (open for write prefers to write to an existing file in
the read list).

What this means is that the longer your READ AUX list is, the longer it takes
to open a file for output, particularly if your aux list includes networked
disks. If your application requires the frequent re-opening of a file, you
might try specifying its aux with a qualifier:

nM> myprim myfile.prm{AUX=MYFILES}

When an AUX=value is specified as a file qualifier, that AUX will be used
and NeXtMidas will skip any checks for an existing file elsewhere on the
READ AUX.

In X-Midas, the initial read aux search is disabled if the write aux
value is negative. A similar concept has been implemented in NextMidas.
This behavior can be activated by putting a '-' before the aux value,
even if it is named and not numbered. See the examples.

Setting the READ AUX:
The <read> parameters are used to define or alter the path list used
to locate Midas data files. The syntax of <read> is as follows:

n1|n2|n3... - An ordered search list of one or more aux names separated
by vertical bars or as separate arguments.
ALL - Defines the read aux list to include all paths in the AUX
table except READ,WRITE,CWD,DAT,HOME.
-MYDIR - Removes MYDIR from the current read aux list.
+MYDIR - Adds MYDIR to the end of the current read aux list.
MYDIR+ - Adds MYDIR to the front of the current read aux list.

Also, it is possible to use the X-Midas syntax which is:
AUX <write> <read> <r2> <r3> ... <rN>
Where <r2>, <r3>, ... <rN> are additional AUXs to add/remove from the list.

Defining an AUX entry:
An AUX entry is added by setting an entry in the AUX table using SET or RES.
For example:

nM> set aux.mydata "/home/smith/mydata/"

Be careful to quote the entry when setting it, otherwise NeXtMidas will
convert it to upper case. To see that an entry is set, just use GET or
RES. For example:

nM> get aux.mydata
19S: /home/smith/mydata/

Supported AUX Entries:
NeXtMidas supports a wide array of entries in the AUX table, not just local
directories (though local directories are the most common). Some of the
resource types supported include:

Resource Type Description/Example R/W
+-------------------+------------------------------------------------+------+
| File | - Unix or Windows directory | Read |
| (FileResource) | - Unix: Use full path name | Write|
| | - "/home/smith/mydata/" | |
| | - Windows: Use full path with drive letter | |
| | - "C:\myData\" | |
| | - Windows: For network drive, use alias drive | |
| | letter or remote mount point | |
| | - "Z:\data\" | |
| | - "\\NewtorkComputer\mountdir\data\" | |
+-------------------+------------------------------------------------+------+
| HTTP | - Reads files from a URL (web server) | Read |
| (HttpResource) | - "http://my.server.com/mydir/" | Only |
+-------------------+------------------------------------------------+------+
| JAR | - Reads files from a Java Archive (JAR) | Read |
| (JarResource) | - Syntax is "jar:<archive>!<path>" (path must | Only |
| | start with a '/') | |
| | - "jar:/home/smith/myjarfile.jar!/dir/datadir/"| |
| | - To read files from a JAR on web server | |
| | - "jar:http://server/dir/file.jar!/dir/in/jar/"| |
+-------------------+------------------------------------------------+------+
| MFTP | - Midas File Transfer Protocol client (server | Read |
| (MftpResource) | is part of RMIF) | Only |
| | - Syntax is "mftp://<lport>/<rhost>:<rport>/" | |
+-------------------+------------------------------------------------+------+
| Pipe | - Handles pipes in the NeXtMidas pipe system, | Read |
| (PipeResource) | - Always defined as RAM aux, do not change! | Write|
| | - Pipes are local to the macro | |
| | - Shares RAM aux with RamResource | |
+-------------------+------------------------------------------------+------+
| RAM | - Handles in-memory RAM files. | Read |
| (RamResource) | - Always defined as RAM aux, do not change! | Write|
| | - Shares RAM aux with PipeResource | |
+-------------------+------------------------------------------------+------+
| RAM Disk | - Part of the ICE option tree | Read |
| (ICE Option Tree) | - See ICE documentation for details | Write|
+-------------------+------------------------------------------------+------+
| TAR File | - Reads files from a Tape Archive (TAR) File | Read |
| (TarResource) | - Syntax is "tar:<arch>!<path>" (path may | Only |
| | start with a '/', but this is rare) | |
| | - "tar:/home/smith/mytarfile.tar!data/" | |
+-------------------+------------------------------------------------+------+
| TCP | - TBD | TBD |
| (TcpResource) | | |
+-------------------+------------------------------------------------+------+
| X-Midas Pipe | - Handles X-Midas pipes when NeXtMidas is run | Read |
| (XmPipeResource) | as an X-Midas option tree | Write|
| | - Always defined as XMPIPE aux, do not change! | |
+-------------------+------------------------------------------------+------+

Special resource types that can NOT be included on the AUX table:

Resource Type Description/Example R/W
+-------------------+------------------------------------------------+------+
| NFILE | - Similar to FileResource but uses native code | Read |
| (NFileResource) | to increase performance for some applications| Write|
| | - Used by adding USENATIVE= qualifier | |
| | - Can NOT add NFileResource to AUX table | |
+-------------------+------------------------------------------------+------+
| Socket | - Reads/writes data from/to a socket | Read |
| (SocketResource) | - Syntax is "stp:<rhost>:<rport> | Write|
| | - Full path must be used, can NOT add a socket | |
| | resource to the AUX table | |
+-------------------+------------------------------------------------+------+
| UDP | - Reads/writes data from/to a UDP socket | Read |
| (UdpResource) | - Syntax is "udp:<port>" for input and | Write|
| | "udp:<host>:<port>" for output (<host> is | |
| | usually "localhost") | |
| | - Full path must be used, can NOT add a UDP | |
| | resource to the AUX table | |
+-------------------+------------------------------------------------+------+

Examples:
1. Display the current AUX settings and associated paths AS DEFINED (user
name is NOT substituted in for '+').
nM> AUX
Write AUX = 1
Read AUX List = 1|CWD|DAT|99|RAM

CWD = /home/smith/ <Type=File>
HOME = /home/smith/ <Type=File>
HOMEPATH = /home/smith/nxm230/nxm/sys/test/ <Type=File>
DAT = /home/smith/nxm230/nxm/sys/dat/ <Type=File>
RAM = ram: <Type=Ram>
1 = /midas/data1/+/ <Type=File>
9 = ramd:/midas/icedisk/,RAM,372M,128M <Type=RamDisk>
11 = /data11/+/ <Type=File>
12 = /data12/+/ <Type=File>
99 = /midas/opt/xmxxx/xm/dat/ <Type=File>
WEB = http://alice.techma.com/nm/nxm/sys/dat/ <Type=Http>

2. Display the current AUX settings and associated paths AS USED (user
name is substituted in for '+').
nM> AUX/LIST
Write AUX = 1
Read AUX List = 1|CWD|DAT|99|RAM

CWD = /home/smith/ <XmAlias=0>
HOME = /home/smith/ <XmAlias=n/a>
HOMEPATH = /home/smith/nxm230/nxm/sys/test/ <XmAlias=98>
DAT = /home/smith/nxm230/nxm/sys/dat/ <XmAlias=n/a>
RAM = ram: <XmAlias=n/a>
1 = /midas/data1/smith/ <XmAlias=n/a>
9 = ramd:/midas/icedisk/ <XmAlias=n/a>
11 = /data11/smith/ <XmAlias=n/a>
12 = /data12/smith/ <XmAlias=n/a>
99 = /midas/opt/xmxxx/xm/dat/ <XmAlias=n/a>
WEB = http://alice.techma.com/nm/nxm/sys/dat/ <XmAlias=n/a>

Since /LIST matches X-Midas, the X-Midas alias is included if applicable.
The alias is used with XBC (allows running X-Midas host primitives from
NeXtMidas) and NeXtOpt (NeXtMidas running as an X-Midas option tree).

3. Write new files to aux 1 and read from all available disks.
nM> AUX 1 ALL

4. Write to aux 1 and read from aux DAT. (A minimal read list reduces search
time.)
nM> AUX 1 DAT

5. Set read to all auxes except the WEB.
nM> AUX 1 ALL -WEB

6. Write to the current directory (read aux is unchanged).
nM> AUX CWD

7. Always write to aux 1 regardless if the file exists in the read aux list
nM> AUX -1

8. Always write to the current directory regardless if the file exists in the read aux list
nM> AUX -CWD

9. Remove aux CWD from the current read list, write aux unchanged.
nM> AUX ,, -CWD

10. Add aux DAT to the end of the current read list.
nM> AUX ,, +DAT

11. Set write aux to CWD, remove auxes WEB and HOME from read list.
nM> AUX CWD -WEB|-HOME

11. Remove aux WEB, append HOME, and prepend DAT from/to read list.
nM> AUX ,, -WEB +HOME DAT+

Switches:
/LIST - Display all valid auxes and their associated pathnames. Unlike
normal listing (when no parameters given) this will "clean" the
AUX paths (i.e. substitute user name for '+', remove ramdisk
parameters, etc), and will include the X-Midas alias (used
with XBC and NeXtOpt).
/LOAD=res- Load READ and WRITE auxes from the specified result. (Since 2.9.3)
/RESTORE - Restore current WRITE and READ auxes from OLDAUXREAD and
OLDAUXWRITE, respectively.
/SAVE=res- Save the current WRITE and READ auxes to the specified result.
See also /LOAD (Since 2.9.3)
/STORE - Store current READ and WRITE auxes to OLDAUXREAD and OLDAUXWRITE,
respectively.
/WARN=NO - Disable warnings about invalid read/write AUX entries. [DEF=YES]

SEE ALSO: ENVIRONMENT, FNAME, HOMEPATH

</pre>

[[Category:NXM_Explain]]