The following pages contain a listing of the instructions given to the user by the Tutorial. This listing should be kept handy while running the Tutorial because its instructions are sometimes overwritten by some VICAR modes (e.g., TUTOR Mode).
In the following listing, the places where the Tutorial expects user input are marked by the NUT> prompt.
Invocation of the Tutorial is accomplished as shown in this example.
Example: Invoking New User Tutorial
VICAR>NUT
The NUT is currently only available on VMS systems. A UNIX version
will hopefully be available in the near future.
10.14.1 New User Tutorial Listing
This is a training session in basic VICAR concepts and functions.
This session is for users familiar with DCL (DEC's Command Language
under VMS), but not with VICAR. Users not familiar with DCL are
advised to run the VMSCAI tutorial in DCL.
This tutorial introduces common VICAR operations, with the
detailed descriptions left to the VICAR USER'S GUIDE. A copy of
the VICAR USER'S GUIDE should be kept handy because the last Section
thereof contains a printed version of this tutorial for reference.
This tutorial will, at times, instruct the user to type various
commands. Follow all such commands with a Carriage Return. It will
behoove the tutee to make the entries exactly as requested, lest the
tutor become confused.
Press RETURN to proceed...
NUT>
..................................................................
.......................EXITING THIS SESSION.......................
..................................................................
The best way to end this tutorial at any NUT> prompt
is to type QUIT. If you want to skip portions of this
tutorial, just respond with Carriage Return at the prompts.
Of course, some steps require the results of previous steps, so
watch out.
You can always get out of any VICAR operation (including this
tutorial) with a CONTROL-Y keystroke if you are desparate (your
entire VICAR session will end). A more graceful way to abort any
VICAR operation is with a CONTROL-C keystroke. You will be
prompted by the interrupt handler.
To abort the operation, but remain in VICAR, respond with: ABORT
To continue the operation, respond with: CONTINUE
Try this now. Type CONTROL-C, but respond with CONTINUE to return here.
NUT>
Good, you made it back. Now on to the meat of the tutorial.
..............................................................
................SAVING YOUR SESSION LOG.......................
..............................................................
Because this is a training session, you should have a listing of
this interactive session for future reference. Therefore, before
you go any further, tell VICAR to save this session in a file to
print later. Type ENABLE-LOG.
NUT>
What you just entered is known as an Intrinsic command. If you
want to get technical, ENABLE was the command and LOG was the
sub-command. You will be doing more of those later in this session.
A list of the available Intrinsic commands may be found in the
VICAR USER'S GUIDE Section 10.4 or you can use HELP (see below).
..................................................................
.......................USING VICAR HELP...........................
..................................................................
VICAR makes available several kinds of user aids. The most
obvious is the extensive HELP utility. To find out its capabilities,
ask for HELP on the HELP command by typing HELP HELP. Within the
utility, type any of the listed choices, but end by typing EXIT.
Now, type HELP HELP and return here with EXIT.
NUT>
Now that you have read about HELP, run it to get information on
available Intrinsic Commands. These are commands which interact
with the VICAR Executive rather than execute programs. As a matter
of fact, you have already used such Intrinsic Commands. You
used ENABLE-LOG and HELP.
Type HELP and page through the text to see what other
Intrisic Commands are available, and end with EXIT to return here.
NUT>
Get HELP on an individual command. Type HELP ENABLE-LOG and return
here with EXIT .
NUT>
To obtaqin general HELP on VICAR, type HELP VICAR, type any listed
choices and return here with EXIT.
NUT>
There is also HELP on more specific areas of VICAR. For instance,
information on a particular program may be requested. Type HELP COPY
and return here with EXIT .
NUT>
Another HELP function deserves mentioning. You may wish
to have the documentation for specific programs written to a
disk file in your directory. The file thus created may be listed
on terminal or line printer. Use HELP's subcommand HARDCOPY to
get the documentation, for program COPY, type HELP-HARDCOPY COPY.
NUT>
Check your directory for that documentation file. Type
DIR COPY.MEM .
NUT>
..................................................................
.......................GETTING HELP ON ERRORS.....................
..................................................................
Occasionally, users will make errors. VICAR will respond with a
brief error message. For example:
[TAE-NOPROC] Unable to locate proc `SNAFU'.;
line 4 in internal proc `ERR' in proc `NUT'
At this point, you can obtain a more detailed description of the
error. You may access HELP for the last error by just typing: ?.
After reading the explana tory text, you return to your session
by typing: EXIT.
Try this on that error we got. Type ? .
NUT>
..................................................................
.......................VICAR LIBRARIES............................
..................................................................
Now that you are in the VICAR environment, you have access not
only to the files in your directories, but also to the numerous VICAR
libraries of utilities and applications programs. Whenever you
attempt to execute such a VICAR utility or program, VICAR searches
its libraries to find the name that you requested. To see what
libraries you are accessing, use the Intrinsic command SHOW.
Type SHOW.
NUT>
The Command SHOW lists User Library first, followed by Application
Libraries (LIBLST) and System Library (TAE$LIB). To see what
Application Libraries are, Type DCL SHOW LOGICAL LIBLST.
NUT>
The search hierarchy begins with your directory (at the top) and
works its way down until the module is located. To illustrate
this, I will arrange for the module's library name to be listed
when a module is executed. Try invoking the module V2VERSION.
Type V2VERSION to see where that module is found.
NUT>
That module was found in MIPL:[MIPL.SYSLIB] ,
aka V2$SYSLIB. If you had a V2VERSION in your directory, VICAR
would have used your version.
You may change the order of the libraries (directories) or add
to the hierarchy. Use the Intrinsic command to put the directory
pointed at by the logical name STARLIB into the hierarchy.
Type SETLIB (STARLIB:,*).
NUT>
Check the results by again typing SHOW.
NUT>
Notice that the new library went ahead of all the others, except
your current default directory. "All the others" was represented by
the * in the SETLIB command.
Getting rid of a search directory is just as simple. Type
SETLIB-DELETE STARLIB: .
NUT>
Now verify the action with another SHOW.
NUT>
..................................................................
.......................VICAR DCL MODE.............................
..................................................................
VICAR provides a way to execute DCL commands while still in the
VICAR environment. In the DCL Mode of VICAR, almost all DCL commands
will function. Now get into DCL mode.
Type DCL .
At the _$ prompt execute a DCL command like SHOW TERMINAL .
To return to VICAR, type VICAR or EXIT (at the _$ prompt).
NUT>
DCL commands may also be executed without leaving VICAR's
command mode. Type DCL SHOW PROCESS.
NUT>
..................................................................
.......................VICAR TUTOR MODE...........................
..................................................................
Up to now, you have been interacting with VICAR in Command mode.
There will be more of that a little later, but users need the
ability to invoke programs or procedures to do the bulk of their
work. VICAR has the capability to assist users in running such
modules. The mode called TUTOR allows users to have access
to HELP on parameters while defining parameter values.
Invoke the TUTOR for module GEN by typing: TUTOR GEN
At the TUTOR prompt, give parameter
OUT the value A OUT=A
Save this set of parameter
values (including defaults): SAVE
Return here without executing the module: EXIT
These instructions will disappear while you are in TUTOR,
but this session is listed in the VICAR USER'S GUIDE.
Start with TUTOR GEN.
NUT>
You gave the parameter OUT a value of A, saved those parameter
values for later and then EXITed. Now bring those parameter
values back and run the program GEN.
Invoke the TUTOR for module GEN: TUTOR GEN
At the TUTOR prompt, recall
the SAVEd set of parameter values: RESTORE
Let the module execute: RUN
You will return here after the program GEN is completed.
Start by typing TUTOR GEN.
NUT>
..................................................................
.......................VICAR DATASET NAMES........................
..................................................................
You have created an image with characteristics based upon the
program defaults and user-input parameter values. Now do a
directory on it. Type DCL DIR A.
NUT>
Note that the file has a "dot Z" file type. If no file type is
specified by the user for a file, this is what is created. The
numbers after the Z are process-specific. ALL FILES WITH SUCH
"
'DOT Z' FILE TYPES ARE DELETED AT LOGOFF.
..................................................................
.......................VICAR LABELS...............................
..................................................................
As with all VICAR files, the file that you GEN'd has a
VICAR label. List out the label with the program LABEL by
typing LABEL-LIST INP=A .
NUT>
The label not only contains the file attributes, but may hold
user- or program-supplied label items. Add a comment using the
program LABEL by typing :
LABEL-ADD INP=A OUT=B ITEMS="COMMENT=`HOWDY'" .
NUT>
List the label again by typing
LABEL-LIST INP=B .
Notice that the added label appears below the previously added items.
NUT>
..................................................................
.....................COMMAND LINE SYNTAX..........................
..................................................................
The last couple of lines you typed actually invoked programs rather
than Intrinsic commands. Notice that the command line consisted of:
1) a PROGRAM or PROCEDURE name for VICAR to find and execute,
2) one or more PARAMETER_NAME=VALUE specifications to control execution.
In the last case, LABEL-LIST INP=B
LABEL-LIST was the program name,
INP was the parameter name (specifically the input file name),
B was the parameter value to be used in this execution.
..................................................................
.......................THE PIXEL DATA.............................
..................................................................
Most VICAR programs alter the pixel data of the file.
Use the program LIST to look at the pixel data of the file you
just created. Type LIST INP=B .
NUT>
Of course, sometimes you may not want to see (or process) the entire
image. In this case, you should specify the area you wish to process
by using the VICAR SIZE parameter. This parameter is standard for
almost all VICAR programs, and has the format:
SIZE=(starting_line,starting_sample,#lines,#samples)
Try using the SIZE field to look at a portion of your file A.
Type LIST INP=A SIZE=(4,2,5,5)
NUT>
Now alter the pixel data of your file A with program F2
by adding 50 to each value. This will create a new file with
different pixel values. Type F2 INP=A OUT=B FUNCTION="IN1+50" .
NUT>
Look at what has happened to the pixel data now in B.
Type LIST INP=B SIZE=(4,2,5,5)
NUT>
We only looked at a portion of the file, but, yes, all the
pixels were altered. To verify this, leave off the SIZE field.
Type LIST INP=B .
NUT>
OK, the pixel data was changed, but what about the labels.
Look at the label of the new file B. Type LABEL-LIST INP=B .
NUT>
Notice that VICAR added an item to the label indicating what
processing occurred, as well as when and by whom. Because this
is a system function, all processing steps are so documented and
in a standard way.
You probably noticed that we used the file B as an output
file twice. VICAR never creates new version of a file. It always
writes over the same version (perhaps updating the size) without
updating the creation date and time. Do a VICAR directory command
to see the .Z* files you have created. Type DIR *.Z* .
NUT>
..................................................................
.......................DEFINING VICAR COMMANDS....................
..................................................................
This DIR command may not have told you all you wanted to know. You
could do a DCL DIR *.Z*, but you can also define a new command within
VICAR to do the job. The DEFCMD command will define strings to be
commands. Type DEFCMD DIRX "DCL DIR/SIZE=ALL/OWNER" .
NUT>
Now try your new command DIRX. Type DIRX *.Z* .
NUT>
..................................................................
.......................COMMAND QUALIFIERS.........................
..................................................................
Earlier in this session, you ran program GEN by restoring saved
parameter values in TUTOR. You can do the same thing from Command
mode by using Command qualifiers. These qualifiers are independent
of the command or program being invoked, they merely alter how the
invocation is done. Invoke GEN again with the same parameter values
from a command line by typing GEN |RESTORE=GEN| .
NUT>
The RESTORE qualifier indicates that VICAR should be able to find
the parameter values in a file called GEN.PAR saved from the
TUTOR SAVE command.
Another useful Command Qualifier will direct the output of an
invoked command to a disk file that may be printed. List out
your GEN'd image to a file by typing LIST |STDOUT=TEMP.LIS| INP=A .
NUT>
Verify that the file TEMP.LIS contains the listing by typing
DCL TYPE TEMP.LIS .
NUT>
..................................................................
.......................USING BATCH QUEUES.........................
..................................................................
Well, you're not going to do all your work on a terminal, so you
need to know how to initiate a batch job. The VICAR USER'S GUIDE
tells how to set up the job stream files called procedures, which
is the most common use of batch. However, you can just execute
one module in batch, which is what you will now do. First, find
out what the batch queues are called at your facility. Do this
by typing DCL SHOW QUE/BATCH .
NUT>
There may be more than one batch queue, so find the one in which
jobs run immediately (probably called FAST or something like that).
Use another Command Qualifier to submit a module to the batch queue.
Type LABEL-LIST |RUNTYPE=(BATCH,FAST)| INP=A .
NUT>
..................................................................
.......................LOG FILES..................................
..................................................................
When the module is finished executing, the output will reside in
a disk file called LABEL.LOG which may be listed. Wait for the
message indicating job completion and type DCL TYPE LABEL.LOG .
NUT>
Job streams or procedures which contain lots of invocations and
commands are completely analogous to what you just did. They are
submitted to a queue the same way and also result in a .LOG file.
..................................................................
.....................FINISHING UP.................................
..................................................................
We are done with most of this tutorial session. In order to print
out the session log file, the logging function must be disabled.
Type DISABLE-LOG.
NUT>
Now that the log file is free, print it on the local printer. But
first determine if the symbol P168 exists. Type DCL SHOW SYM P168 .
NUT>
If the P168 is defined, use it instead of PRINT. Either way,
type DCL P168 SESSION.LOG or DCL PRINT SESSION.LOG .
NUT>
..................................................................
.......................VICAR MENU MODE............................
..................................................................
You have tried out VICAR Command mode and TUTOR mode. There is
one other mode to play with called MENU mode. Before starting that
up, remember that many details that this Tutorial session cannot
instruct you on are explained in the VICAR USER'S GUIDE. Every
user should have one.
The final act of this tutorial will be to turn you loose in the
VICAR MENU mode. A system-wide MENU has been set up to guide users
to VICAR programs based upon the functionality required. The
MENU is rather self-explanatory, but recall that you can always
ask for HELP.
Invoke the MENU mode by typing the command MENU. Happy trails!
NUT>
If you wish to return to the Contents page, click here.