This appendix specifies the TAE programming conventions that are different for each host (computer/operating system combination) in which TAE is resident. The conventions are for developing procs that execute under the Terminal Monitor (TM). For developing graphical Wpt-based programs, see the "TAE Plus Programmer's Manual" and the appropriate "TAE Plus (language) Reference Manual".
To avoid the use of hard-coded directory names, TAE defines several shell symbols equated to critical directories:
The TAE subroutine library directory ($TAELIB) includes two libraries: libtae.a and libtaec.a. The libtae.a library contains subroutines used by the Terminal Monitor, FORTRAN application programs and C application programs. The libtaec.a library contains additional C functions used only by C application programs. When building C application programs, the libtaec.a library must be presented to the loader before the libtae.a library.
In those UNIX systems with no termcap/termlib capabilities, at installation time $TAETAELIB/termlib.c is compiled and archived in libtae.a. The libtae.a library then becomes an interface package for terminal I/O.
FORTRAN application programs should include the file "pgminc.fin" in the $TAEINC directory. This file defines PARAMETERS like xsucc for use in calling TAE subroutines.
The following examples show the procedures to compile and link a FORTRAN or C application process named "prog", consisting of a single source module "prog.f" or "prog.c" respectively. It is assumed that the host UNIX system has the termlib library. For compiling and linking Wpt-based programs, see the "TAE Plus Programmer's Manual".
$ f77 prog.f $TAELIB/libtae.a -ltermlib -o prog
$ forcomp prog.f
$ f77 prog.o $TAELIB/libtae.a -ltermlib -o prog
NOTE: On an Apollo system use "ftn" instead of "f77" to compile and link.
$ taeccone prog.cThe name of the debugger activated by TAE is indicated by the shell symbol DEBUGGER. Internally, TAE uses the default of /usr/ucb/dbx (BSD) or /bin/adb (SYSV). The system manager may define the DEBUGGER symbol in the "$TAE/bin/csh/taesetupall" script file.
VMS systems cannot choose a debugger.
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 batch "queue" name: NOHUP or NICE. NOHUP is the default queue name.
To submit a batch job, the Terminal Monitor executes one of the following shell commands:
nice -15 taetm jobnnn.job proc.log >proc.log &
or:
nohup taetm jobnnn.job proc.log >proc.log &
where "proc" is the name of the proc to be executed in batch mode, and "nnn" is a three-digit decimal number unique to each TAE session.
The files "jobnnn.job" and "proc.log" are assigned as the standard input and output files respectively for the TM running in the background. (If the STDOUT qualifier is also used in the user command, the corresponding file name is assigned to the standard output instead of the proc.log.)
When batch and/or asynchronous jobs with the same log file name run simultaneously, output from all the jobs except the last are lost.
To avoid the problem, use the STDOUT qualifier to request unique log file names.
If an asynchronous job is initiated eleven times with the same proc name and if the first job is still active, the response to the eleventh job submitted will be:
[TAE-ASYCRE] Error creating async job
This is caused by a conflict in their job file and parameter file names.
The necessary logical names required for application program development are defined in the DCL command procedure $TAE:TAESETUP.COM. The command procedure ASSIGNs all of the necessary logical names to the proper directories.
INCLUDE files used for FORTRAN compilation under VAX/VMS are located in the directory ASSIGNed to the $TAEINC logical name. The only INCLUDE file required to define TAE constants (e.g., "xabort") is STAEINC.PGMINC.FIN.
TAE application programs should be linked with reference to a TAE-provided options file. This options file, used to link with the proper C run-time library, is created by the TAE installation procedure and can be referenced as $TAELIB:crtl/OPT. No other reference to the C run-time library should exist for the link.
A typical LINK command for an application program appears as follows:
$ LINK/DEBUG program-name, -
$TAELIB: libtae/LIBRARY, -
$TAELIB: crtl/OPT
where $TAELIB:libtae is the file specification of the TAE subroutine library and $TAELIB:crtl is the "C" runtime library.
Linking without an options file will result in either the use of a non-shareable version of the library, which is not as economical, or the use of an older version of the library, which could cause compatibility errors.
TAE normally executes an application program with a "$RUN/NODEBUG" DCL command. A programmer may activate the debugger in an application program using the TAE SWITCH command; see "HELP SWITCH" information for the proper switch bit to enable debugging. Because "$RUN/NODEBUG" is the operational form of program execution, the programmer may include the debugger in every program, not just those versions being developed.
For linking Wpt-based programs, see the "TAE Plus Programmer's Manual."
See Appendix A to the "TAE Command Language (TCL) User's Manual."
Within TAE library subroutines, event flags for asynchronous events are allocated using the VMS LIB$GET_EF subroutine. When such event flags are no longer needed, they are deallocated using the LIB$FREE_EF subroutine.
There is one event flag for synchronous events; it is allocated automatically by TAE, using LIB$GET_EF, at the start of the application.
Application programs that use event flags should also use the LIB$GET_EF and LIB$FREE_EF routines to avoid using the same event flags as the TAE library.
For the VAX implementation, the terminal type is determined by the terminal code established by the DCL SET command. For example, "$SET TERM/DEVICE=VT100" is required to use a VT100 terminal and "$SET TERM/DEVICE=VT52" is used for a VT52.
On VT200 series and certain VT100 series terminals, TAE highlights (i.e., backlights or underlines) a portion of the screen to indicate the current mode. For command mode, the prompt is highlighted. If the terminal has the "advanced video" feature, TAE performs the highlighting.
The highlighting consists of a backlight or an underline, depending upon the last bit of the first block on the VT100 SETUP-B display.
If a VT101 terminal is configured via "$SET TERMINAL/INQUIRE", the advanced video feature is not detected and TAE does not highlight. Either of the following DCL commands will fix the problem:
$SET TERMINAL/ADVANCED
$SET TERMINAL/VT1O1
At the beginning of a session, the Terminal Monitor creates a sub-process for execution of application programs. This sub-process contains the DCL command language processor and remains active for the remainder of the session. The VMS process permanent files in the sub-process are as follows:
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 SYSSINPUT 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.
Debugging an ASYNC-PROCESS depends upon manipulating the assignments of the VMS SYS$INPUT and SYS$OUTPUT logical devices for the ASYNC-PROCESS.
When a proc is executed with the |RUNTYPE=ASYNC-PROCESS| qualifier, TAE creates a VMS process running SYSLOGINOUT(i.e., a process with DCL), and sends the process a $RUN/NODEBUG DCL command for the proc's executable image.
The DCL SYS$INPUT for the ASYNC job is assigned to the TAE$APP_INPUT logical name. By default, TAE$APP_INPUT is assigned to the NL: device upon TAE startup.
The assignment of SYS$OUTPUT depends upon the presence of the STDOUT qualifier:
The following steps describe how to run the VMS debugger for an asynchronous process:
$ASSIGN debugfile TAE$APP_INPUT
where "debugfile" is the file holding the DEBUG commands. This assignment may also be executed by interrupting the Terminal Monitor as follows:
SWITCH 1
This causes subsequent DCL $RUN commands for ASYNC-PROCESSes to have the /DEBUG option rather than the /NODEBUG option.
Interactive debugging may be performed by $ASSIGNing TAE$APP_INPUT to TT (the interactive terminal) and directing STDOUT to TT. To avoid having the debugger and the interactive TAE> prompt compete for the terminal, TAE must be put to sleep while the debugger is active. This can be done by executing the ASYNC-PROCESS from a procedure:
procedure
body
switch 1 !turn on debugging
server |run=async-process, stdout=tt|
dcl wait 10:00:00 !put interactive TAE to sleep
end-proc
There is difficulty in obtaining all of the output produced by batch jobs.
Normally, execution of a batch job produces a single log file which is placed in the default directory and is named proc.LOG. The value of "proc" is the name of the proc submitted for batch execution, or the name specified via the STDOUT qualifier. The information logged in this file consists of the output sent to STDOUT.
By default, the listing of the VMS DCL commands which activate TAE and the output of DCL commands executed under TAE are lost. A new TAE switch bit has been defined which enables the generation of such output. If the TCL command "SWITCH 2" is executed prior to the submission of a proc to batch, two files are produced in addition to the standard log file:
In addition, the output from a "DCL" TCL command will be written to this file.
Both of these log files are produced in the same directory as the normal log file.
If a job submitted to batch does not produce the expected results, it is recommended that the switch bit be set and the job submitted again.
The "DCL" command is a TCL command that permits escaping from TAE into the VMS command language. The command is executed in the sub-process described above in Section A.2.7. The following considerations apply when using the DCL command:
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, use the DCL EXIT command; for example, to display the text associated with the VMS code 99838, use the following sequence:
TAE>DCL
_$EXIT 99838
TAE subroutines return codes that are defined as symbolic constants in the $TAEINC:pgminc.fin file. To obtain the symbolic name of a decimal code, use the DCL SEARCH command against the PGMINC.FIN include file; for example, to display the text associated with the code 1802, use the following sequence:
TAE>DCL SEARCH $TAEINC:pgminc.fin 1802
Similarly, the decimal value of a symbolic constant may be determined with the $SEARCH command.