3.5 TAE COMMAND LANGUAGE OPERATIONS

This section describes the operations available to an interactive user of the TAE Command Language (TCL). (For information on writing TCL procedures, see "TAE Command Language (TCL) Programmer's Manual.")

3.5.1 TCL Startup

TCL is entered when:

In TCL, the user is prompted with "TAE>" (or an installation-dependent prompt) and is expected to respond with TAE commands as described in this section.

3.5.2 TCL Command Line Rules

A TCL command line is either the invocation of a proc or a TAE "intrinsic" command. Command lines in TAE are "free-field": the command fields may appear anywhere on the input line, as long as they appear in the correct order.

The simplest and most common form of a command consists of the command or proc name followed by a parameter list:

TAE> command parameter-list

The "command" is the name of the intrinsic command or proc to be executed and the "parameter-list" is the set of parameters associated with the command or proc.

Example:
TAE> IMGCOPY FILE1 FILE2

This command line invokes a proc named "IMGCOPY" and passes the parameter values "FILE1" and "FILE2" to the proc.

A full command string consists of an intrinsic command or proc name, a subcommand, command qualifiers, a parameter list, and a comment field, all in free-field format:

TAE>name-subcommand|qualifiers| parameter-list !comments

Command qualifiers are not available for intrinsic commands. Comments may appear at the end of any line, including a line to be continued. The following sections describe the components of a command line.

3.5.2.1 Command Name

The command name may be one of the user-oriented intrinsic commands listed in Table 3.5-1 or one of the programmer-oriented intrinsic commands (described in the "TAE Command Language Programmer's Manual"), or the name of a proc. Under VMS, the name may be specified in upper or lower case. See the description of the command DISABLE-FORCE_LOWER for case considerations under UNIX. The following rules apply to command names:

  1. If the named command is not an intrinsic command, TAE uses the normal hierarchy search (see Section 2.4.1) to locate the proc.

  2. To bypass the hierarchy search, the command field may use the host-dependent file syntax for the library specification. For example, in VAX/VMS, the command "MYLIB:IMGCOPY" overrides the hierarchy search.

  3. An intrinsic command may be abbreviated by using any string containing at least the characters prior to the asterisk shown in the Table 3.5-1. (E.g., ABORT may be abbreviated "A" or "AB" or "ABO" or "ABOR".)

  4. A proc name may not be abbreviated unless an abbreviation has been defined using the DEFCMD command.



Table 3.5-1.

Interactive Intrinsic Commands


Command                  Description
-------                  -----------

A*BORT                   Terminate proc
BATCH                    Batch queue manipulation
COHPI*LE                 Compile a PDF
CONT*INUE                Continue (after attention)
DEFC*MD                  Define command
DELC*MD                  Delete command definition
DELE*TE                  Delete variables
DISA*BLE                 Disable a TAE function
DISP*LAY                 Display variable value(s)
ENA*BLE                  Enable logging, script
EX*IT                    Terminate TAE
H*ELP                    Obtain help information
LET                      Assign a value to a variable
LO*GOFF                  Logoff of TAE
M*ENU                    Enter menu mode
REMO*VE                  Remove job from ASYNC list
REPL*Y                   Reply to Asynchronous Job
REST*ORE                 Restore saved variables
SAVE                     Save variables
SETL*IB                  Set library search order
SH*OW                    Show status
T*UTOR                   Enter tutor mode
WAIT                     Wait upon ASYNC job termination
?                        Help on last message
Note: The "*" implies that the command may be abbreviated by using at least the characters prior to the "*". The "*" is not part of the command.

3.5.2.2 Subcommands

As explained in Section 2.4.5, a TAE command may have subcommands. A subcommand, if present, follows the command name and is separated by a hyphen. The hyphen must be immediately adjacent to the command.

Example:

TAE> SHOW-BATCH FASTQ

This command displays the status of the batch queue named FASTQ.

A command that has subcommands may be defined to have a default subcommand. When that command is typed with no explicit subcommand, the default is used.

3.5.2.3 Command Qualifiers

Command qualifiers are TAE-defined parameters that specify the environment for command execution.

The rules for command qualifiers are:

  1. Command qualifiers are optional and may appear on any TAE proc invocation. Command qualifiers are not allowed with intrinsic commands.

  2. If qualifiers are present, they must be listed between vertical bars ("|") and must be supplied in standard parameter list format. (See below for standard parameter list format.)

  3. As for any parameter list, qualifier values may be specified by position (see "Positional parameters" below) or associated with a qualifier name.

  4. Qualifier names may be abbreviated using the same rules as for parameters.

Example:
TAE> IMGCOPY|TEMP, RUNTYPE=BATCH| FILE1

