3.2 GENERAL INFORMATION ON OPERATING TAE

3.2.1 Specifying Values for Variables

TAE maintains named values called "variables". There are three classes of variables:

  1. Parameters: These are the values passed to procs. Parameters are the class of variables most visible to the interactive user.

  2. Globals: These are "permanent" variables accessible to all procs. Whereas parameters. have transient values, global variables retain their values across proc invocations.

  3. Locals: These are "permanent" variables (when created interactively), but knowledge of the variables is restricted to interactive use (i.e. a proc cannot determine the value of a user's local variables).

Rules for entering proper variable values are based upon the "type" of the variable. The type of a variable is defined when the variable is created; for parameters, the definition is contained in the associated proc definition file.

3.2.1.1 Types

A variable is defined to be of one of five types; the type of the variable determines the allowable values that the variable may be given, as follows:

  1. INTEGER

    An integer is any number (positive or negative) without a fractional part; a number with a zero in the fraction is also acceptable as an integer. Scientific notation (power of ten notation using "E") is acceptable as long as the fraction is zero. See Appendix A for the range of integers acceptable on a particular computer system.

    Examples:

        1
        13346
        1.
        1.0
        1E3
  2. REAL

    A real number is a number that may have a fraction. The number may be represented by a standard decimal number (e.g., 1.3) or by the "scientific" notation shown below. The following rules apply to real numbers:

    Examples:

        -3.1415
        0.0122222
        301. 732E-12
        2
  3. STRING

    A string is any sequence of characters allowable within the host's character set. The following rules apply to string values:

  4. FILE

    A "file" is a string representing a file specification in the host system. A file variable may be declared to be an input file, an output file, or an input/output file.

    File verification is an option that may be selected when TAE is installed. If not selected, no verification is performed and file type variables become identical to string type variables.

    When a string is assigned to an input file variable, TAE checks that the file exists and that the user has the right to read the file. When a string is assigned to an input/output file variable, TAE checks that the file exists and that the user has read/write access to the file. There are currently no checks for output file variables.

  5. KEYWORD

    A variable declared to be a KEYWORD contains a string (or strings if multi-valued) that is one of a defined set of valid values. KEYWORD variables have the following rules (in addition to those discussed above for strings):

    Examples:

        'BYTE                  ! flagged keyword
    
        parm = BYTE            ! by name
    
    

3.2.1.2 Multi-valued Variables

A multi-valued variable is one that may have several associated values (i.e., a single-dimensioned array). The definition of the variable may specify a fixed number of values or a variable number (up to a specified maximum, currently 300).

If the number of values to be specified for a variable is greater than one, then the values must be enclosed in parentheses and separated by standard TAE list separators, i.e., a comma or spaces or tabs.

A value is considered "missing" from a multi-value list if:

In these cases a default, depending on the variable type, is supplied for the missing value: if the variable is a string, the empty string is used; if the variable is a numeric, zero is used.

If more than one value is specified for a multi-valued KEYWORD parameter, the values must be enclosed in parentheses whether or not the flag character specification method is being used.

Examples of multi-valued variables:

	(6,7,8)
	(6 7 8)
	(L.N L2.N2 L3.N3)
	(one, two, "and three")

Examples of multi-valued KEYWORD parameter specifications are:

	'(BYTE NOLIST)
	OPTIONS = (BYTE NOLIST)

Note that every multi-valued variable has a minimum number of values, a maximum number of values, and a current number of values. If the user specifies a set of values for the variable with fewer than the minimum or greater than the maximum number of values, an error message will be generated.

3.2.1.3 Restrictions on Variable Values

The definition of a variable may constrain the acceptable values to be within a specified set of ranges, or to be one of a discrete set of allowed values. An example of a restriction on an integer variable is the set of ranges 1 through 100, 1000 through 1100, 10000 through 11000; an example of a restricted set of strings is "BLUE," "GREEN," and "RED."

For a restricted set of strings, the user may abbreviate the string value on a command line or in tutor; the rule is that right-hand characters of the string may be omitted, provided the correct string can be unambiguously identified among the set of allowed values.

3.2.1.4 Nullable Variables

In TAE, every variable is viewed as a vector of values and a count of the number of values. Thus, scalar variables have a count of one and a single value. A variable may be declared to be nullable, i.e., the variable is allowed to have the null value. The null value is indicated by two adjacent "-" characters and may be regarded as a vector with a count of zero and (consequently) no components.

Arithmetic may not be performed with null values; arithmetic is only valid for variables with a count of one.

Examples of specifying a null value:

	TAE> LET X = --

	TAE> PROC1 PARM1 = --, PARM2 = HELLO

3.2.2 Global Variables

Global variables are accessible to the TCL user at the interactive level, or by any proc. The two types of global variables are those implicitly defined by the Terminal Monitor and those defined in procs. Global values may be set using the LET command, and displayed using the DISPLAY command or by tutoring on the proc that defines the globals.

Global variables may not be of type "keyword".

3.2.2.1 Implicitly Defined Globals

The implicitly defined global variables maY be viewed by tutoring on the proc TAEGBL. The implicitly defined global variables of interest to the user are all string variables. The implicit globals are:

  1. $AECHO

    $AECHO controls the echoing of command lines in asynchronous jobs. It is multi-valued, where the ith element of $AECHO applies to the ith level of proc; the primary level is always echoed. In addition, the last element set for $AECHO applies to all subsequent levels. The allowable values for $AECHO are the same as $ECHO.

  2. $APLIB

    $APLIB contains names of the currently active applications libraries. At the beginning of a session (that is, before the system and user logon procs are executed), $APLIB consists of the null value and, consequently, there are no application libraries defined for the hierarchy search.

  3. $BECHO

    $BECHO controls the echoing of command lines in batch jobs. It is multi-valued, where the ith element of $BECHO applies to the ith level of proc; the primary level is always echoed. In addition, the last element set for $BECHO applies to all subsequent levels. The allowable values for $BECHO are the same as $ECHO.

  4. $DEFCMDi

    $DEFCMDi represents a series of globals ($DEFCMDO, $DEFCMD1, . . .$DEFCMD9). The variables contain the list of commands defined by DEFCMD (Section 3.5.4.5). The format of each component value is "command=string" where "command" is the command defined by the user, and "string" is the replacement string. "Command" may contain an asterisk indicator to define abbreviations. An example of a list element is:

    	 IMG*COPY=MYLIB: IMGCOPY
    
  5. $DYNTUT

    $DYNTUT selects the form of a dynamic tutor session (Section 3.4). A dynamic tutor session is screen oriented if $DYNTTJT is "SCREEN" and non-screen oriented if SDYNTUT if "NOSCREEN".

  6. $ECHO

    $ECHO controls the echoing of command lines in synchronous jobs. It is a multi-valued, where the ith element of $ECHO applies to the ith level of proc; the primary level is never echoed. In addition, the last element set for $ECHO applies to all subsequent levels. If "BODY" or "YES", the body portion of the procedure will be displayed as the commands are executed; if "FULL", the declarations plus the body will be echoed; if "TRACE", the full file specification of the PDF will be echoed upon proc invocation; and if "NO", no echo at the level. The initial value for $ECHO(1) is "NO". $ECHO may be changed by the user with the LET command.

  7. $FILEVER

    $FILEVER determines whether file verification is enabled. If the value of $FILEVER is "YES", then proc parameters of type FILE are verified according to the ACCESS specification. For example, a file declared ACCESS=IN must exist at the point the parameter is assigned a value.

    If $FILEVER is "NO", then no file verification is performed and the ACCESS specification for FILE parameters is ignored.

  8. $JOB

    $JOB is automatically initialized to the name of the current job. For interactive jobs, $JOB is equal to $SESSION; for ASYNC jobs, $JOB is the name assigned by the parent job.

  9. $LASTCMD

    $LASTCMD contains the 20 most recent interactive command strings typed by the user. $LASTCMD(1) is the most recent command, $LASTCMD(2) is the command previous to $LASTCMD(1), and so on. Thus, a user may examine old commands with "DISPLAY $LASTCMD".

    If $LASTCMD is set to the null value ("LET $LASTCMD = --"), the archiving of previous commands into $LASTCMD is disabled.

  10. $LOG

    This variable is currently fixed to "SESSION", with type "TSL".

  11. $MENUOPT

    $MENUOPT allows suppression of the "Press RETURN key for menu" message and controls the display of menu header information. If SMENUOPT has the value NO_PRESS FOR_MENU, then the Terminal Monitor suppresses the "Press RETURN key for menu" message that usually appears before a menu is reprinted. If $MENUOPT has the null value (--), the default, then the "Press RETURN key for menu" message is displayed.

    "NO_TAG" suppresses the "Menu:" part of the menu screen header, "NO NAME", the proc name, and "NO LIBRARY", the library name. Note also that to set more than one of these attributes, include the attributes in a list. For example,

    	LET $MENUOPT=("NO_PRESS_FOR_MENU", "NO_TAG")
    
  12. $MENUS

    $MENUS is the active stack of menu definition file names. $MENUS(1) is the root menu name, $MENUS(2) is the menu selected from the root menu, and so on. The current menu stack may be displayed with "DISPLAY $MENUS".

    When menu mode is activated following proc execution, $MENUS(n) is the menu displayed, where "n" is the current vector count for $MENUS; if "n" is zero, then TAE displays the menu named "ROOT". An executing proc may change the value of $MENUS, thereby changing the next menu to be displayed.

  13. $MESSAGE

    $MESSAGE controls the terminal action when a message is displayed. With "BELL", TAE sounds the terminal bell and continues; with "PAUSE", the user must press the RETURN key to continue execution; "ATTN" is the combination of "BELL" and "PAUSE"; and "SILENT" means there is no special action for messages.

  14. $PARENT

    For ASYNC jobs, $PARENT is the name of the parent job, i.e., the job that initiated the ASYNC job. For interactive jobs, $PARENT is the null value.

  15. $PROMPT

    The value of $PROMPT is used as the TCL prompt. Before prompting, TCL appends the ">" character to the end of the $PROMPT value.

  16. $RUNTYPE

    $RUNTYPE contains "ASYNC", "ASYNC-PROCESS", "BATCH", or "INTERACTIVE" and is automatically set by TAE according to the session environment.

  17. $SESSION

    $SESSION. is a string, automatically set by TAE, that uniquely identifies the current asynchronous, ASYNC-PROCESS, batch, or interactive session. For VAX/VMS and UNIX implementations of TAE, $SESSION contains a string representation of the process ID.

  18. $SYSCHAR

    $SYSCHAR contains information on system characteristics. The keyword strings in this variable are referenced by help files to generate "conditional" help text. Thus, one help file may be used on several different implementations of TAE and, where needed, generate system-specific information.

  19. $TUTOPT

    $TUTOPT is for tailoring the tutor screen. "NO TAG" suppresses the "Tutor:", "NO NAME", the proc name, and "NO_LIBRARY", the library name on the screen. "COMPRESS" causes future tutor screens to be presented in "compressed" mode (see Section 3.4.4). To set more than one of these qualifiers, include them in a list. For example,

    	LET $TUTOPT=("NO_NAME", "NO_TAG")
    
  20. $SYSLIB

    $SYSLIB contains the name of the system library. At the beginning of a session, $SYSLIB is automatically set to the name of the installation's standard TAE system library. $SYSLIB may be altered during a session in order to change the hierarchy search. If $SYSLIB is set to the null string, the hierarchy search bypasses the system library.

  21. $TUTOR

    $TUTOR selects the form of a tutor session (Section 3.4). A tutor session is screen oriented if $TUTOR is "SCREEN" and non-screen oriented if $TUTOR is "NOSCREEN".

  22. $USERLIB

    $USERLIB contains the name of the user library. At the beginning of a session, $USERLIB is automatically set to the library defined for the user by the system manager. $USERLIB may be altered during a session in order to change the hierarchy search. If $USERLIB is set to the null string, the hierarchy search bypasses the user library.

3.2.2.2 Globals Defined in Procs

Global variables, other than those implicitly defined by TAE, must be defined in procs. The user must invoke the proc that contains the definition of a global in order to use any other proc that refers to the global. Procs that define globals typically define a number of related globals that are needed by a particular application package.

To set the value of a global after the global has been defined, the user may either enter tutor mode for the proc that defines the global, or use the LET command (see Section 3.5.4.13). The value of a global may-also be changed by a proc.

3.2.2.3 Qualifiers for Globals

Global variables may have qualifiers, just as parameters may have qualifiers. The value of the global's qualifier may be set using a TCL LET command. In the following example, the global G, with string qualifier Q, is defined in the GLOBAL PDF, GLOPDF; the following sequence of commands would set Q to "this is Q":

	GLOPDF       !create globals, qualifiers
	LET G.Q = "this is Q"

This feature is useful in avoiding name conflicts among globals from different applications packages. For example, the MET package could define a global "MET" that could then be qualified by all other MET globals, thereby allowing the user to use MET.SIZE for the MET package, and IMG.SIZE for the IMAGE package. See Section 2.3.4 of the "TAE Command Language (TCL) Programmer's Manual" for more information on qualifiers.

3.2.3 Abbreviations

An abbreviation in TAE is the omission of the right-most characters in a given command or parameter name. (Keywords may also be abbreviated as discussed in Section 3.2.1.1.) The rules for abbreviations are as follows:

  1. TCL Intrinsic Commands

    Commands defined in Section 3.5.4 (TAE "intrinsic" commands) may be abbreviated according to Table 3.5-1.

  2. Parameter names

    Parameter names may be abbreviated on a command line or in a tutor operation; the rule is that right-hand characters of the parameter name may be omitted, provided the parameter can be unambiguously identified among all the parameters for the proc.

  3. Tutor, menu, and help commands

    Right-most characters of a tutor, menu or help mode command may be omitted provided the intended command can be unambiguously identified among all the commands in that mode.

  4. Subcommands

    Right-most characters of a subcommand may be omitted, provided the intended subcommand can be unambiguously identified among all the subcommands for the proc.

  5. Libraries and procs

    Library and proc names may not be abbreviated. To avoid excessive typing when referencing a long proc name, use DEFCMD (Section 3.5.4.5) to define an alternate name for the proc.

  6. New abbreviations for commands

    A user may define abbreviations for an intrinsic command or proc name using the DEFCMD command (Section 3.5.4.5).

3.2.4 Special Terminal Keys

TAE uses special, host-dependent terminal keys for some line editing functions (e.g., line and character deletion). The actual keys used are host-dependent and are listed in Appendix A.

3.2.5 Command Editor

For certain CRT terminals, command lines typed by the user may be edited before execution. In addition, previous command lines may be retrieved for editing. Under the VAX/VMS implementation of TAE, VT100 and VT100-compatible terminals have this feature.

(Note: Under VMS, if the VMS command line editor is active, then the TAE command line editor is not available.)

When TAE prompts for a command mode response, the following special keys may be used to edit a command line:

In addition to the basic keys above, the GOLD key (labeled "PF1" on many terminals) may precede a special key to "exaggerate" the meaning as follows:

(Note: on UNIX systems, TAB characters echo as a single space ' '. Also, the terminal 'type-ahead' feature does not work; the user should wait until prompted; by TAE before entering a new command.)

3.2.6 Gaining TAE Attention while a Proc is Running

If the user types the TAE "attention sequence" (a host-dependent key or series of keys) while a proc is running, TAE enters "proc interrupt mode"; the execution of the proc is suspended and the user is prompted with a special interrupt mode prompt.

The attention sequences for the various hosts are described in Appendix A. For VAX/VMS and most UNIX systems, the attention sequence consists of CONTROL/C. The usage rules for proc interrupt mode are as follows:

  1. Any TCL command may be executed; the following exceptions apply:

  2. The ABORT command may be used to force termination of the executing proc. The ABORT command returns the user to normal command mode.

  3. The CONTINUE command resumes execution of the suspended proc.

See Section 3.5.4 for more detailed descriptions of the ABORT and CONTINUE commands.