7 The VICAR Image Processing Executive

7.1   Introduction to the TAE Command Language (TCL)
    7.1.1   TCL Command Line Rules   Abbreviations   Line Continuation   Labels   Special Characters   Special VT100 Terminal Keys   Command Line Editor
    7.1.2   Variables   Local Variables   Global Variables   Assignment   Intrinsic Variables   Substitution and  Dereferencing
    7.1.3   Expressions
    7.1.4   Built-In Functions
    7.1.5   Error Handling
7.2   VICAR Command Line Structure
    7.2.1   Command Line Syntax   Commands and Proc Names   Subcommands   Command Qualifiers   Parameter List   Comments
    7.2.2   Parameters
    7.2.3   Parameter Value Specification   Parameter_name=value Format   Keyword Format   Positional Format   Parameter Qualifiers
    7.2.4   Missing or Invalid Parameter Values
    7.2.5   Dynamic Parameters
7.3   Proc Definition Files (PDFs)
    7.3.1   Procedure Definition Files (PDFs)
    7.3.2   Process Definition Files (PDFs)
    7.3.3   Executing a PDF
    7.3.4   HELP Files
    7.3.5   Global PDFs
    7.3.6   Compiled PDFs
7.4   Script Files
7.5   Tape Handling
7.6   Session Logging
7.7   Sample Interactive Session
Within this section, the major aspects of the VICAR executive are covered. Complete detail has not been attempted, but all information likely to be commonly required by users has been included. The major concepts being described include command rules and syntax, parameter entry, procedure and script file construction, session logging, and tape handling.

The new user may be confused the first time through this section, since a lot of important information is presented at the same time. Some of the earlier examples might be particularly confusing because they use concepts that are introduced a little later. The new VICAR user should try to understand the basic concepts the first time through and not worry about understanding everything. By the end of this section, the concepts should all start to make sense.

7.1 Introduction to the TAE Command Language (TCL)

Communication between the user and VICAR is accomplished through the TAE Command Language (TCL). TCL allows the user to access procs, supply parameters to them, and initiate their operation using a single command line. TCL provides the following tools to achieve this:

7.1.1 TCL Command Line Rules

While VICAR GUIs are currently being developed, at the present time all user communication to VICAR is accomplished through the use of the TCL Command Line. VICAR functions and procs are invoked by using established rules and syntax. The standard rules governing command lines are covered in this section, while syntax is detailed in Section 7.2.1. Abbreviations

The user is allowed to use abbreviations for the following cases: Proc names, library names and file names may not be abbreviated.

The extent of allowed truncation is governed by one rule: the abbreviation must uniquely specify one command or parameter name out of all those allowed at the time.

Example: Abbreviation of parameters.

    VICAR>F2 A B FUN="IN1*10." 'HA
will work as well as the full command line:

    VICAR>F2 A B FUNCTION="IN1*10." 'HALF Line Continuation

A command line may be continued to a maximum of 2048 characters on subsequent lines by ending it with a "+" character. Lines may not be continued within command names, comment fields or parameter values or names.

Example: Continuation of a command line.

    VICAR>+ 'AUTO GEOM=3 AREA=(50,50,700,700)
BEWARE DCL and USH commands submitted at the VICAR prompt follow the above rules (i.e., using the "+" character). All those submitted from the VICAR DCL mode or USH mode use the standard VMS DCL rule of continuing lines with a "-" character, or the UNIX rule of using a "\" character. Labels

EXPERT Any command line within VICAR procedures may be labelled. A label is created by prefixing a line with a string of characters (which make up the label) and the ">" character. This label may then be referenced by the GOTO command elsewhere in the procedure.

Example: Label use in procedures (the label is "BATCH").

	Refgbl $RUNTYPE
BEWARE Contrary to normal Fortran programming standards, only forward branching is permissible. Special Characters

The special characters allowed by TCL and their meanings are listed in Table 3-2 of the TAE Command Language Programmer's Manual. The most useful of those symbols are listed here. Only the "&" character retains its meaning when placed within a quoted string (a character string bracketed by " " characters).


	!	comment field indicator
	&	variable substitution flag
	@	variable dereferencing flag
	" "	start and end of quoted string
	|	start or end of qualifier field
	,	separator used in lists
	SPACE	general separator
	?	query for help on last message
	'	flag for keyword value
	+	line continuation indicator Special VT100 Terminal Keys

The use of certain special keys has effects that are unique to TCL. The most important of these keys are ESCAPE, Control-C, Control-Y and Control-O. Information on the keys used by the Command Line Editor and Tutor mode are found in Section and Appendix 10.9. The following information describes the VICAR Command mode.

Typing the ESCAPE key twice (ESC ESC) serves two functions within VICAR. When entered on any continuation line, it will cancel the entire command. When entered at a prompt from some interactive procedures, the procedure will be interrupted. Options available at this point are ABORT, TUTOR, and EXIT. ABORT will terminate the procedure, TUTOR will put VICAR in Tutor mode, and EXIT will return the user to the procedure prompt.

A Control-C entry will abort a VICAR operation (Section 5.5) and prompt the user for a further command. After appropriate response to the VICAR-INTERRUPT> prompt, the user is left in VICAR.

On VMS systems, Control-Y will abort an operation and, in addition, will end the VICAR session, lose VICAR dummy names and some allocated devices, and return the user to the DCL prompt. On UNIX systems, it will suspend the VICAR session and return the user to the shell prompt. Typing fg will re-initiate the VICAR session.

A Control-O entry will discontinue all further output to the terminal screen from the current proc. The proc continues to run to completion and continues to output to the session log file. A second Control-O entry will again route output to the terminal screen. Command Line Editor

A command line editor is implemented in VICAR for VT100-compatible video terminals. This editor allows the user to recall previous commands and modify the current (or recalled) command. Commands which may be recalled include those issued from within an interactive program (IDX being an exception). The special keys utilized by the editor are described in Appendix 10.10.

On VMS systems, the method of line modification (either insertion or overstrike) is controlled by that selected under DCL (the SET TERM command). A Control-A will toggle between the options. (The insertion mode is the only one available on UNIX systems.)

