7.1 Introduction to the TAE Command Language (TCL)
7.1.1 TCL Command Line Rules
7.1.1.1 Abbreviations
7.1.1.2 Line Continuation
7.1.1.3 Labels
7.1.1.4 Special Characters
7.1.1.5 Special VT100 Terminal Keys
7.1.1.6 Command Line Editor
7.1.2 Variables
7.1.2.1 Local Variables
7.1.2.2 Global Variables
7.1.2.3 Assignment
7.1.2.4 Intrinsic Variables
7.1.2.5 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
7.2.1.1 Commands and Proc Names
7.2.1.2 Subcommands
7.2.1.3 Command Qualifiers
7.2.1.4 Parameter List
7.2.1.5 Comments
7.2.2 Parameters
7.2.3 Parameter Value Specification
7.2.3.1 Parameter_name=value Format
7.2.3.2 Keyword Format
7.2.3.3 Positional Format
7.2.3.4 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.1 Abbreviations
The user is allowed to use abbreviations for the following cases:
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
Example: Continuation of a command line.
VICAR>FARENC URANUS.RED (A,B,G) +
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.
7.1.1.3 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").
Procedure Refgbl $RUNTYPE Body IF ($RUNTYPE="BATCH") GOTO BATCH WRITE "ARE WE HAVING FUN YET?" BATCH>TESTPROC (A,B,C) End-procBEWARE Contrary to normal Fortran programming standards, only forward branching is permissible.
7.1.1.4 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).
CHARACTER MEANING
! 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
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
7.1.1.6 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.
7.1.1.6 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.)
7.1.2.1 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, REAL, STRING and FILE. 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
variable
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
TYPE, VALID and COUNT.
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.
Procedure Body LOCAL I INTEGER INIT=1 WRITE "Watch me count to 10" LOOP WRITE "&I" LET I=I+1 IF (I>10) BREAK END-LOOP WRITE "How was that?" end-procExample: Running COUNTEM procedure.
VICAR>COUNTEM
Watch me count to 10
1
2
3
4
5
6
7
8
9
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. Syntax:
VICAR>DELETE NAME=variable_name
VICAR>DELETE-LOCALS
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 Parm CAT STRING COUNT=1 DEFAULT=GARFIELD + VALID=(Garfield, Heathcliff, Sassafras) End-procExecution of the above procedure.
VICAR>cdef cat=sass
VICAR>display cat
cat="Sassafras"
Example: Use of the DEFGBL command.
procedure ! procedure game
body
defgbl play type=string count=1:2 +
valid=("base","volley","ball")
refgbl play
let play=("base","ball")
write "We like to play &play"
end-proc
Execution of the procedure game:
VICAR>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. Syntax:
VICAR>DELETE NAME=variable_name
VICAR>DELETE-GLOBALS PROC=proc_name
Note: Globals may not be of type KEYWORD (Section 7.2.3.2).
7.1.2.3 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.
Procedure Refgbl $ECHO Body Let $ECHO="YES" COPY myfile.dat newfile.dat End-procIn 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"
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","
").
REFGBL command may be required. Descriptions of Intrinsic
Global variables are contained in Appendix 10.6.
Example: Access Intrinsic variables $RUNTYPE and
_PROC.
Procedure Refgbl $RUNTYPE Body IF ($RUNTYPE="INTERACTIVE") GOTO INT LOCAL PN STRING LET PN = _PROC WRITE "Proc &PN is invoking TESTPROC" INT>TESTPROC (A,B,C) End-proc
Substitution
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. Dereferencing
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 Parm F INTEGER COUNT=0:1 DEFAULT=-- Body LIST OUT SPACE=@F End-procExecution 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.
VICAR>GEN OUT=DATASET&"NAME".IMG
EXPERT The various operators available to the user are listed below with the supported expression types.
Numeric Expression
+ addition - subtraction * multiplication / divisionExample: Assignment statement.
LET X = Y*2
String Expression
// string concatenationExample: 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 toExample: A relational expression.
IF (WAIST >= 100) GOTO FAST
Logical Expression
AND logical AND OR logical OR NOT logical negationExample: A conditional statement.
IF (day="Monday" and floor="cold") GOTO SLEEPIN
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.
LOCAL I INTEGER COUNT=0:4
LET I = (1,2,4)
LOCAL J INTEGER
LET J = $COUNT(I) !variable J is given the value 3
$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
"label".
"NEXT" Control passes to first command of current
loop.
"STOP" The proc and its invoking procs terminate.
EXPERT The default value is
_ONFAIL=("RETURN","RETURN").
Example: Equivalent _ONFAIL statements.
LET _ONFAIL="CONTINUE"
LET _ONFAIL(1)="CONTINUE"
Example: _ONFAIL use in a loop.
LET _ONFAIL="GOTO ERROR"
LOOP
COPY IN/&F X
MASKV X Y.&F
NEXT
ERROR>WRITE "WARNING: FILE &F FAILED"
END-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:
VICAR>name[-subcommand] [|qualifiers|] +
VICAR>+ [parameter_list] [!comments]
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 VICAR>usage 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.32Intrinsic 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.
VMS:
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
ring.scr
VICAR>ush setenv OUTDIR /scr/abc !Setenv done in a
!subprocess.
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
!processes.
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.
7.2.1.2 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.
VICAR>LABEL-DELETE INP=A.DAT KEYS=STRETCH
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.
7.2.1.3 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 7.2.1.4). As in any parameter list,
qualifier values may be specified by position (Section 7.2.3.3) or associated with a qualifier
name (Section 7.2.3.4). 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>F2 |RUNTYPE=BATCH| A.DAT B.DAT +
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.
7.2.1.4 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.
parm-1=value-1,parm-2=value-2,...,parm-n=value-n
where: parm-1 is the first parameter name
value-1 is a value to be assigned to the
first parameter
etc.
The parameters within a parameter list may be separated by a comma
and/or any number of spaces.
7.2.1.5 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>!
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:
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 7.2.3.2. 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 ! , ) ( + ' > < | @ = tab
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.
VICAR>TFILT |RESTORE=TFILT.PAR|
Parameter values may be assigned explicitly in any of three formats:
KEYWORD)
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.
7.2.3.1 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 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"
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 samplesExample: Standard convention for INP, OUT, SIZE.
VICAR>F2 a.dat b.dat (1,1,100,100) format=half +
VICAR>+function="2*IN1"
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"
not
VICAR>F2 inp=a.dat b.dat (1,1,100,100) format=half +
VICAR>+function="2*IN1"
Syntax:
parameter=value|qual1=val1,qual2=val2,...qualn=valn|
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
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
Local CONST INTEGER
Body
GETPAR CONST
GEN A.DAT 10 10 IVAL=&CONST LINC=0 SINC=0
WRITE "Created A.DAT with all DNs = &CONST"
End-proc
Example: Execution of the procedure CON.
VICAR>CON
ENTER CONST
->12
Beginning VICAR task GEN
GEN Version 6
GEN task completed
Created A.DAT with all DNs = 12
.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.
Body
. !This is the body of the PDF. VICAR commands
. !should be entered in the order they will be
. !executed.
End-proc
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.
Line 3 creates a label for a raw image with 100 lines and 200
samples.
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:
Process [EXECUTE=executable_file HELP=help_location] Parm NAME1 description1 Parm NAME2 description2 . . . End-procExample: Process PDF for VICAR program
COPY.
process help=*
PARM INP TYPE=STRING
PARM OUT TYPE=STRING
PARM SIZE TYPE=INTEGER COUNT=0:4 DEFAULT=--
PARM BANDS TYPE=INTEGER COUNT=0:2 DEFAULT=--
PARM SL INTEGER DEFAULT=1
PARM SS INTEGER DEFAULT=1
PARM SB INTEGER DEFAULT=1
PARM NL INTEGER DEFAULT=0
PARM NS INTEGER DEFAULT=0
PARM NB INTEGER DEFAULT=0
PARM FORMAT KEYWORD VALID=(BYTE,HALF,FULL,REAL,DOUB,COMP) +
DEFAULT=BYTE
PARM INSIZE INTEGER COUNT=0:3 DEFAULT=--
PARM ORG KEYWORD VALID=(BSQ,BIL,BIP) DEFAULT=BSQ
PARM BLOCK TYPE=KEYWORD VALID=(BLOCK,NOBLOCK) DEFAULT=BLOCK
PARM BINARY TYPE=KEYWORD VALID=(BINARY,NOBINARY) +
DEFAULT=NOBINARY
END-PROC
.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.
VICAR>TAPE2DSK
or
VICAR>TAPE2DSK.PDF
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.
Syntax:
.TITLE Title to appear on each Tutor and Help
screen.
.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
used.
Restrictions Any special restriction the user should
be aware of.
Written by Programmer who originally wrote the
program.
Programmer Programmer currently responsible for the
program.
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
follows.
.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.
Syntax:
Global [HELP=help_information_location] definitions of Global variables declarations of referenced Globals declarations of Local variables End-procExample: Sample Global PDF.
Global 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" End-procEXPERT Note: Globals may not be of type
KEYWORD (Section 7.2.3.2).
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:
DEFGBL statements are not allowed
RUNTYPE and NAME fields of
PROCESS and PROCEDURE statements must be
default
DEFAULT field of a parameter statement cannot be
dereferenced
COMPILE command. Syntax:
VICAR>COMPILE INPROC=input_pdf [OUTPROC=compiled_pdf]
Example: Compile the proc TAXCALC.PDF.
VICAR>COMPILE inproc=TAXCALC.PDF outproc=TAXCALC.CPD
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.
VICAR>BROWSE
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.
VICAR>TAXCALC.CPD (W2.DAT,INTEREST.DAT) 1040.DONE
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
F2 TEST.RED OUTTEST FUNC="100.*ALOG10(IN1)"
STRETCH OUTTEST STRTEST LINE=(0,150)
EXPERT A SCRIPT file can be invoked with
the intrinsic command ENABLE-SCRIPT. Syntax:
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.
VICAR>ENABLE-SCRIPT LOG.SCR
F2 TEST.RED OUTTEST FUNC="100.*ALOG10(IN1)"
Beginning VICAR task F2
F2 version 2-04-94
F2 using byte table lookup
FUNCTION EVALUATED 256 TIMES
STRETCH OUTTEST STRTEST LINE=(0,150)
Beginning VICAR task STRETCH
STRETCH version 2-11-93
*** LINEAR CONTRAST STRETCH MODE ***
Linear Stretch: 0 to 0 and 150 to 255
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.
VICAR>COPY IN/10 X
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.
Syntax:
$ HELP TAPES
Hardcopy help for TAPES is obtainable using the following
sequence of DCL commands. Syntax:
$ HELP/OUT=TAPES.HLP TAPES
$ HELP/OUT=TAPES1.HLP TAPES*
$ PRINT TAPES.HLP, TAPES1.HLP
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.
$ VICAR
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
Line
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
FUNCTION EVALUATED 256 TIMES
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
Line
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
Line
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
FUNCTION EVALUATED 2 TIMES
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
Line
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
COPY VERSION 12-JUL-1993
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
Line
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>exit
%
If you wish to return to the Contents page, click here.