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 SessionWithin 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." 'HAwill 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 allowedExample: Declaration of Local Variables
Local J TYPE=INTEGER COUNT=0:1 VALID=(5,6,7) Local (L,K) REAL COUNT=1 INITIAL=1.5Example: 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-procExecution 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_nameNote: 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 OUTEXPERT 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*2String 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 FASTLogical 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-LOOPIf 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=STRETCHA 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" 'HALFAppendix 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=2BEWARE 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=file2The 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-procExample: 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-procNote:
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>TAPE2DSKor
VICAR>TAPE2DSK.PDFWhenever 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.CPDWIZARD 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>BROWSEWIZARD 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.DONEWIZARD 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 MOUNT
ed.
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 XIt 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 deallocatedBEWARE 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 TAPESHardcopy 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.HLPNote: "
/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-LOG
s (after DISABLE-LOG
s, 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.