The user may scroll backward and forward among the recallable commands with the UP ARROW and DOWN ARROW keys. UP gives earlier commands; DOWN gives later.

BEWARE Restrictions:

7.1.2 Variables

TCL allows the definition of named values called variables. These may be assigned values, be the object of substitution or be used in expressions. Variables may be of two distinct scopes: Local or Global. All variables must be defined before use. The intrinsic command DISPLAY may be used to examine the value of variables. (See Section 10.4 for an explanation of the DISPLAY command.) Local Variables

A Local variable may be referenced only within the procedure or session in which it was declared. These variables must be defined with the LOCAL command before use in an interactive session or in a procedure. The definition of a Local variable in a procedure may be made before or after the BODY statement. The following characteristics are defined for the LOCAL command:

NAME	The variable name, maximum of 8 characters.

TYPE	The variable type, limited to the values: INTEGER,

COUNT	The number of elements in the variable or the range 
	of valid COUNTs.  A count exceeding 1 creates a 
	multi-valued variable; a count of 0 implies the 
	variable is nullable (i.e., not required or may 
	receive the null value (--) ).  Default is 1.  
	Max count is 600.
Examples: Possible COUNT declarations.
    COUNT=1	must have one value associated with the 	

    COUNT=1:10	may have 1 to 10 values entered, which will be 	
		called variable_name(1)...variable_name(10)

    COUNT=0:1	may have at most 1 value, but need not be 	
		entered (i.e., COUNT=0 is valid)

INITIAL	The initial value for the variable, consistent with 

VALID	The allowed values or range of values of the variable,
	consistent with TYPE.
Examples: Possible VALID declarations.
    VALID=4:10		values 4,5,6,7,8,9 or 10 are allowed
    VALID=(1:4,8:10)	values 1,2,3,4,8,9 or 10 are allowed
    VALID=(J,S,U,N)	the listed values are allowed
Example: Declaration of Local Variables
    Local J TYPE=INTEGER COUNT=0:1 VALID=(5,6,7)
    Local (L,K) REAL COUNT=1 INITIAL=1.5
Example: Procedure COUNTEM using a Local variable.
	WRITE "Watch me count to 10"
		WRITE "&I"
		LET  I=I+1
		IF (I>10) BREAK
	WRITE "How was that?"
Example: Running COUNTEM procedure.
    Watch me count to 10
    How was that?
Local variables are deleted when the operation that created them ends or they are explicitly deleted with the intrinsic commands DELETE or DELETE-LOCALS. The DELETE command will delete a single variable, whereas DELETE-LOCALS will delete all the currently defined local variables.


    VICAR>DELETE NAME=variable_name
    VICAR>DELETE-LOCALS Global Variables

A Global variable may be accessed from any level of a session for which it was defined. If accessed in a procedure, a REFGBL statement is required unless it is implicitly defined by VICAR or used at the interactive level. Global variables are defined by PARM commands within special Global procedures (Section 7.3.5) or by the DEFGBL command in regular procedures (Section 7.3.1). A PARM command is similar in structure to the LOCAL command and a DEFGBL command has exactly the same structure. The characteristics defined by PARM commands are outlined in Section 7.2.2.

Example: A Global procedure

	Global		!proc name is CDEF.PDF
 			VALID=(Garfield, Heathcliff, Sassafras)
Execution of the above procedure.
    VICAR>cdef cat=sass
    VICAR>display cat
Example: Use of the DEFGBL command.
	procedure		! procedure game
	defgbl play	type=string	count=1:2 +
	refgbl play
	let play=("base","ball")
	write "We like to play &play"
Execution of the procedure game:
    We like to play (base,ball)
Like Local variables, Global variables are deleted when the operation that created them ends or they are explicitly deleted with the intrinsic commands DELETE or DELETE-GLOBALS. The DELETE command will delete single Global variables, while the DELETE-GLOBALS will delete all those defined in a Global PDF.


     VICAR>DELETE NAME=variable_name
