ConvertBot: Created page with "
↑ ''Go to the full list of NXM Help pages''.
=== ONLINE_HE..."

2020-04-27T18:39:28Z

Created page with "<div style="background-color: #eef9ff; border: 1px solid #999; padding: 10px;">↑ ''Go to the full list of NXM Help pages''.</div> <onlyinclude> === ONLINE_HE..."

New page

<div style="background-color: #eef9ff; border: 1px solid #999; padding: 10px;">[[NXM_Help|↑ ''Go to the full list of NXM Help pages'']].</div>
<onlyinclude>
=== ONLINE_HELP - LENDING A HELPING HAND ===
LENDING A HELPING HAND

NeXtMidas has an enormous amount of on-line help, ranging from descriptions of
commands to on-line documentation for internal library routines.

A brief summary of available help:

Command Description
-------------- ------------------------
MENU lists commands by name and/or support

EXPLAIN <command> describes <command>
DEFAULT <command> lists default values for <command>

HELP shows list of HELP categories
HELP <category> lists routines, switches, or qualifiers in <category>
HELP <routine> gives on-line documentation for <routine>
HELP/GUI a graphics interface to EXPLAIN and HELP

The HELP GUI is an simple way for beginners to learn their way around NeXtMidas.
It is also helpful to Midas veterans who need to look up a detail or two
without interrupting their current session. Give it a try!

=== SHELL - THE SHELL THAT WASN'T ===
THE SHELL THAT WASN'T

One of the best features of the NeXtMidas shell is that you don't have to be
"in" the shell to use it. All you have to do is type

nmstart

at your operating system prompt and NeXtMidas is "set up". nmstart will also
execute a user macro named %nmstartup at this time, if it exists. %nmstartup
is to NeXtMidas what LOGIN.COM is to VMS and .login (not .cshrc) is to UNIX.

