SWITCH
From ICE Enterprises
Define static switches or get a switch value into a results parameter
<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]