Note: Globals may not be of type KEYWORD (Section Assignment

All variables may be assigned values by the use of the LET command. TCL will not allow values which are inconsistent with the defined characteristics. In addition, the null value "--" or the empty string value " " may be assigned, if COUNT includes "0".

Example: Change the value of the Global variable $ECHO.

	Refgbl $ECHO
	Let $ECHO="YES"
	COPY myfile.dat newfile.dat
In all cases, if the variable definition allows multiple values, each value may be individually accessed or assigned by appending the element number in parentheses to the variable name. In addition, the element number may be an expression (Section 7.1.3).

Example: Possible assignments for a multi-valued parameter.

    LET OUTOF(3) = "BOUNDS" 
    LET OUTOF(P+4) = "LUCK" Intrinsic Variables

VICAR maintains implicitly defined local and global variables. In certain cases, the user may even be able to change the value of one of these intrinsic variables.

EXPERT There are four Intrinsic Local variables available to the user. All Intrinsic Locals may be accessed without defining within a procedure; only _STDOUT is not available in batch.

_ONFAIL Multi-valued variable; at most two values. Controls error handling (Section 7.1.5).
_PROC Contains the name of the currently running proc.
_SUBCMD Contains the name of the currently active subcommand.
_STDOUT Multi-valued variable; at most two values.
_STDOUT(1) contains the file or device name to which the standard output is directed. This is normally set to "SYS$OUTPUT", but may be directed to a file or the print queue (e.g., "SYS$PRINT").
_STDOUT(2) may contain either "APPEND" or "CREATE", defining whether to add to an existing file or create a new one. The default is _STDOUT=("SYS$OUTPUT"," ").
EXPERT Intrinsic globals may be accessed without defining on the interactive level, but within a procedure a REFGBL command may be required. Descriptions of Intrinsic Global variables are contained in Appendix 10.6.

Example: Access Intrinsic variables $RUNTYPE and _PROC.

	Refgbl $RUNTYPE
	WRITE "Proc &PN is invoking TESTPROC"
	End-proc Substitution and Dereferencing

EXPERT TCL gives the user the flexibility of creating procedures which can both substitute and dereference variables. Individual values of a multi-valued variable may not be used for substituting or dereferencing.


EXPERT Prefixing a variable name with the "&" character tells VICAR to replace the "&variable_name" string with the character string that represents the value of the variable. This replacement occurs before command interpretation.

Example: Substitution.

    LET J = 14
    LET I = "PAWS.DAT"
    COPY &I F&J SIZE=(100,100,50,50)
is interpreted as
    COPY PAWS.DAT F14 SIZE=(100,100,50,50)
BEWARE When substituting variables imbedded in a string or word, the variable name itself may require quotes to distinguish it from the rest of the string. This however, becomes a problem when substitution is to be performed inside an otherwise already quoted string, such as a WRITE statement. In this case, concatenation into another variable may be necessary.


EXPERT Prefixing the variable name with the "@" character tells VICAR to replace the "@variable_name" string with the value of the variable. This is like a pointer operation and occurs at run time, not before command interpretation. This is allowed only in value fields (right of the equal sign). The replacing value must be consistent with the definition of the variable.

Example: Dereferencing in a procedure.

	Procedure	! proc name is GPRC.PDF
Execution of the procedure GPRC:
    VICAR>GPRC F=10	! acts like: LIST OUT SPACE=10 
    VICAR>GPRC		! acts like: LIST OUT
EXPERT The "@" is telling VICAR: "when the value of SPACE is needed, use the value of F". A "--" for F implies the same for SPACE, which acts like SPACE was not entered.

EXPERT Differences between Substitution and Dereferencing are detailed in the TAE Command Language Programmer's Manual. Generally speaking, though, "@" always works properly for value fields and "&" may not under certain circumstances.

Example: Dereferencing in a procedure.


7.1.3 Expressions

EXPERT TCL allows various kinds of expressions in order to calculate a value from variables, functions and operators. Expressions are only allowed in the commands LET, FOR, IF and ELSE-IF, and are not allowed in proc invocation commands. Expressions using variables of more than one type are not allowed.

EXPERT The various operators available to the user are listed below with the supported expression types.

Numeric Expression

		+	addition
		-	subtraction
		*	multiplication
		/	division
Example: Assignment statement.
    LET X = Y*2
String Expression
		//	string concatenation
Example: String concatenation.
    LET TRUE = "GARFIELD "//"&verb"//" LASAGNE"
Relational Expression
		>	greater than
		<	less than
		=	equal to
		>=	greater than or equal to
		<=	less than or equal to
		<>	not equal to
Example: A relational expression.
    IF (WAIST >= 100) GOTO FAST
Logical Expression
		AND	logical AND
		OR	logical OR
		NOT	logical negation
Example: A conditional statement.
    IF (day="Monday" and floor="cold") GOTO SLEEPIN

7.1.4 Built-In Functions

EXPERT TCL supplies user-callable functions that can be used in commands and expressions, anywhere a variable name could be used. At run time, the value of the function replaces the function call on the command line.

EXPERT Available functions include:

    Function	    Returned Value				

    $ASFI(jobname)  Returns the current value of $SFI for the
		    asynchronous job.
    $ASKEY(jobname) Returns the current value of $SKEY for the
		    asynchronous job.
    $COUNT(name)    The number of elements for the variable
		    named; -1 if variable has no value, 0 if 
		    variable has null value (--).
    $FIX(real)	    Truncated real value converted to integer.
    $FLOAT(integer) Integer value converted to real. 
    $GLOBAL(name)   1 if variable is a Global, 0 if not. 
    $PANEL(panelname) Returns the status of existence for the 
		    named panel.
    $STRLEN(string) Returns length of specified string. 
Example: Use of the $COUNT function.
    LET I = (1,2,4)
    LET J = $COUNT(I)	!variable J is given the value 3

7.1.5 Error Handling

EXPERT The Intrinsic Global variable $SFI is the indicator of success or failure of a command. It is set to negative upon failures, or remains positive for successes. This variable may be referenced by procs for error handling. Alternatively, the Intrinsic Local variable _ONFAIL can do the error handling for the user. _ONFAIL will check the $SFI indicator and take the action specified by the user. _ONFAIL does not work for errors in intrinsic subcommands.

EXPERT _ONFAIL(1) is set by the user to the command which shall be executed in the event of command failure. _ONFAIL(2) is set by the user to the command which shall be executed upon ABORT after CONTROL-C by the user.

EXPERT The legal values of _ONFAIL are defined below.

    "RETURN"	  The proc gets terminated and error indicators 
		  are passed back up through the chain of 
		  invoking procs.

    "BREAK"	  Control passes to the first command outside
		  the loop containing the failed command.

    "CONTINUE"	  Error has no effect, proc execution continues.

    "GOTO label"  Control passes to command indicated by 

    "NEXT"	  Control passes to first command of current 

    "STOP"	  The proc and its invoking procs terminate.
EXPERT The default value is _ONFAIL=("RETURN","RETURN").

Example: Equivalent _ONFAIL statements.

Example: _ONFAIL use in a loop.
If any of the steps in the loop fails, a warning message is written and the loop continues to the next iteration.

7.2 VICAR Command Line Structure

The VICAR command is a string containing information that controls VICAR's execution. Executing a command line requires proper syntax. This section will describe the command line structure in detail.

7.2.1 Command Line Syntax

A full command line consists of five terms: Syntax:
    VICAR>name[-subcommand] [|qualifiers|] +
    VICAR>+ [parameter_list] [!comments] Commands and Proc Names

The first component of the command line may be a proc name or one of the VICAR intrinsic commands. See Appendicies 10.3 and 10.4, respectively, for lists of standard VICAR procs and intrinsic commands.

A proc name invokes a stored Proc Definition File (PDF - Section 7.3) from a hierarchical search of the VICAR libraries (Section 5.1).

Intrinsic commands cause the system to perform standard, predefined operations. These allow the user to interact with the VICAR executive rather than with application procs. For instance, the intrinsic command ENABLE-SCRIPT instructs VICAR to execute commands stored in a file.

Example: Execute intrinsic command usage after running the proc gen. (Note: The usage command has not yet been ported to UNIX but will be included in future releases. Also, the following example shows what the output will look like for SunOS UNIX; the format will be slightly different for Sun/Solaris and VMS operating systems.)

  VICAR>gen rate.img 10 10
  Beginning VICAR task gen
  GEN Version 6
  GEN task completed

  Statistic               Session     Last Proc (gen)
  ---------               -------     ---------
  Proc Start Time                     Mon Sep 12 15:54:02 1994
  Block input operations  5           0          
  Block output operations 0           0          
  Page Faults(no ph I/O)  24          1          
  Page Faults(phys I/O)   30          0          
  System CPU Time         00:00:00.20 00:00:00.00
  User CPU Time           00:00:00.41 00:00:00.01
  Connect Time            00:00:16.81 00:00:00.32
Intrinsic commands are run by VICAR in the parent process, not the subprocess. It is possible, therefore, to get the two processes confused, as in the following examples.

Example: Confuse the parent process and yourself.


    VICAR>DCL ASSIGN UD:[USERID] X  !Assign done in subprocess.
    VICAR>DCL DIR X:*.SCR	    !Dir done in subprocess.

    Directory UD:[USERID]
	RING.SCR;2	1/3	13-JAN-1987	10:00 
	Total of 1 file, 1/3 blocks.

    VICAR>ENA-SCR X:RING.SCR    !Ena-scr done in parent process
				!which didn't know about assign.
    [TAE-OPNRD] Unable to open script file. VMS/RMS code 
    99524 stv=2312.
UNIX: In UNIX, the problem is even worse, since each ush command is run in a separate subprocess. (Assume the user is currently in the /home/abc directory.)
    VICAR>ush ls /scr/abc
    VICAR>ush setenv OUTDIR /scr/abc  !Setenv done in a 
    VICAR>ush ls $OUTDIR              !Lists current directory, 
    a.img   a.out   b.img   c.img     !since OUTDIR unknown in
				      !this subprocess.
    VICAR>ena-scr $OUTDIR/ring.scr    !OUTDIR unknown in the 
				      !parent process. 
    [TAE-OPNRD] Unable to open script file. No such file 
    or directory.
Example: Keeping things clear (VMS example).

    VICAR>DCL ASSIGN/JOB UD:[USERID] X	!Assign done for all 
    VICAR>DCL DIR X:*.SCR		!Dir done in subprocess.

    Directory UD:[USERID] 
	RING.SCR;2	1/3	13-JAN-1987	10:00 
	Total of 1 file, 1/3 blocks.

    VICAR>ENA-SCR  X:RING.SCR	!Ena-scr done in parent process
				!which now knows about assign.
Under UNIX there is no equivalent of assign/job. Since each program is run in a separate sub-process, the environment variable set with ush will not effect the next command. The only way to set an environment variable for a VICAR session, is to do it before entering VICAR. Subcommands

Some commands and procs may perform several different but related functions, each of which requires a different set of parameters. These functions are called "subcommands". A subcommand is specified as a suffix to the proc or command name, separated with a hyphen and no spaces.

Example: Use of a subcommand.

A command may have a default subcommand. Subcommands of intrinsic commands are listed along with the commands in Appendix 10.4. Subcommands of procs can be found by tutoring the proc. Command Qualifiers

A VICAR command may have qualifiers which are VICAR-defined parameters (not program specific) that specify the environment for command execution. Command qualifiers are optional and may appear in any VICAR proc invocation command. If qualifiers are present, they must be listed between vertical bars, "|", immediately after the proc name, and must be supplied in standard parameter list format (Section As in any parameter list, qualifier values may be specified by position (Section or associated with a qualifier name (Section Qualifier names may be abbreviated using the same rules as for parameters (Section 7.2.2).

Example: Run the program F2 in Batch. Note: Batch mode is currently only available on VMS VICAR.

    VICAR>+ (1,1,100,100) FUNCTION="2*IN1" 'HALF
Appendix 10.5 lists and briefly describes the command qualifiers. For detailed descriptions, see the TAE Command Language User's Manual. Parameter List

A parameter list is a list of zero or more (maximum of 600) values, called parameters, (Section 7.2.2), to be provided to a proc or command.

Syntax: Parameter list.


	where: 	parm-1		is the first parameter name
		value-1		is a value to be assigned to the 
				first parameter
The parameters within a parameter list may be separated by a comma and/or any number of spaces. Comments

Comments are introduced by the character "!" and may appear anywhere on a line. Anything that appears after "!" is a comment. Comments are ignored by VICAR. Use the comment character to insert a blank line in a series of proc statements or to document a proc.

Examples: The use of comments.

    VICAR>! Test filtering procedure
    VICAR>GEN T.DAT 100 100 +	!Generate test image
    VICAR>+ linc=1 sinc=2
BEWARE If the line continuation character, "+", is used, it must precede the comment character, "!".

7.2.2 Parameters

Proc parameters are a form of data used to control the specific way a proc operates. Each parameter's attributes are defined in its Proc Definition File (PDF - Section 7.3) by PARM commands. Parameter attributes specify how the parameter value is handled when the proc is invoked. The characteristics specified by the definition are:

A parameter that has no default value is a mandatory parameter.

The number and type of parameters used on the command line are proc-dependent. They may be separated by blanks or commas. Parameter names and values may be abbreviated provided the parameter can be unambiguously identified among all the parameters for the proc.

Parameters may be one of five types:

INTEGER or REAL - A numeric integer or decimal value consisting of the characters "+", "-", ".", "0" through "9", and/or "e" (the power indicator). Spaces are not permitted within a numeric value. The null value "--" is allowed. This type is only for values being passed into procs.

STRING - A character string of maximum length 250. If any characters listed below appear in the string, the string must be surrounded by double quotes, " ". The empty string " " and the null value "--" are allowed. This type is only for values being passed into procs.

KEYWORD - A character string of maximum length 8. None of the characters listed below are allowed For more information on keywords, see Section This type is only for values being passed into procs.

NAME - A character string which is the name of a declared TCL variable. Values output by procs must be of this type.

The characters recognized by TCL which are the subject of the above STRING and KEYWORD restrictions include:

	space	!	,	)	(	+
	'	>	<	|	@	=

7.2.3 Parameter Value Specification

A parameter may be assigned a value in several ways. The values may be defaulted, restored from previously saved values or explicitly specified.

Parameters with defined default values will automatically take those values if they are not given values any other way.

A set of parameters may be saved and later restored, in the same or a later session, using the SAVE and RESTORE command qualifiers or the SAVE and RESTORE Tutor commands.

Example: Run the program TFILT with its saved parameters.

Parameter values may be assigned explicitly in any of three formats:

Parameters defined to have multiple values may be explicitly specified by parenthesized lists using commas or blanks as separators.

Example: Specification of multi-valued parameters.

    VICAR>F2 inp=(a,b,c) out=d.dat size=(1,1,100,100) +
    VICAR>+ func="2*IN1" 
BEWARE The values within multi-valued parameters are position-dependent. VICAR procs expect the sequence to be that defined in the PDF for the proc. Parameter_name=value Format

Parameters may be in any order when specified this way. If no value is given, then the default value is assigned to the parameter.

Example: A command line in parameter_name=value format.

    VICAR>F2 inp=a.dat out=b.dat size=(1,1,100,100) +
    VICAR>+ format=half function="2*IN1" Keyword Format

Keyword format is a special case of parameter_name=value format for KEYWORD type parameters only. All of the above rules still apply, but a single quote, ', replaces the parameter_name= part of the specification. The ' is necessary to distinguish this format from positional format.

Example: Specification of keywords.

    VICAR>F2 inp=a.dat out=b.dat size=(1,1,100,100) +
    VICAR>+ 'half function="2*IN1" Positional Format

The user should be aware that the order in which the proc receives the parameters is not necessarily that in which they were specified. The Proc Definition File (PDF) for a specified proc (Section 7.3) defines the order of the parameters by the sequence of the PARM statements in the PDF. VICAR allows the parameter_name= part of the parameter specification to be omitted if the parameters are specified on the command line in exactly the same order as they occur in the PDF. This order is the same as the order in which the parameters appear in the Tutor display.

Because VICAR procs generally have many parameters, whose order would be difficult to remember, a convention has been adopted requiring that all procs have the same three initial parameters (except for programs such as GEN, AL and LIST). Their order in the program PDF is:

INP	a defined number of strings specifying input 
	file or input device names in the PDF

OUT	a defined number of strings specifying output
	files or output device names in the PDF

SIZE 	four integers specifying:

	starting line
	starting sample
	number of lines
	number of samples
Example: Standard convention for INP, OUT, SIZE.

    VICAR>F2 a.dat b.dat (1,1,100,100) format=half +
BEWARE Once any parameter value is specified using an explicit parameter name, all remaining parameters on the command line must be specified using explicit parameter names. In a positional parameter list, two successive commas indicate that the corresponding parameter's default value is to be used. There cannot be two successive commas after a value has been provided using an explicit parameter name.

Example: Correct use of explicit parameter names.

    VICAR>F2 inp=a.dat out=b.dat size=(1,1,100,100) +
    VICAR>+format=half function="2*IN1"

    VICAR>F2 inp=a.dat b.dat (1,1,100,100) format=half +
    VICAR>+function="2*IN1" Parameter Qualifiers

Parameter qualifiers are like sub-parameters (parameters to the parameters). Upon proc invocation, the values of qualifiers to a parameter are specified after the parameter value and set between vertical bars, "|".


Example: Specification of parameter qualifiers.

    VICAR>IMGCOPY from=file1|bands=(n1,n2),format="BSQ"| +
    VICAR>+ to=file2
The rules for specifying parameter qualifiers are identical to the rules for parameters. Therefore, parameter qualifier values may be entered by position.

Example: Specification of positional parameter qualifiers.

    VICAR>IMGCOPY file1|(n1,n2), "BSQ"| file2

7.2.4 Missing or Invalid Parameter Values

Parameter errors occur when a proc is invoked in the following cases.

VICAR issues an error message in these cases and reprompts the user.

Example: Sample parameter error message.

    VICAR>LIST CLIFF.ROT (100,100,10,10) 'SPAXE
    [TAE-KEYWORD] Undefined keyword "SPAXE".
    Re-enter the command line or type TUTOR to recover 
    specified values.
The user may respond with "Tutor" and enter Tutor mode to respecify the missing parameters or obtain help on the parameter in question (Section 6.5).

7.2.5 Dynamic Parameters

An executing proc may prompt the user for parameter entry. These parameters are called Dynamic parameters. Programs generate such requests with special subroutines described in the VICAR Run-time Library Reference Manual and the TAE Command Language Programmer's Manual. Procedures, both Asynchronous and Synchronous may also request parameters through the use of the GETPAR command.

Example: Dynamic parameter use in the procedure CON.

    Procedure	! procedure CON
    WRITE "Created A.DAT with all DNs = &CONST"
Example: Execution of the procedure CON.

    Beginning VICAR task GEN
    GEN Version 6
    GEN task completed
    Created A.DAT with all DNs = 12

7.3 Proc Definition Files (PDFs)

As discussed in Section 4.5, a proc may be either a procedure or a process. PDFs are text files defining parameters for the proc and have a .pdf file extension. For procedures, the PDF also contains VICAR commands to be executed. For processes, the PDF has an executable program file associated with it to be activated. In this section, the user will become familiar with procedure definition files, process definition files, Global PDFs, the execution of PDFs, help files for PDFs, and compiled PDFs.

BEWARE On UNIX systems, proc names must be in lower case letters. Procs may be called using either lower case or upper case characters, but the file itself must have a lower case name, or it will not be found by the VICAR executive.

7.3.1 Procedure Definition Files (PDFs)

A VICAR Procedure Definition File is the method that most users will select to join parameter definitions and a series of VICAR commands together and selectively control their execution. A procedure may be simple or complex and yet all users, even the most novice user, will be able to write one.

The procedure PDF is comprised of two main parts: the declaration section and the body. The declaration section contains the parameter declarations, the Local variable declarations and the Global variable references. The body contains the VICAR commands to be executed.

Syntax: Basic format of a procedure PDF.

    Procedure   [HELP=help_information_location]
    Defcmd  !
    Refgbl  !This is the declaration section. All entries 
    Parm    !within this section are optional and they can 
    .	    !appear in any order so long as they appear 
    .	    !between the PROCEDURE and BODY commands.
    .	    !This is the body of the PDF.  VICAR commands
    .	    !should be entered in the order they will be 
    .	    !executed.
Note: PROCEDURE, BODY and END-PROC are all required elements of a procedure.

The easiest method to learn how to write procedure PDFs is to look at examples. The following example is a very simple PDF which creates a VICAR label for a dataset, copies that dataset, then performs a linear stretch on the copy. Note that within this PDF there is no declaration section. The declaration section is not mandatory and is omitted in this case.

Example: A procedure to label and stretch an image.

	Procedure				!1
	Body					!2
	label-create a.raw a.img nl=100 ns=200	!3
	copy a.img b.img			!4
	stretch b.img b.str linear=(54,199)	!5
	End-proc				!6

Line 1	defines that this proc is a procedure.
Line 2	defines that the body of the procedure follows this 
Line 3	creates a label for a raw image with 100 lines and 200 
Line 4	executes the VICAR program COPY, creating a second, 
        identical image.
Line 5	executes the VICAR program STRETCH, performing a linear
        stretch from 54 to 199 on the image.
Line 6	defines that the end of the proc has been reached.
Additional sample PDFs can be found in Appendix 10.11.

7.3.2 Process Definition Files (PDFs)

A process is a program of executable code and all programs require a process PDF. A process PDF may specify:

Syntax: A process PDF, conforming to recommended standards.

	Process [EXECUTE=executable_file HELP=help_location]
	Parm	NAME1  description1
	Parm	NAME2  description2
Example: Process PDF for VICAR program COPY.

    process help=*
    Copy is a simple program which can be used to copy all or
     (See Section 7.3.4 for further
      information on Help files.)
Additional sample PDFs can be found in Appendix 10.11.

7.3.3 Executing a PDF

If the user is new, or if the PDF is trying something new or tricky, the user is advised to run the PDF through the syntax checker (Section 6.4) before actually executing the proc on the host system.

Once a PDF has successfully passed through the syntax checker, the user is ready to execute the proc. The user must next select the mode in which to execute the PDF (Interactive, Asynchronous or Batch). The use of the latter two modes has already been explained in Section 5.2. If the Interactive mode has been chosen, all the user needs to do is enter the proc name and any necessary parameters.

Example: Equivalent methods of proc invocation.


Whenever a user enters a command, a hierarchical library search (Section 5.1) is initiated for a .PDF file of that name. If the PDF is not located in any of the libraries, the user will be notified that an illegal command has been entered.

7.3.4 Help Files

All procs which conform to the recommended standards have a Help file associated with them. Help files contain the information that the user will see when Tutor or Help information is requested on a specific proc.

EXPERT The typical user will probably not bother to write the Help file portion of a procedure PDF since the user designed the PDF and will not require any assistance with the proc. However, there are cases when a Help file is useful. For example, when a procedure is very complicated, or when more than one person will be using a proc (as in the case of the application programs).

EXPERT Help information on VICAR procs can be written in one of two ways: as a separate text file with the name PROCNAME.HLP, or as text appended to the end of the PDF. In the second case, the PDF must include on the PROCEDURE or PROCESS command line HELP=*. In either case, the format of the help information is the same.


    .TITLE		Title to appear on each Tutor and Help 

    .HELP		Information on the proc itself, 
			typically including:
	Purpose		Purpose of the program.
	Execution	Description of command line used to 
			execute the program.
	Features	Special features the user might like to 
			know about.
	Examples	Examples showing how the program can be 
	Restrictions	Any special restriction the user should 
			be aware of.
	Written by	Programmer who originally wrote the 
	Programmer	Programmer currently responsible for the 
	Revision	Version number and date.

    .LEVEL1		Header to tell VICAR that first level 
			help on the proc's variables follows.
    .VARIABLE name1	Help information on name1 to be 
			displayed on the Tutor screen.
    .VARIABLE name2	Help information on name2 to be 
			displayed on the Tutor screen.

    .LEVEL2		Header to tell VICAR that second level 
			or detailed help on the variables 
    .VARIABLE name1	Detailed information on name1. This text 
			is displayed on the "Help PARM" Tutor 
			command or on the VICAR command: 
			  HELP-PARM parm=name1 proc=proc_name
    .VARIABLE name2	Detailed information on name2. 

    .END		End of help text.
See Appendix 10.11 for examples of Help files.

EXPERT It is possible to get hardcopy printouts of the proc's Help section. For formatted Help, use the HELP-HARDCOPY command to create a disk file which may then be printed. For unformatted Help, print the proc's .PDF file.

7.3.5 Global PDFs

EXPERT A Global proc defines Global variables. It may contain references to other Globals and/or declarations of Local variables. The Global PDF starts with "Global" and has no body.


	Global [HELP=help_information_location]
	definitions of Global variables
	declarations of referenced Globals
	declarations of Local variables
Example: Sample Global PDF.

	Parm	DATATYPE    String	Default=" "
	Parm	RUNSEQ 	    Integer	Default=0
	Parm	COLTBL	    String	Default="default"
	Parm	SL	    Integer	Default=1  (null value)
	Parm	SS	    Integer	Default=1
	Parm	NL	    Integer	Default=1340
	Parm	NS	    Integer	Default=3360
	Parm	RES	    Real	Default=8.
	Parm	REGION	    String	Default="global"
EXPERT Note: Globals may not be of type KEYWORD (Section

7.3.6 Compiled PDFs

WIZARD A compiled PDF is created when the VICAR command COMPILE is run on any process, procedure or Global PDF. During compilation, the declaration statements are scanned for proper syntax and symbol tables are generated. Because these steps do not have to be repeated during the PDF execution, compiled PDFs (with a .CPD extension) run faster than normal PDFs (.PDF).

WIZARD In order to compile a PDF, the following rules must be observed when writing the proc:

WIZARD Procs are compiled by using the COMPILE command.


    VICAR>COMPILE INPROC=input_pdf [OUTPROC=compiled_pdf]
Example: Compile the proc TAXCALC.PDF.

WIZARD The execution of a compiled PDF is identical to the execution of a normal PDF. If the PDF resides within one of the VICAR application libraries,VICAR automatically looks to see if a .CPD version of the requested proc exists. If no compiled proc is available then the .PDF is executed.

Example: Execute a program which has a compiled PDF.

WIZARD In this example, because the compiled PDF exists, VICAR automatically executes BROWSE.CPD. However, if the compiled PDF resides within a personal directory, the compiled PDF must be explicitly specified unless the library has been customized to select compiled PDFs first.

Example: Explicitly invoke the compiled version of TAXCALC.

WIZARD Additional information on compiled PDFs can be found in the TAE Command Language User's Manual and the TAE Command Language Programmer's Manual.

7.4 Script Files

EXPERT A Script file is a text file consisting of VICAR commands used primarily for demonstration and test purposes. None of the special commands required in a procedure (e.g., BODY) are included in a script file. On the other hand, no parameters are allowed either.

Example: Script file LOG.SCR

EXPERT A SCRIPT file can be invoked with the intrinsic command ENABLE-SCRIPT.


    VICAR>ENABLE-SCRIPT FILE=filename [COUNT=number]

    Where:  FILE    is the name of the SCRIPT file to be 
		    executed.  The file must be of the type 
		    .SCR in order to be properly executed.
	    COUNT   The number of times to execute the script 
		    file.  The default is to execute the file 
		    once.  COUNT=ZERO causes the file to be 
		    repeated endlessly until aborted by a host 
		    interrupt sequence.
EXPERT The ENABLE-SCRIPT command causes VICAR to use the specified script file for its "interactive" input. There is no hierarchy search implemented for script files so the user should either be in the directory containing the script file prior to entering VICAR, or the user should fully specify the directory and filename in the invocation. In addition, the datasets used by the script file must be in the same directory as the script file or the directory should be fully specified. Once invoked, TAE then sequences through the script file, echoing each command as it is executed.

Example: Script file use in an interactive session.

    Beginning VICAR task F2
    F2 version 2-04-94
    F2 using byte table lookup

    Beginning VICAR task STRETCH
    STRETCH version 2-11-93

    Linear Stretch:      0 to      0 and    150 to    255

7.5 Tape Handling

The following section covers tape handling for VICAR under VMS only. There is no VICAR tape support under UNIX. It is suggested that the standard operating system utilities such as tar and dd be used for accessing tapes. VMS VICAR support of tape handling may not continue in the future, and many applications which have accepted tape inputs in the past will no longer do so.

When running under VMS, operations involving magnetic tapes are handled within VICAR with the commands ALLOC, MOUNT, REWIND, DISMOUNT and DEALLOC (see Section 10.4). Both foreign and ANSI labelled tapes are supported, as are blocked tapes (those with multiple logical records per physical record). All applications which accept tape inputs require that the tapes be previously MOUNTed.

The ALLOC command assigns a symbolic name to the allocated device. All other tape commands use that symbolic name to access the device. In addition, the MOUNT command uses many of the same qualifier names as the DCL MOUNT command. However, ANSI-labelled tapes are identified by the presence of the LABEL parameter.

The syntax for referencing a particular file on a tape uses the "/" character. The symbolic name of the tape is suffixed by a "/file_number" string.

Example: Accessing file 10 on tape IN.

It is not necessary to rewind the tape for VICAR to access the proper file number. VICAR always keeps track of the current file number and handles file number regressions properly.

Example: Tape processing under VMS.

    VICAR>ALLOC MT: IN  	!allocates first available 
				!MT: drive and assigns
    				!symbolic name IN
    VICAR>MOUNT IN +		!tape mytape is mounted foreign,
    VICAR>+ comm="mount mytape"	!unblocked and for read
    VICAR>COPY IN/4 A		!copy file 4 into A
    VICAR>COPY IN/2 B		!copy file 2 into B
    VICAR>REWIND IN		!tape is rewound
    VICAR>DISMOUNT IN		!tape is dismounted
    VICAR>DEALLOC IN		!device is deallocated
BEWARE Device allocations may be performed at any time in a VICAR job or session. However, in practice, jobs should do all allocations at the beginning of the job stream, and do them as a group. This is because, in general, the job is started when the resources become available, but there is no guarantee that they will stay available.

Users may exit VICAR and reenter with confidence that any tape drives will remain allocated, mounted and at the same position unless a Control-Y was used to exit. Exiting by Control-Y will lose dummy names associated with devices, asynchronous jobs and some allocated devices. Tape drives that had been allocated and mounted will remain mounted, but VICAR will know nothing about them.

Tape drives allocated within VICAR may be accessed from VICAR's DCL mode. Such access must, of course, be accomplished with DCL tape handling commands.

BEWARE Tape drives allocated within VICAR are not available to the user outside VICAR (and vice versa). This is because the VMS process and the VICAR may not share resources.

The general tape handling utility, TAPES, is not a standard VICAR proc and may not be invoked from VICAR. It may be invoked from VICAR DCL mode or from the user's VMS process. Because of the non-standard nature of TAPES, no VICAR user aids are available for it. However, there is on-line help for TAPES in DCL.


Hardcopy help for TAPES is obtainable using the following sequence of DCL commands.


Note: "/OUT" must immediately follow HELP and not TAPES or TAPES*.

7.6 Session Logging

VICAR gives the user the ability to create a log of their interactive session activity. This option is enabled and disabled with the ENABLE-LOG and DISABLE-LOG commands. When enabled, this option creates or appends to two files called session.log and session.tsl. The .log file reflects the commands and responses as they appear on the standard output, while the .tsl file supplies additional useful information (e.g., a full list of proc parameters).

A new pair of session files is created at the initial ENABLE-LOG command after entry into VICAR. Further ENABLE-LOGs (after DISABLE-LOGs, of course) within a given session will append information to the existing files. Once the DISABLE-LOG option is selected, the files are closed and may be accessed, reopened, or printed.

At the current time, there are still some problems with session logging on the UNIX system. In batch log files, items often appear out of order, and FORTRAN programs do not appear at all. In interactive sessions, the session.log file is usually correct, but the session.tsl file can occasionally be out of order.

7.7 Sample Interactive Session

The following example shows a Synchronous or Interactive VICAR session. The commands are all entered from Command mode and perform several basic tasks. The reader may follow this session exactly or embellish it as desired for practice.


		Welcome to VICAR

                System Release 12.1
                Executive Version 5B/16B

  --- Type NUT for the New User Tutorial ---

  --- Type MENU for a menu of available applications ---

VICAR>gen a 10 10 ival=2 sinc=0 linc=0
Beginning VICAR task gen
GEN Version 6
GEN task completed
VICAR>list a
Beginning VICAR task list

   BYTE     samples are interpreted as   BYTE   data
 Task:GEN   User:edd   Date_Time:Thu Aug 11 15:05:44 1994
     Samp     1       3       5       7       9
      1       2   2   2   2   2   2   2   2   2   2
      2       2   2   2   2   2   2   2   2   2   2
      3       2   2   2   2   2   2   2   2   2   2
      4       2   2   2   2   2   2   2   2   2   2
      5       2   2   2   2   2   2   2   2   2   2
      6       2   2   2   2   2   2   2   2   2   2
      7       2   2   2   2   2   2   2   2   2   2
      8       2   2   2   2   2   2   2   2   2   2
      9       2   2   2   2   2   2   2   2   2   2
     10       2   2   2   2   2   2   2   2   2   2
VICAR>f2 a b.dat func="in1+10"
Beginning VICAR task f2
Beginning VICAR task f2
F2 version 2-04-94
F2 using byte table lookup
VICAR>list b.dat
Beginning VICAR task  LIST

   BYTE     samples are interpreted as   BYTE   data
 Task:GEN   User:edd   Date_Time:Thu Aug 11 15:05:44 1994
 Task:F2    User:edd   Date_Time:Thu Aug 11 15:06:16 1994
     Samp     1       3       5       7       9
      1      12  12  12  12  12  12  12  12  12  12
      2      12  12  12  12  12  12  12  12  12  12
      3      12  12  12  12  12  12  12  12  12  12
      4      12  12  12  12  12  12  12  12  12  12
      5      12  12  12  12  12  12  12  12  12  12
      6      12  12  12  12  12  12  12  12  12  12
      7      12  12  12  12  12  12  12  12  12  12
      8      12  12  12  12  12  12  12  12  12  12
      9      12  12  12  12  12  12  12  12  12  12
     10      12  12  12  12  12  12  12  12  12  12
VICAR>gen b 10 10 ival=4 sinc=0 linc=0
Beginning VICAR task gen
GEN Version 6
GEN task completed
VICAR>list b
Beginning VICAR task list 

   BYTE     samples are interpreted as   BYTE   data
 Task:GEN   User:edd   Date_Time:Thu Aug 11 15:12:38 1994
     Samp     1       3       5       7       9
      1       4   4   4   4   4   4   4   4   4   4
      2       4   4   4   4   4   4   4   4   4   4
      3       4   4   4   4   4   4   4   4   4   4
      4       4   4   4   4   4   4   4   4   4   4
      5       4   4   4   4   4   4   4   4   4   4
      6       4   4   4   4   4   4   4   4   4   4
      7       4   4   4   4   4   4   4   4   4   4
      8       4   4   4   4   4   4   4   4   4   4
      9       4   4   4   4   4   4   4   4   4   4
     10       4   4   4   4   4   4   4   4   4   4
VICAR>f2 (a,b) b.dat func="in1*in2+10" 'half
Beginning VICAR task f2
Beginning VICAR task f2
F2 version 2-04-94
F2 using hash table lookup
VICAR>list b.dat (1,1,10,10)
Beginning VICAR task list

   HALF     samples are interpreted as HALFWORD data
 Task:GEN   User:edd   Date_Time:Thu Aug 11 15:05:44 1994
 Task:F2    User:edd   Date_Time:Thu Aug 11 15:23:45 1994
   Samp   1    2    3    4    5    6    7    8    9   10
    1    18   18   18   18   18   18   18   18   18   18
    2    18   18   18   18   18   18   18   18   18   18
    3    18   18   18   18   18   18   18   18   18   18
    4    18   18   18   18   18   18   18   18   18   18
    5    18   18   18   18   18   18   18   18   18   18
    6    18   18   18   18   18   18   18   18   18   18
    7    18   18   18   18   18   18   18   18   18   18
    8    18   18   18   18   18   18   18   18   18   18
    9    18   18   18   18   18   18   18   18   18   18
   10    18   18   18   18   18   18   18   18   18   18
VICAR>copy a c
Beginning VICAR task copy
VICAR>list c
Beginning VICAR task list

   BYTE     samples are interpreted as   BYTE   data
 Task:GEN    User:edd    Date_Time:Thu Aug 11 15:05:44 1994
 Task:COPY   User:edd    Date_Time:Thu Aug 11 15:27:50 1994
     Samp     1       3       5       7       9
      1       2   2   2   2   2   2   2   2   2   2
      2       2   2   2   2   2   2   2   2   2   2
      3       2   2   2   2   2   2   2   2   2   2
      4       2   2   2   2   2   2   2   2   2   2
      5       2   2   2   2   2   2   2   2   2   2
      6       2   2   2   2   2   2   2   2   2   2
      7       2   2   2   2   2   2   2   2   2   2
      8       2   2   2   2   2   2   2   2   2   2
      9       2   2   2   2   2   2   2   2   2   2
     10       2   2   2   2   2   2   2   2   2   2

If you wish to return to the Contents page, click here.