10.14 The VICAR New User's Tutorial

The VICAR New User's Tutorial is a VICAR proc residing in one of the VICAR libraries. It is designed to introduce some of the basic VICAR concepts in a hands-on mode.

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