APPENDIX A -- HOST DEPENDENT OPERATIONS

This appendix describes the TAE operations that are different for each host implementation of TAE. The systems currently supported are:

A.1 VAX/VMS

A.1.l Logon Sequence

  1. Press the carriage return key of any terminal connected to the VAX system.

  2. In response to the "Username:" prompt, type the user name (assigned by the system manager) followed by a carriage return.

  3. In response to the "Password:" prompt, type the password (also assigned by the system manager) followed by a carriage return. Note that, for protection, the password does not echo on the terminal.

    If the password is accepted by the system, system greeting messages are displayed.

  4. Automatic logon to TAE is initiated. (If TAE does not start automatically, see the TAE system manager for the necessary command file.)

  5. If the terminal type is not known to the system or cannot be determined automatically, a prompt similar to the following is displayed:

    ENTER TERMINAL TYPE (VT100, VT52, OTHER):

  6. Respond with "VT100" or "VT52" to identify the terminal type, followed by a carriage return.

    If the terminal is other than a VT100 or VT52, the correct response is "OTHER" or a carriage return.

  7. TAE now enters menu or command mode as described in Section 3.2 and Section 3.3

The following rules apply to the logon:

  1. If the user specifies the "VT100" terminal, the VT100 terminal must be configured for "ANSI" mode rather than "VT52" mode. See the "VT100 User Guide" (Digital Equipment Corporation, document no. EK-VT100-UG-002).

A.1.2 Special Terminal Keys

The command editor (Section 3.2.5) and the tutor editor (Section 3.4.1.5) describe additional features that assist the user in composing command lines.

A.1.3 Executing VMS/DCL Commands under TAE

To execute a VMS/DCL command under TAE, the format of the command line is "DCL" followed by the DCL command string.

The following rules apply to executing DCL commands under TAE:

  1. The "$" character preceding the DCL command is optional.

  2. "DCL" alone on a TCL command line puts the user into interactive use of DCL. Interactive DCL usage is terminated with an "EXIT" or a "CONTROL/Z".

  3. During an interactive DCL session, if a DCL command returns an error code (i.e., an even $STATUS value), the DCL session is terminated and the TAE prompt re-appears. If, however, a "$SET NOON" DCL command is issued during an interactive DCL session, then DCL errors will not cause an automatic return to TAE.

  4. If the DCL command line must be continued to another line, the TAE continuation convention ("+") applies and not the VMS/DCL convention ("-").

  5. The DCL command has two subcommands, -INTERRUPT and -NOINTERRUPT; the default subcommand is INTERRUPT. The NOINTERRUPT subcommand will suppress the TAE interrupt mode and allow VMS utilities to handle the attention sequence. The DCL-NOINTERRUPT command should be used with great care. If the active utility does not handle the attention sequence, there will be no way of aborting. An effective usage of the NOINTERRUPT subcommand is shown in the examples below.

  6. Cautions:

EXAMPLES

  1. TAE> DCL
$ EDIT filespec

    2. An interactive DCL session is started and the editor is entered.

  2. TAE> DCL $DIR

    The DCL command "DIR" is executed. The "$" is optional.

  3. TAE> DCL

    A DCL dialogue is initiated.

  4. Create a file named EDIT.PDF with contents:

    	  procedure 
	  parm file 
	  body
	  dcl $assign terminal sys$input
	  dcl-nointerrupt $edit &file 
	  end-proc

    The user then may use "EDIT filename" to get into the editor directly from the TAE.

A.1.4 Host Error Codes

Many TAE error messages contain a "VMS/RMS error code," a decimal number indicating the exact nature of the error.

To interpret a VMS/RMS error code, start an interactive DCL session and then use the EXIT command; for example, to display the text associated with the code 99838, use the following sequence:

TAE> DCL
$ EXIT 99838

A.1.5 Acceptable Value Ranges

  1. Integers: 32 bits, signed

  2. Reals:

    Magnitude of smallest non-zero constant: approximately 0.29E-38

    Largest: approximately 1.7E38

A.1.6 Library Names