As long as NeXtMidas has been started with nmstart, you can send commands to
NeXtMidas right from your operating system prompt, if you so desire.
([[NXM_Help_SHELL#ONESHOT|See HELP ONESHOT]] to see how this is done.)

But since there are a lot of nice reasons to work in the NeXtMidas shell
(see HELP FEATURES and the User's Guide), you might want to jump in by typing

nm

Now what? Are you divorced from your operating system? Must you exit to
perform any operating system command? Certainly not. Just type the
operating system command at the NeXtMidas prompt as you would at your normal
operating system prompt. If the first word of the command is not in the
NeXtMidas dictionary, the command will pass through to the operating system
beneath. If there is an NeXtMidas command with the same name as an operating
system command and you want to use the operating system's version, just
precede it with a dollar sign ($). In other words, if you are operating in
VMS and you want to use the VMS HELP facility rather than the NeXtMidas HELP,
say

NeXtMidas> $help

There is almost no reason to have to jump in and out of the NeXtMidas shell in
order to work back and forth between NeXtMidas and the operating system.

See also: HELP RUN_OS, HELP ONESHOT

=== ONESHOT - Oneshot mode is a method by which NeXtMidas commands can be performed from your ===
Oneshot mode is a method by which NeXtMidas commands can be performed from your
operating system prompt. This is nice if you do most of your work in the
operating system and only need NeXtMidas for one or two things; it is very
attractive if you need to get at an NeXtMidas command from within an operating
system script.

The standard way of invoking a oneshot command, which works both on VMS
and UNIX, is to precede the normal NeXtMidas command with "nm":

nm waveform s1

Please note that oneshot mode STILL REQUIRES that you have done an "nmstart"
to initialize a session, and you should do an "nm end" when you are done.

Also beware of "vanishing metacharacters": since you are executing from
the O/S shell, it may process and remove things like double quotes on its
own. There is no way around this in DCL.

With UNIX, it is usually safest just to enclose the entire command in single
quotes, so that everything inside will be preserved as literal:

nm 'say "hello"'

=== INTERACTIVE - THE OLD SHELL GAME ===
THE OLD SHELL GAME

Although you can issue commands from either within the shell or outside of
it, there are several interactive features of the NeXtMidas shell that make it
preferable to work from inside it. (All of the other features work from
either inside OR outside the NeXtMidas shell.)

Total Recall ==============

One of these is command recall with a keystroke. By hitting the up arrow,
you can recall the last command you just typed and get a chance to edit it
before issuing it again. Hitting the up arrow repeatedly moves you further
back through the history of commands for this NeXtMidas session. Hitting the
down arrow moves you "forward" through the list.

There is also recall ability which will recall any recent command beginning
with the letters of its argument. For example,

nM>!wave

will recall the most recent command beginning with "wave".

Before hitting <RETURN> to send a command, the line itself can be edited with
the following keys:

Left and Right Arrow Keys -
move your cursor left and right through the command.
CTRL-A - toggles insert mode.
CTRL-H (Home) - jumps cursor to beginning of line
CTRL-E (End) - jumps cursor to end of line
CTRL-U - deletes the entire line

(VAX) CTRL-J Delete word
(UNIX) CTRL-W Delete word

If you are a SunOS UNIX user, you may have found that when you are using an
OpenWindows shelltool with the scrollbar turned on, the arrow keys do not
work. The following aliases are provided for UNIX users:

CTRL-P (Previous) or CTRL-B (Back) - Up Arrow
CTRL-N (Next) - Down Arrow
CTRL-F (Forward) - Right Arrow
CTRL-D - Left Arrow

When using a shelltool with a scrollbar, you should also be aware that when
insert mode is on, it will not look like you are inserting characters even
though you are.

See also: EXPLAIN HISTORY.

Looking For An Argument =====

Many NeXtMidas commands have a large number of arguments. You can use the DEFAULT
command to help you out here, but one even more useful shell feature will prompt you
for each argument in turn.

Simply end the command (however much you've typed) with a question mark (?)
and hit <RETURN>. NeXtMidas will give the meaning of each argument, one line
at a time, together with its default value. When you have "answered" each
one, NeXtMidas will show you the command it has built. You can edit it further
if necessary before hitting <RETURN> to send the command.

If for some reason you need a final literal question mark for your command,
just end your command with two (??) and they will be translated to one. No
command prompting will take place.

=== CALCULATIONS - A CALCULATED ADVANTAGE ===
A CALCULATED ADVANTAGE

One of the most heavily used features of NeXtMidas is its ability to perform
in-line calculations. You can stick a complex mathematical formula or
logical tests anywhere a single number would go; this formula can even
include the names of numeric results parameters, as they are interpreted
as symbolic numeric constants. For example, the command

nM> waveform OUT=s1 PHASE=2*pi+(3/4)-phase

produces exactly the same effect as

nM> calc frequency 2 pi * 3 4 / + phase -
nM> waveform out=s1 freq=frequency

(assuming, of course, that PI and PHASE are results parameters set ahead of
time to numeric values.)

You can always write any number in scientific or engineering notation. For
example, 2.146 x 10^7 is written in NeXtMidas as 2.146e7 . If you think in
multiples of 10^3, as in 21.46 MHz, you can write that as 21.46e6 . 165.2 mA
can be 165.2e-3 . NeXtMidas takes care of it all.

Certain applications work well with powers of two (or multiples thereof)
rather than powers of ten. You may find yourself often wanting to write
values such as 2**10 or 3*(2**20). Two short NeXtMidas abbreviations are K for
2**10 and M for 2**20. 9k means 9*(2**10) and .6M means 0.6*(2**20).

The available operators for in-line calculations are: addition (+),
subtraction (-), multiplication (*), division (/), and exponentiation (**).
You can also use parentheses to group expressions. For more sophisticated
functions such as logarithm or minimum, use the CALCULATOR intrinsic in-line
via the syntax:

nM> sincosine s1 ,,,, calc(phase,0,max,360,min)

The arguments for the calc() inline function are the same as the CALCULATOR
intrinsic. The logical() inline function supports all of the tests available
with the IF and WHILE intrinsics, returning a 1 for true and 0 for false.

For example, the following command sets SINCOSINE's phase parameter to 180
degrees if A is greater than B or the file INVFILE exists, and zero if not.

nM> sincosine s1 ,,,, 180*logical(A,gt,B,or,INVFILE,fexists)

You can also directly use the values of existing switches in calculations.
For example:

nM> calc/sw=45 ans 10*/sw+3
ANS = 453.00000000000

The contents of a Midas file's header control block is also available in
a results like syntax for inline calculations via the syntax:

nM> constant outfile template(hcb.f) template(hcb.sz) 0 0 &
template(hcb.xs) template(hcb.xd) template(hcb.xu)
nM> results outfile(hcb.key.comment) template(hcb.key.comment)

where "template" is a Midas file. See HELP FEATURES VECTORED for more.

A few words of caution:

1. The precedence of operators in any in-line calculation is strictly
left to right. In other words, 2+4*5 will evaluate to 30, not 22. Use
parentheses whenever you want to indicate a different precedence.

2. Never put any spaces in the middle of an in-line calculation. Spaces and
commas separate arguments in NeXtMidas, and you want the entire calculation to
be perceived as a single argument.

3. In-line calculations usually fail as you would expect with strings that
are incomplete or don't make sense, such as "100**" or "+*/". But some
strings that seem to be nonsensical sometimes have an interpretation; for
example, "100+/" evaluates to 99, since the "/" is taken to be a switch
reference (it is not preceded by an operand) to a switch with no name. A
no-name switch is considered absent and therefore has the value of -1.
100 + -1 = 99.

See Also: EXPLAIN CALC

=== SUBSTITUTION - ACCEPTING SUBSTITUTES ===
ACCEPTING SUBSTITUTES

One use of results parameters (see EXPLAIN RESULTS) is just to store values
so you can look at them. But the most powerful use of them is to substitute
their values for their names wherever those names appear.

Often, the value of the result gets substituted automatically. For example,
if a name is given where a number is required, NeXtMidas searches for a numeric
result with that name, and if found, substitutes it value.

You can also store ASCII strings (such as filenames) in result parameters.
The following:

nM> res fname sine1
nM> sincos fname

is equivalent to

nM> sincos sine1

If the ASCII result exists, it is substituted. If FNAME was the name of a
numeric results parameter, its value would not be substituted and the sine
wave would have been written to a file named FNAME.

But sometimes the substitution is not automatic and you have to force it. One
major example is the forcing of substitution within double quotes. Normally
NeXtMidas does not look at anything inside double quotes; it will not uppercase
anything, remove any spaces, or substitute any result parameters. (See HELP
METACHAR for more information.) But by preceding the name of a result with a
caret(^), you can force result substitution anywhere. The command:

nM> say "The value of FNAME is ^FNAME."

will produce

The value of FNAME is SINE1.

Some commands expect the name of a results parameter, not the value of one.
For example, STATUS can write various fields of the given file header into
results parameters, if given. The following command will put the size of the
file SINE1 into a result named FSIZE:

nM> status sine1 fsize

But what if FSIZE contained the name of the result you wanted the file size
to be stored in? The sequence

nM> res fsize sizeofsine
nM> status sine1 fsize

will still store the size of SINE1 in FSIZE, not in SIZEOFSINE as you wanted.
The sequence

nM> res fsize sizeofsine
nM> status sine1 ^fsize

will do it.

See Also: EXPLAIN RESULTS, HELP SCOPE

=== VECTORED - THE ONE AND THE MANY ===
THE ONE AND THE MANY

The NeXtMidas results table can handle scalar, atomic, and array data. However,
most large vectors are best stored as files so they can be operated on by
primitives. Vectored results are a way to reach into a file to retrieve or
store values with a result-like syntax.

For a one-dimensional file (type 1000), put the number of the element you
want to access in parentheses after the file name. For example, if you
wanted to print out the eighteenth element of the file R1, you could write

nM> say "The eighteenth element of R1 is ^R1(18)."

and you would get

The eighteenth element of R1 is 17.6331.

Or, if you wanted to assign it to another result:

nM> res temp r1(18)
nM> res temp
D: TEMP = 17.633100509644

If the file is two-dimensional (type 2000), then you must give the result
name two arguments: frame ("row"), and index ("column"). To get at the 46th
element of the 20th frame, write

nM> res temp r1(20;46)

where R1 is a type 2000 file.

If the file is record-oriented (type 3000), two arguments are needed: the
record number and either the subrecord name (preceded by a tilde) or the
subrecord index. For example, given R1, a type 3000 file whose 5th subrecord
is named "LOC", retrieve the value of that subrecord in the 10th record:

nM> res temp r1(10;5)

or, more readably,

nM> res temp r1(10;~LOC)

The individual scalars within a vectored result atom can also be accessed
directly using an extra ; to specify the scalar of interest. See HELP
FEATURES ATOMIC for more.

The contents of the file's header control block (including keywords) is also
available in a results like syntax as:

nM> say "The size of R1 is ^R1(hcb.sz) elements."

The HCB.xx syntax supports all of the tags used in STATUS and HEADERMOD for
positionally independent parameters. The HCB.KEY.keyname accesses a keyword
named "keyname" and HCB.SCOPE can be used to scope for the keyword access (if
the file is an environment file that remains open - see below).

For example:

nM> constant outfile template(hcb.f) template(hcb.sz) 0 0 &
template(hcb.xs) template(hcb.xd) template(hcb.xu)

nM> results outfile(hcb.key.comment) template(hcb.key.comment)

creates a file of zeros with the same format, size, abscissa info, and
comment as the existing Midas file called "template".

There are two major advantages to this sort of syntax:

# In addition to retrieval, you can also store directly into an existing
#: file. For example, if you wanted to reach into the file DATAPOINTS and
#: change its fifth element to 0, you can just say

nM> res datapoints(5) 0

# The ability to create a file out of nowhere. For example, if the file
#: AVERAGES does not exist, and you say

nM> res averages(1) 5/(6+10)

the file AVERAGES will be created and 0.3125 will be its first element. You
can therefore pull vectored results "out of the air" just like any scalar
result. This can be really useful in combination with the FORALL command.
The following command stores the sizes of each file RAMP1 through RAMP20 into
a result vector named SIZES, which does not yet exist:

nM> forall <nowiki>#</nowiki>=1:20 status/quiet ramp<nowiki>#</nowiki> sizes(<nowiki>#</nowiki>)

Furthermore, you can deal with this vectored result either as a series of
results or a file. After the example above, if you wanted to find out what
the largest and smallest file sizes were, you could type

nM> maxmin sizes

By default, the format of the created vectored result is SD (Scalar Double).
If you need a different format, use result-style typecasting, as in:

nM> header/create datapoints FORM=SB ! will create a SB-format file
nM> res FILE(datapoints).setdata(0) 50 ! will set the first element

Once created, however, the file retains that format and will automatically
convert new values without use of typecasting:

nM> res FILE(datapoints).setdata(1) 50.6 ! will be stored as 50

VECTORED RESULTS - HELP IS TBD

See also: EXPLAIN FORALL, EXPLAIN ENVIRONMENT, EXPLAIN AUXILIARY

=== SCOPE - SAYING WHEN ===
SAYING WHEN

When you prefix a result name with a caret (^), NeXtMidas attempts to
substitute the entire result name. This means all continuous alphabetic
characters, digits, the underscore, and, if followed by an open parenthesis,
everything up to the closing parenthesis. However, this is not always what
is desired. You can scope the substitution of the result name by the use of
the curly braces { } . When you follow the caret with an open curly brace,
only those characters up to the closing curly brace are considered for
substitution.

For example, suppose you have a result named FILE which contains some
filename. You want to look at the status of the file whose name is the value
of FILE followed by the number 123 (e.g., if the value of FILE is SINE, you
want to see the status of SINE123). So you merrily type

nM> status ^file123

But what NeXtMidas will do here is look for a result named FILE123. Not
finding it, the STATUS command will try to give the status of a file named
FILE123, which does not exist (in this example, anyway). What you should say
is

nM> status ^{file}123

This time, the caret only applies to the letters "file", which is translated
into (for example) SINE, so that what the STATUS command gets is the name
SINE123.

Often it is necessary to use scoping within double quotes. Suppose that you
have the number of a widget in WNUM. You want to SAY the value of that
widget, which you know is referenced by the name "W_" followed by the widget
number. There are two ways to do this. The first way assigns the widget's
value into a temporary result, then SAYs it:

res temp W_^wnum
say "The frequency width is ^temp."

But you can do it in a single line with scoping:

say "The frequency width is ^{W_^wnum}."

Note that the following will NOT work:

say "The frequency width is ^W_^wnum."

because W_ is being substituted at the same "level" as WNUM. The scoping
above makes sure that the entire section within curly braces is substituted
as a single result AFTER making the substitutions within.

=== FILES - HAVING IT YOUR WAY ===
HAVING IT YOUR WAY

In NeXtMidas you can supply an explicit path and extension, if you like. If you
supply this path and extension, NeXtMidas will look for that file. Omitting a
pathname lets NeXtMidas search the aux list, as usual; omitting an extension lets
NeXtMidas use its defaults of .tmp or .prm . The ability to specify an explicit path
or extension helps when you want to refer to a file that is not on the standard aux
list.

BLUE files also contain information as to the data representation of both their
header and their data. Because of this, when a library routine reads data from a
file whose machine data representation is not that of the host machine, it can
convert it as it is read (or written). This means that you can, for example, create
a file on a VAX, transfer it directly to a Sun, and the NeXtMidas on the Sun can use
the file without any special protocol to make it readable.

There are special auxiliaries:

1. This aux points to ../data1/+/ (UNIX) where + is replaced with
a user name
11. This aux points to ../data11/+/
12. This aux points to ../data12/+/
99. This aux points to a special global data directory
($XMAREA/dat on UNIX, XMAREA:[DAT] on VMS).
CWD: This aux always points to your current directory, changing as your
current directory changes.
DAT : This aux points to the SYS option, DAT area.
HOME: This aux points to your home directory.
HOMEPATH: This aux points to your current user macro homepath (see EXPLAIN
HOMEPATH), changing as you change your homepath.

Another nice new feature is the ability to use file qualifiers.

See Also: HELP Qualifiers

=== TRIMMING - JUST A TRIM, PLEASE ===
JUST A TRIM, PLEASE

There are many times when you might like to look at just a piece of a file:
say, the first 300 elements, or the part between 1.5 and 3.5 seconds.

See User's Guide -> Files -> File Trimmers for more information and examples.

See Also: HELP TRIMMERS

=== METACHARACTERS - There are several characters that have special meaning to the NeXtMidas shell. ===
There are several characters that have special meaning to the NeXtMidas shell.
Their function and precedence (from highest to lowest) is given below:

Character Position Function

& end Continues command to next line. In a macro, the line
following will be concatenated without its leading
white space.

&& end No continuation, becomes literal final &

? end Prompts for command arguments. Does not function
within macros.

$ start Forces command to operating system. Required before
all operating system commands in a macro.

$$ start (UNIX) Forces command to be executed in the shell
which is running NeXtMidas (rather than in a subshell).

! start Recall previous command from the shell.
Designates command line as comment in a macro.

! anywhere In a macro, designates beginning of inline comment
(except within double quotes).

/ after
command
name Applies following switch to command.

, between
arguments Separates arguments.

space between
arguments Separates arguments.

^ before
name Forces the substitution of the result or macro
argument name following.

{} after ^ Defines the range of characters to which the
caret (^) applies.

" " around
argument Preserves characters bracketed by " " as a literal
STRING argument, leaving their lowercase characters
and white space alone.

% before
macro name Designates the macro as a user macro.

underscore
(_) before
file name (the underscore) Designates file name as the name
of a pipe in a piped macro.

() after
file name Treats characters bracketed by ( ) as a file name
qualifier; depending on the operators within the
parentheses, may indicate a vectored result, in-line
trimming, or some file attribute to modify.

() around
expression Groups expressions in an inline calculation.

[] after macro
argument Defines the default for that argument in a user macro.

[] within
ASK prompt Defines the default for the ASK prompt.

: between
type and
name Separates type from macro argument or result label.

: in trim
qualifier Separates start from end.

; in vectored
result name Separates row and column for Type 2000 files.

=== in - qualifier ===
qualifier
or
vectored
result Designates following value as abscissa rather than
index.

</onlyinclude>
[[Category:NXM_Help]]

NXM Help SHELL - Revision history

ConvertBot: Created page with "↑ ''Go to the full list of NXM Help pages''. === ONLINE_HE..."

ConvertBot: Created page with "
↑ ''Go to the full list of NXM Help pages''.
=== ONLINE_HE..."