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