A TAE library name under VMS is any valid directory specification, including logical names. The pre-defined libraries are:

  1. System proc library: $TAEPDF

  2. System menu library: STAEMENU

  3. System help library: $TAEHELPTM

A.1.7 File Specification

Any VMS file specification may be used without quotation marks as a proc name or as a parameter value. The exception is the DEC-10/DEC-20 form "x.y.z", which is not allowed.

A.1.8 File Extension Types Used by TAE

A.1.9 Name of The Session Log File

SESSION. TSL

A.1.10 Batch

Users may occasionally want to run some of their PROCs in batch mode. Section 2.6 of this manual describes the standard method for directly submitting a batch job from the TAE command line. In cases where users want more control over the batch job, a file must be created and then manually submitted to the batch queue.

On VMS systems a TAE run may be submitted as a batch job by using the DCL command "SUBMIT". This requires that the user create a DCL command file for submission. There are two options for doing this. TAE may be used to automatically create the file or the user may manually create the file using a text editor. The following sections describe these two methods.

A.1.10.1 Creating Batch Jobs With TAE

When submitting a batch job (discussed in Section 2.6), a file is created using the name of the proc but with type "JOB". This file contains TCL commands to create the proper environment and to execute the proc. Normally, the JOB file is deleted when the job terminates.

TAE defines a special queue named "NORUN" that causes the JOB file to be created but suppresses execution of the job. The NORUN queue allows the user to use the DCL SUBMIT command to run the job later or otherwise control the job's execution. Example:

TAE> proc|RUNTYPE=(BATCH, NORUN)|
TAE> DCL submit proc.JOB/after=23:00

The name of the default batch queue is SYS$BATCH.

When the JOB file is created, TAE also creates a PAR file with the name of the PDF and type "JEN". This file is used to pass along values of global and local variables that were current when the JOB file was created. Neither the JOB nor the JEN file is deleted when the batch job terminates. The reason for this is that a NORUN job is likely to be run multiple times.

A.1.10.2 Creating Batch Jobs Manually.

It is also possible to manually create a DCL command file to be submitted as a batch job to run TAE. Note the following information when creating a batch command file:

  1. A batch job starts by doing a logon to the account of the submitter. Thus the initial environment is the same as if the user had just logged on. The batch job file will have to include any necessary commands for setting default directory, etc.

  2. When TAE starts in batch mode, it does not automatically execute SLOGON. This must be included as a TAE command in the file, if desired.

  3. Starting TAE is site dependent.

Here is an example DCL command file for running a TAE job in batch mode:

$!  File:     SHOWBATCH.COM
$!  Demonstrate VMS batch job to run TAE.
$!  Has site dependent details. May not run on all systems.
$!
$ SET DEFAULT [TGC.TEST]
$ ASSIGN SYS$OUTPUT TAEJOBLOG
$ ASSIGN NL: ALTSUBLOG
$ DEFINE TAEACTMODE LOCAL
$ SET NOVERIFY
$ @TAE:TAESETUP ! Not needed if LOGIN.COM does this.
$ TAETM
BATCH           ! Required
SLOGON          ! SLOGON must be explicit
DISPLAY-ALL     ! TCL commands may be used.
MYPROC          ! Run my own proc
SHOW-LIB
EXIT
$EXIT

Details of the DCL command file tend to be site dependent. A good way to get started would be to use the RUNTYPE=(BATCH,NORUN) option to create a job file and then modify that file as needed for your own work.

A.1.11 SYS$INPUT for Application Processes

When the Terminal Monitor (TM) creates the sub-process to be used for executing application programs, the SYS$INPUT for the process is directed to a mailbox; TM sends DCL commands to the sub-process through this mailbox. This source of DCL commands is always used by the sub-process (even if SYS$INPUT is subsequently re-assigned).

After the sub-process is created, TM sends a user mode assignment of SYS$INPUT to the sub-process. This assignment establishes SYS$INPUT for subsequently executed application programs. The target of this assignment depends upon the nature of the TAE session:

