This appendix specifies the TAE programming conventions that are different for each host (computer/operating system combination) in which TAR is resident.
The logical names required for application program development are $TAEINC and $TAELIB. The DCL command procedure $TAE:TAESETUPALL.COM ASSIGNs these logical names to the proper directories.
Include files used for C compilation under VAX/VMS are located in the directory ASSIGNed to the $TAEINC logical name. The include file extensions are "mc" and "inp". See Section 2.2.4 for a more detailed description of the include files.
Note that the device/directory portion can be omitted if compilation is performed using the /INCLUDE_DIRECTORY qualifier provided by DCL.
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 CC command for an application program appears as follows:
$CC/ INCLUDE=$TAEINC
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-sharable 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.
See Appendix A of the "TAE Command Language (TCL) User's Manual."
Within TAE library subroutines under VAX/VMS, 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/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:
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.1.7. The following considerations apply when using the DCL command:
Many TAE error messages containa "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.INC file. To obtain the symbolic name of a decimal code, use the DCL SEARCH command against the pgminc.inc include file; for example, to display the text associated with the code 1802, use the following sequence:
TAE>DCL SEARCH $TAEINC:PGMINC.INC 1802
Similarly, the decimal value of a symbolic constant may be determined with the $SEARCH command.
The path_size argument of c_crepath, Section 7.1, is the number of bytes to be allocated to the path (the mailbox). This argument is passed to the VMS $CREMBX system service as the BUFQUO argument. The path must have a size large enough to cover all of the messages that might be queued at one time.
Under VMS, a path is a mailbox created by the $CREMBX system service. The scope of the mailbox name may be determined by manipulating VMS logical name tables--see the description of the $CREMBX system service in the "VAX/VMS System Services Reference Manual." The path structure is defined in include file "$TAEINC:COMMINC.INP".
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; this termlib serves as an interface package for terminal I/O.
Terminal Monitor
The following example, from $TAEDEMOCLASSIC/template.cmak, shows the procedure to compile and link a C application process named 'prog', consisting of a single source module prog.c. It is assumed that the host UNIX system has the termlib library.
$ cc template.c -I$TAEINC $TAELIB/libtaec.a $TAELIB/libtae.a \
-ltermlib -o template
TAE Plus Graphical Interface
For programs that require the X Window System, the following example [example missing in version 5.2 of printed manual] shows the procedure to compile and link a C application process named 'prog', consisting of a single source module prog.c. It is assumed that the host UNIX system has the termlib library.
To build a single source file Wpt-based program under UNIX, please consult the discussion of "taeccone" in the TAE Plus Programmer's Manual. To build a multiple source files Wpt-based program under UNIX, make the Makefile created with the TAE code generator (taecg).
The name of the debugger activated by TAE is indicated by the shell symbol DEBUGGER.
For debugging ASYNC-PROCESS jobs refer to Appendix A of the TAE Command Language (TCL) Programmer's Manual.
The path size argument of c_crepath, Section 7.1, is the number of bytes to be allocated to the path (the socket). Under UNIX, c_crepath ignores this argument. Portable application programs, however, should specify path size large enough to cover all of the messages that might be queued at one time.
Application programs receiving only TAE VBLOCKs should assume that each TCL variable received requires about 64 bytes plus the data needed for the variable's value.
In UNIX, the interproc communication functions are implemented using sockets. The sockets are named with ".sk" appended to the path name supplied by the c_crepath caller.
It is recommended that all socket files in your directory be deleted during TAE startup. (If a server attempts to create a socket named "X" and the file entry "X.sk" already exists, the server will probably abort.) The following TCL command is recommended for the ULOGON.PDF of users that depend on the TAE inter-process communication features:
ush rm *.sk
The path structure Is defined in the include file "$TAEINC:comminc.inp".