NXM Help SHELL

↑ Go to the full list of NXM Help pages.

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. (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:

1. 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

1. 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 #=1:20 status/quiet ramp# sizes(#)

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.