If a program that reads SYS$INPUT is to be executed as a TAE batch or asynchronous session, then TAE$APP_INPUT should be re-assigned to a text file containing the inputs for the program.

A.2 UNIX

A.2.1 Logon Sequence

  1. In response to the UNIX "login:" prompt, type the user name (assigned by the system manager) followed by a carriage return. Usually, the user name must be typed in lower case.

  2. In response to the "password:" prompt, type the password (initially assigned by the system manager, may be changed by the user) followed by a carriage return. (Note that, for protection, the password does not echo on the terminal.)

  3. Host system greeting messages are displayed.

  4. Automatic logon to TAE is initiated. (If automatic logon is not setup on your system, see the TAE system manager for the necessary command file.)

  5. TAE now enters menu or command mode as described in Section 3.2 and Section 3.3.

Before entering TAE, the shell symbol 'TERM' must be set to the terminal type. If the UNIX system manager has properly configured '/etc/ttytype' and the terminal is hard-wired, then the TERM symbol is set automatically. Otherwise, the value of 'TERM' should be set to the specific terminal type in '.profile'. For example, the following commands are needed in '.profile' for a VT100 terminal:

TERM=vt100; export TERM
stty dec

If the shell of the TAE user is the C-shell (csh) rather than the Bourne shell (sh), there should be a '.login' file in the user's home directory. The entries in this file should perform functions similar to the '.profile' entries described previously. A sample of this file is the following:

setenv TERM vt100
stty dec
setenv TAE root-of-the-TAE-tree
source $TAEBIN/csh/taesetup
setenv ULIB user-library

The 'DISPLAY' variable allows applications to communicate with the X server. For more information see the "TAE Plus Overview" and the "TAE Plus User Interface Developer's Guide".

The 'ULIB' specifies a default directory to search for application procs.

If the user wants to invoke the Bourne shell, 'sh', rather than 'csh' via that interactive USH command (see below), the following command should be included in '.login':

setenv SHELL /bin/sh

A.2.2 Special Terminal Keys

In UNIX, the "editing" keys may vary from user to user and terminal to terminal. Further, the editing keys are configurable with "stty". TAE users under UNIX, however, usually have the following editing keys:

(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.)

Note: Use of the up- and down-arrow keys in command mode to recall previous TCL commands sometimes has the result of displaying the TAE prompt on a line far removed from the previous command. This can happen, for example, when a process has been invoked which clears the screen: The next TAE prompt is displayed at the top of the screen, although subsequent use of the up-arrow key may display the prompt (and the retrieved command) at the bottom of the screen.

This displacement can be prevented by placing in the user's terminal capability file the appropriate string for controlling horizontal movement of the screen cursor ("ch"). The file is /etc/termcap. For VT100 (and VT200) users, find the VT100 terminal definitions in this file and add "ch=e [%dC".

Help on determining the correct string for the user's site terminals can be obtained by examining the "nd" string for those terminals and also the "ch" strings for other terminals.

A.2.3 Proc Interrupt Mode

An executing proc may be interrupted by typing the attention sequence at the terminal. Under UNIX, the "inter" key assigned with stty may also be used. The attention sequence is normally set to CONTROL/C, but may be changed to some other control character by using the shell command 'stty'.

An interrupted proc may be resumed or aborted under BSD UNIX. In other systems such as the Standard 7th edition UNIX, the proc is always aborted and the user returns to TAE after leaving the proc interrupt mode.

A.2.4 Executing UNIX Shell Commands under TAE

The USH ("UNIX shell") command is a TCL command that permits the execution of shell commands from TAE. The command has the following forms:

  1. TAE> ush shell-command

  2. TAE> ush

In the first form, the shell-command text is executed by a spawned shell. In the second form, an interactive shell session is initiated by activating the shell identified by the SHELL environment symbol. If the TAE user wants to invoke the C-shell, 'csh', rather than 'sh' via the interactive USH command, the following command should be included in '.profile':

SHELL=/bin/csh; export SHELL