This command line submits the IMGCOPY proc for batch processing, restores parameter values from the file "TEMP", and supplies "FILE1" as a parameter.

The command qualifiers are listed in Table 3.5-2 and are described in detail below, in positional order.



Table 3.5-2

COMMAND QUALIFIERS


NAME                    ALLOWED VALUES           DEFAULT

1. RESTORE              A file spec              none

2. RUNTYPE             (BATCH, queuename)        SYNCHRONOUS
                       (ASYNC,jobname)
                       (ASYNC-PROCESS , jobname)
                        INTERACTIVE
                        SYNCHRONOUS
                        NORUN

3. SAVE                 A file spec              none


4. STDOUT               A file spec              user
                                                 terminal

5. JOB                  ASYNC jobname            none

6. ASYNCEND             NOTIFY                   SILENT
                        SILENT

  1. RESTORE=file-specification

    The RESTORE qualifier specifies a file that contains parameter values. Values provided explicitly on the proc invocation line override values provided from the restored file.

    An explicit value must be supplied for RESTORE; there is no default. If the RESTORE file specification is the empty string, then the name of the file used for the restore is the same as the proc name.

  2. RUNTYPE= (BATCH, queuename)

    The RUNTYPE qualifier specifies whether the proc is to be run while TAE waits (SYNCHRONOUS/INTERACTIVE), or submitted for BATCH or ASYNC execution. If the RUNTYPE is BATCH, then the second value is interpreted as the name of the batch queue. If BATCH is specified, the following message is displayed:

    Job (nnn) submitted to queue (que)

    where "nnn" is the assigned job number and "que" is the name of the queue the job was submitted to.

    RUNTYPE=ASYNC or
    RUNTYPE= (ASYNC, jobname)

    This qualifier specifies that the proc is to be executed as a normal asynchronous job. (See Section 2.7.1.) If "jobname" is present, then the specified name is assigned to the asynchronous job. If "jobname" is omitted, TAE assigns a unique name to the job. When TAE assigns a unique name, the proc name is used as a base, and suffixes ("1", "2", etc.) are used to make the name unique with respect to previously submitted asynchronous jobs.

    If the proc is located successfully and the parameters are correctly specified on the command line, TAE initiates execution of the proc and displays the following message:

    [TAE-ASYNCJOB] Asynchronous job 'jobname' initiated.

    where "jobname" is the name of the job created for the asynchronous proc.

    RUNTYPE=ASYNC-PROCESS or
    RUNTYPE= (ASYNC-PROCESS, jobname)

    This qualifier specifies that the proc is to be executed asynchronously without the overhead of an accompanying TAE Monitor. The specification of "jobname" is the same as, for normal asynchronous jobs. (See Section 2.7.2.)

    RUNTYPE=NORUN

    This qualifier specifies that the preliminary processing of a proc execution should be performed without actually executing the proc. The full file specification for the proc is placed in the global variable $SKEY. Each parameter is checked for its validity. The NORUN value is particularly useful for verifying parameters in procs with long execution times.

  3. SAVE=file-specification

    The SAVE qualifier specifies a file for saving the values of the parameters. An explicit value must be given for SAVE; there is no default value.

    If the specification of the SAVE file is the empty string, then the name of the file used for the save is the proc's name.

    A parameter set saved using SAVE may be restored using the RESTORE qualifier. The file created by the SAVE qualifier may also be restored in tutor mode using tutor's RESTORE command. In one command line, it is possible to restore a file, assign parameters new values and save the parameter set using the command qualifiers RESTORE and SAVE.

  4. STDOUT=file-name

    The STDOUT qualifier specifies the file or device to be used to receive data sent to the "standard output". Standard output is the file or device that (a) receives messages from TAE commands; and (b) is the output destination for the DISPLAY, HELP, SHOW, and PUTMSG commands. The default for STDOUT depends upon the execution environment:

    The assignment of the standard output applies for the duration of the proc's execution; the assignment also applies to lower level procs invoked by the initial proc. When the proc terminates, STDOUT reverts to the value of STDOUT prior to proc invocation.

  5. JOB=job-name

    The JOB qualifier is an alternate way for specifying the name of an asynchronous job. See description above on RUNTYPE=(ASYNC,jobname).

  6. ASYNCEND=NOTIFY

    The ASYNCEND qualifier is only valid if the RUNTYPE qualifier is set to ASYNC. This qualifier specifies whether notification of job completion is desired. If the ASYNCEND qualifier is set to NOTIFY and the asynchronous job completes, the following message is displayed:

    
    [TAE-ASYNCDONE] Job "'job-name'" complete.

    where "job-name" is the name of the asynchronous job submitted with NOTIFY.

3.5.2.4 Parameter Lists

A parameter list is a list of values to be provided to a proc or command. The format of the parameter list is:

parm-1=value-1, parm-2=value-2,..., parm-n=value-n

"parm-i" represents a parameter name and "value-i" represents a value to be assigned to the parameter. The detailed rules for values are described in Section 3.2.1.

The following rules apply to parameter lists:

  1. List item separators

    The separator between parameters may be a comma, and/or any number of spaces or tabs; a comma may be preceded or followed by spaces and tabs.

    Examples:

    1. TAE> IMGCOPY FROM=FILE1 TO=FILE2
    2. TAE> IMGCOPY FROM=FILE1, TO=FILE2
    3. TAE> IMGCOPY FROM=FILE1, TO=FILE2

  2. Positional parameters

    Parameter names may be omitted in a parameter list, in which case TAE determines the parameter name based upon the position of the value in the parameter list. (To assist users in specifying parameters positionally, descriptions of commands in this manual list the command parameters ordered by position.)

    Note, however, that 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.

    Examples:

    1. TAE> ANAL FILE1, FILE2, FILE3
    2. TAE> ANAL FILE1 TO=FILE2, FORM=FILE3
  3. Null parameters

    Two successive commas in a positional parameter list indicate that the corresponding parameter's default value is to be used. It is illegal to have two successive commas after a value has been provided using an explicit parameter name.

    If a parameter name is specified in the form "name=", but with no value, then the default value is assigned to the parameter.

  4. Abbreviations

    Parameter names may be abbreviated. The allowable abbreviations for a parameter consists of any set of leading characters that is not ambiguous with any other parameter available for the command. For example, if there is a command with defined parameters, FILE, FIRST, and SIZE, then "S", "FIR", and "FIL" are acceptable abbreviations, while "F" and "Fl" are ambiguous.

Each parameter in a parameter list may be "qualified". The format of the qualifier list for a parameter is:

parm=value |qual-1=value-1, qual-2=value-2,..., qual-n=value-n|

"qual-i" represents a parameter qualifier name, "value-i" represents a value to be assigned to the qualifier.

The rules for specifying parameter qualifiers are identical to the rules for parameters. Currently, no parameter qualifiers are defined for intrinsic commands.

3.5.2.5 Variable De-referencing

The "@" character may be used in a value field of a proc invocation command to indicate "use the value of the following variable". The "@" syntax is called "de-referencing" the variable (because, without the special syntax, the variable name would be taken as a string constant).

The rules associated with de-referencing are:

  1. De-referencing may only be used in a proc invocation command and may only occur in the parameter/qualifier value field. The value field may be a positional field or field explicitly associated with a parameter/qualifier name.

  2. The item being de-referenced must be a simple variable name, i.e., it is illegal to de-reference one component of a multi-valued variable with "@variable(index)".

  3. The exact value associated with the variable is used as the value of the corresponding parameter/qualifier. The variable must be compatible in type and count with the corresponding parameter/qualifier.

  4. De-referencing is not allowed in tutor mode.

Examples:

  1. TAE>IMGCOPY INPUT=@FILE1|BANDS=@FRAME1| OUTPUT=@FILE2
  2. TAE>IMGCOPY @FILE1|@FRAME1| @FILE2

3.5.2.6 Missing Parameters/Qualifiers and Parameter Latching

If a user invokes a proc and fails to provide all the mandatory parameter/qualifier values, the user may then type "TUTOR" with no proc name, and TAE will enter tutor mode for the proc. Furthermore, initial parameter/qualifier values shown in tutor will include those values that were successfully entered on the failed proc invocation line. This capability is called "parameter latching".

Example:
TAE> IMCCOPY FROM=FILE1
[TAE-MISPARI Missing parameter(s): TO
TAE> TUTOR

The second command, "TUTOR", starts tutor mode with the value of the FROM parameter set to FILE1.

3.5.2.7 Line Continuation

A command may be continued to another line with the + character as the last non-comment character of a line. For example:

TAE> IMGCOPY +

TAE>+ FROM=ANAME + !Comment

TAE>+ TO=BNAME

A line may not be continued in the middle of a command name, parameter name, or value. For multi-valued parameters, continuation may occur between the component values.

3.5.2.8 Retracting a Command

If the ESCAPE key is, pressed twice anywhere within a command, the current command--including all previous continuation lines--is ignored and the user is re-prompted.

(Note: If the terminal is VT220 and is in VT220 mode press "CTRL [" twice to retract the command.)

3.5.3 Dynamic Parameter Entry

If an executing proc requests additional parameters/qualifiers, TAE enters dynamic tutor mode. Dynamic tutor begins with the message "Parameters Requested:", followed by the names of the parameters that are to be set by the user. (In certain cases, however, the executing proc may replace the standard dynamic tutor greeting with a proc-generated message). The dynamic tutor options available to the user are: