7.1 Introduction to the TAE Command Language (TCL) 7.1.1 TCL Command Line Rules 220.127.116.11 Abbreviations 18.104.22.168 Line Continuation 22.214.171.124 Labels 126.96.36.199 Special Characters 188.8.131.52 Special VT100 Terminal Keys 184.108.40.206 Command Line Editor 7.1.2 Variables 220.127.116.11 Local Variables 18.104.22.168 Global Variables 22.214.171.124 Assignment 126.96.36.199 Intrinsic Variables 188.8.131.52 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 184.108.40.206 Commands and Proc Names 220.127.116.11 Subcommands 18.104.22.168 Command Qualifiers 22.214.171.124 Parameter List 126.96.36.199 Comments 7.2.2 Parameters 7.2.3 Parameter Value Specification 188.8.131.52 Parameter_name=value Format 184.108.40.206 Keyword Format 220.127.116.11 Positional Format 18.104.22.168 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:
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.
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
elsewhere in the procedure.
Example: Label use in procedures (the label is
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.
22.214.171.124 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
Control-O. Information on the keys used by the Command Line Editor and Tutor mode are found in Section 126.96.36.199 and Appendix 10.9. The following information describes the VICAR Command mode.
ESCAPE key twice (
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 will terminate the procedure,
will put VICAR in Tutor mode, and
EXIT will return the
user to the procedure prompt.
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
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
188.8.131.52 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
On VMS systems, the method of line modification (either insertion or
overstrike) is controlled by that selected under DCL (the
TERM command). A
Control-A will toggle between
the options. (The insertion mode is the only one available on UNIX
The user may scroll backward and forward among the recallable commands
UP ARROW and
DOWN ARROW keys.
UP gives earlier commands;
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
DISPLAY may be used to examine the value of
variables. (See Section 10.4
for an explanation of the
184.108.40.206 Local Variables
A Local variable may be referenced only within the procedure or
session in which it was declared. These variables must be defined
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
statement. The following characteristics are defined for the
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=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=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
COUNTEMusing 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
DELETEcommand will delete a single variable, whereas
DELETE-LOCALSwill delete all the currently defined local variables.
VICAR>DELETE NAME=variable_name VICAR>DELETE-LOCALS
REFGBLstatement is required unless it is implicitly defined by VICAR or used at the interactive level. Global variables are defined by
PARMcommands within special Global procedures (Section 7.3.5) or by the
DEFGBLcommand in regular procedures (Section 7.3.1). A
PARMcommand is similar in structure to the
LOCALcommand and a
DEFGBLcommand has exactly the same structure. The characteristics defined by
PARMcommands 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
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
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
DELETEcommand will delete single Global variables, while the
DELETE-GLOBALSwill delete all those defined in a Global PDF.
VICAR>DELETE NAME=variable_name VICAR>DELETE-GLOBALS PROC=proc_nameNote: Globals may not be of type
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
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.
_ONFAILMulti-valued variable; at most two values. Controls error handling (Section 7.1.5).
_PROCContains the name of the currently running proc.
_SUBCMDContains the name of the currently active subcommand.
_STDOUTMulti-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., "
_STDOUT(2)may contain either "
APPEND" or "
CREATE", defining whether to add to an existing file or create a new one. The default is
REFGBLcommand may be required. Descriptions of Intrinsic Global variables are contained in Appendix 10.6.
Example: Access Intrinsic variables
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
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.
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
WRITEstatement. In this case, concatenation into another variable may be necessary.
EXPERT Prefixing the variable name with the "@" character tells VICAR to replace the "@variable_name" string with the value of the variable. This is like a pointer operation and occurs at run time, not before command interpretation. This is allowed only in value fields (right of the equal sign). The replacing value must be consistent with the definition of the variable.
Example: Dereferencing in a procedure.
Procedure ! proc name is GPRC.PDF 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
SPACEis needed, use the value of
F". A "--" for
Fimplies the same for
SPACE, which acts like
SPACEwas 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.
EXPERT The various operators available to the user are listed below with the supported expression types.
+ 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
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
$SFIis 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
_ONFAILcan do the error handling for the user.
_ONFAILwill check the
$SFIindicator and take the action specified by the user.
_ONFAILdoes not work for errors in intrinsic subcommands.
_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
EXPERT The legal values of
_ONFAIL are defined
"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
LET _ONFAIL="CONTINUE" LET _ONFAIL(1)="CONTINUE"Example:
_ONFAILuse 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
ENABLE-SCRIPT instructs VICAR to execute commands
stored in a file.
Example: Execute intrinsic command
running the proc
gen. (Note: The
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.
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
ushcommand 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
ushwill not effect the next command. The only way to set an environment variable for a VICAR session, is to do it before entering VICAR.
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
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.
220.127.116.11 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 18.104.22.168). As in any parameter list,
qualifier values may be specified by position (Section 22.214.171.124) or associated with a qualifier
name (Section 126.96.36.199). 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.
188.8.131.52 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.
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, "!".
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 184.108.40.206. 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
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
command qualifiers or the
Example: Run the program
TFILT with its saved
VICAR>TFILT |RESTORE=TFILT.PAR|Parameter values may be assigned explicitly in any of three formats:
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.
220.127.116.11 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"
KEYWORDtype 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"
PARMstatements 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"
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
Example: Dynamic parameter use in the procedure
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
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:
END-PROCare 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
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.PDFWhenever a user enters a command, a hierarchical library search (Section 5.1) is initiated for a
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
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
HELP=*. In either case, the format of the help
information is the same.
.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
7.3.5 Global PDFs
EXPERT A Global proc defines Global variables. It may
contain references to other Globals and/or declarations of Local
variables. The Global PDF starts with "Global" and has no body.
Global [HELP=help_information_location] definitions of Global variables declarations of referenced Globals declarations of Local variables 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
7.3.6 Compiled PDFs
WIZARD A compiled PDF is created when the VICAR
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
WIZARD In order to compile a PDF, the following rules must be observed when writing the proc:
DEFGBLstatements are not allowed
PROCEDUREstatements must be default
DEFAULTfield of a parameter statement cannot be dereferenced
VICAR>COMPILE INPROC=input_pdf [OUTPROC=compiled_pdf]Example: Compile the proc
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
F2 TEST.RED OUTTEST FUNC="100.*ALOG10(IN1)" STRETCH OUTTEST STRTEST LINE=(0,150)EXPERT A
SCRIPTfile can be invoked with the intrinsic command
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-SCRIPTcommand 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
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
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
command. However, ANSI-labelled tapes are identified by the presence
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.
$ HELP TAPESHardcopy help for
TAPESis obtainable using the following sequence of DCL commands.
$ HELP/OUT=TAPES.HLP TAPES $ HELP/OUT=TAPES1.HLP TAPES* $ PRINT TAPES.HLP, TAPES1.HLPNote: "
/OUT" must immediately follow
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
DISABLE-LOG commands. When
enabled, this option creates or appends to two files called
.log file reflects the commands and responses as they
appear on the standard output, while the
supplies additional useful information (e.g., a full list of proc
A new pair of session files is created at the initial
ENABLE-LOG command after entry into VICAR. Further
DISABLE-LOGs, of course)
within a given session will append information to the existing files.
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
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.