If the user wants to invoke the Bourne shell, 'sh', rather than 'csh' via that interactive USH command, the following command should be included in '.login':

setenv SHELL /bin/sh

Control is returned to TAE after the command is executed by a non-interactive shell, or when an end-of-file indicator (CONTROL/D) or the 'exit' command is encountered by an interactive shell.

If the attention sequence is typed while the shell is executing, the non-interactive shell terminates immediately and control returns to TM; an interactive shell aborts the current activity and prompts the user for the next command.

Upon termination of a shell command, TAE sets the $SKEY TCL global to an octal string representation of the status value returned by the shell. The $SFI global is set positive if the USH command was successful (as determined from this status value), and negative otherwise.

The following should be noted when executing the shell under TAE:

A.2.5 TM as a Host Utility

TAE's Monitor (TM) may be executed as a utility, where TM will execute one TCL command (or a proc) and terminate. The command to be executed is supplied on the host command line. For example:

$ taetm disp-globals
or
$ taetm $TAEDEMO/classic/states

If the TCL command string contains blanks, it must be quoted. The following UNIX command displays the contents of the PAR file, xyz.par:

$ taetm "display-parfile xyz.par"

When TM runs in this utility mode, there is no slogon.pdf execution and there is no greeting message. If you omit the TCL command string, TM will run in normal interactive mode, where you are prompted for each command.

This TAE feature is typically used by programmers who normally use the host command language, but who occasionally need utility support from TM.

For C programs running under UNIX or UNIX/TAE, the feature allows execution of a TCL command or proc in the following manner:

system ("taetm procName");

A.2.6 Host-dependent Error Codes

Many TAE error messages contain a decimal error number, the "host error code". These codes and their meanings are described in Section "INTRO(2)" in the most standard UNIX manuals.

A.2.7 Arithmetic Overflow and Underflow

Some UNIX systems do not provide notification of exceptional conditions like integer overflow, floating underflow, and floating overflow. An example of such a system is the UNIX implementation on the SUN workstation. Under such systems, TAE does not report exceptions caused by the evaluation of TCL expressions.

A.2.8 Library Names

A TAE library name under UNIX is any valid directory specification. The specification may include shell-defined symbols prefixed with the "$" character; TAE substitutes the value of the shell symbol when the "$" character is encountered.

The standard, pre-defined library names are:

  1. System proc library: $TLIB

  2. System menu library: $TMENU

  3. System help library: $THELP

A.2.9 File Specifications

A UNIX file specification may be used (without quotation marks) as a proc name or as a parameter value. As a TAE default, file specifications are NOT translated to lowercase before access. Lower case forcing can be enabled via the ENABLE-FORCE_LOWER command.

A.2.10 File Extensions Used by TAE

TAE uses the following "extensions" to indicate the type of a file:

For example, the proc named "/usr/century/copy" corresponds to the file named "/usr/century/copy.pdf".

A.2.11 Name of the Session Log File

session.tsl

A.2.12 Implementation of Batch under UNIX

There is no batch queue management under TAE/UNIX. When a "batch job" is submitted, it is run immediately and asynchronously in the "background". The following is an example of a batch command.

TAE> prog |RUNTYPE=(BATCH, NICE)|

The second argument in the RUNTYPE specifier is the batchqueue" name: NOHUP or NICE. NOHUP is the default queue name.

A job submitted to the queue NOHUP runs at a slightly lower priority than the interactive session; the job continues to execute even after user logout. A job under the queue NICE, on the other hand, runs at a much lower priority and is aborted by the system when the user logs out.

A.2.13 Difference between Batch and Asynchronous Jobs

Under UNIX, batch jobs are processed immediately and asynchronously. However, batch jobs differ from asynchronous jobs in the following respects:

  1. Batch jobs are processed in the background and at a lower priority than that of the interactive Terminal Monitor. Asynchronous jobs are processed in the foreground, and at the same priority as the interactive session.

  2. The number of simultaneously active asynchronous jobs is limited to eight because the Terminal Monitor has to maintain communication with the jobs through open pipes during their execution. There is no such limit for batch jobs.