This section describes how to implement a program (i.e., a "process")to run under TAE.
As described in Section 2 of the TAE Command Language (TCL) Programmer's Manual, a program running under TAE becomes known to TAE through a PDF. The PDF defines the program's parameters and indicates where the help information for the program can be found.
The program coordinates with the Terminal Monitor to receive and manipulate the program's TCL variables (including program parameters) through the p_ and q_ function packages described in Section 3.9 of this document, or through the Vm_ package described in the TAE Plus C Reference Manual.
(The Vm_ package allocates memory internally, whereas the p_ and q_ packages require that the caller allocates the memory. Use of the Vm_ package is recommended.)
The other function packages described are:
The programming language for TAE applications development addressed in this document is C. For FORTRAN-77 applications development, see "TCL Runtime Services Volume 2: FORTRAN." Programs may be written in other high level languages, but must be linked with the standard TAE function library.
Since a major objective of TAE is portability, several conventions have been adopted to promote host-independence. These conventions are described in the following sections.
This document references constants and block sizes as uppercase symbols, e.g., SUCCESS is the constant that indicates a successful status return from a function. These value definitions exist as C define statements in include files; see Section 2.2.4 of this document for details.
Each TAE library function name begins with one or more special characters, corresponding to the utility package in which the function is grouped, followed by an underscore. For example, "p_ for the parameter and variable retrieval package, "t_ for the terminal I/O package, and "Dp_ for the dynamic PDF manipulation package.
An executable image file is created using the host's object module linker. The executable file must be placed in the same library as the PDF for the program, or the PROCESS command in the PDF must supply the file specification. (See Section 3.4 of the TCL Programmer's Manual.)
For the link commands suitable to a particular host, see Appendix A of this document.
Functions are provided in the standard TAE library for initialization (z_init) and termination (z_exit). Although there is no requirement that a program running under TAE call these functions, their use is recommended. When a program is submitted as a batch job without z_init, all output is lost. See Section 8 of Volume 1 for details.
Note that programs that are never initiated under the Terminal Monitor (e.g., some TAE Plus, WPT-based programs) need not call z_init and z_exit.
This section describes the TAE include files. The general conventions for TAE include files are as follows:
/* header comments */ /* change log */ #ifndef I_PARBLK #define I_PARBLX 0 #include "symtab.inc" /* needed by PARBLK */ /* PARBLK definitions */ #endif
Thus, if a file is included twice in the same compilation (a common situation), the compilation works successfully.
In this document the term "V-block" is equivalent to a "PARBLK structure." A discussion on the V-block can be found in Section 3.2.
This include file defines the record format for parameter files. The same record format is also used in communication between TM and application processes. The LARGE_PARBLK and PARBLK structures are defined here; they are required by the parameter and variable manipulation package and z_init. The file also defines LARGE_P_BYTES and P_BYTES for the storage pool size.
"parblk.inc" includes "symtab.inc" and "pgminc.inc" automatically.
This include file contains the C language definitions of the constants required for applications programs (written in C) to interface with the TAE application function library. The file defines the P_ and M_ codes. This file is automatically included with the "parblk.inc" file.
This include file contains the standard C definitions, which include such data types as COUNT, TEXT, etc. This file does not have to be explicitly referenced--it is automatically referenced by the "taeconf.inp" include file.
This include file contains TAE symbol table definitions and macros. The primary data structure is the VARIABLE structure. The file defines V codes for variable attributes. This file is automatically included with the "parblk.inc" file. The VARIABLE structure is described in Section 3.9.2.
This include file contains TAE standard data types (e.g. CODE, FUNINT, TAEINT and TAEFLOAT) and constant definitions. In addition, it contains definitions associated with the TM configuration. This primarily includes definition of parameters which control the size of TAE internal arrays. The file taeconf.inp should be referenced by every C source module.
taeconf.inp also defines the macro MOVE STRUCT to perform structure movement. Assuming a defined structure type of ALPHA, the following code sequence demonstrates the use of MOVE_STRUCT:
struct ALPHA a = {1, 2, 3);
struct ALPHA b;
struct ALPHA *ap;
struct ALPHA *bp;
ap = &a;
bp = &b;
MOVE_STRUCT(a, b); /* move a to b */
MOVE_STRUCT(*ap, *bp); /*repeat previous operation */
This include file contains the definitions of constants required for using the terminal package.
This include file contains the definition of the various WPT package functions. The file also includes wptevent.h which contains the definition of the Wpt Event data constants and structures.
Additionally there is wptdefs.h which defines many of the other constants required for using the WPT package.
This include file contains definitions of the IFCB structure and constants required for using the image I/O package.
As described in Section 2.7 of the TAE Command Language (TCL) User's Manual, a user may indicate that an asynchronous proc is to run without an associated Terminal Monitor. Because there is no Terminal Monitor, there are several restrictions, described in Section 2.7.2 of the TAE Command Language (TCL) User's Manual. This section lists additional rules for those ASYNC-PROCESSes that communicate with other jobs using the SENDVAR/RECVAR protocol.
A simple ASYNC-PROCESS server in the C language is shown in Appendix B.3. The following considerations apply:
Note that the SENDVAR/RECVAR protocol requires that each message contain a string variable named JOB to identify the originator of the message. SENDVAR and RECVAR are described in the TAE Command Language (TCL) Programmer's Manual, Section 3.4.
The "makerel" and "makeabs" functions have the same arguments: the first argument is a pointer to a TAE PARBLK symbol table and the second argument is a pointer to PARBLK pool where variables are stored.
Sections 3 through 10 in this manual, and the TAE Plus C Reference Manual, describe the calling sequences for TAE utility functions. The functions exist to standardize access to primitive host functions and to enhance the portability of the calling programs.
The functions are grouped into packages of related routines follows:
Section Package Name Title
TAE Command Language (TCL) Runtime Services Volume 1: C
3. p_/q_ Parameter/Variable manipulation
4. t_ Terminal I/O
5. m_ Message logging
6. i_ Image I/O
7. c_ Interproc communication functions
8. z_ Miscellaneous
9. Dp_ PDFs manipulation functions
10. Dm_ MDFs manipulation functions
TAE Plus C Reference Manual and TAE Plus Programmer's Manual
Vm_ Variable manipulation with internal memory
allocation
Co_ Collection manipulation functions
Wpt_ TAE Plus Window Programming Tools
In subsequent sections, the function descriptions are organized as follows:
The calling sequences are defined in the function descriptions in Sections 3 through 10 of Volume 1, and in the TAE Plus C reference manual. The function code type, argument name, type, direction of I/O (input or output)and description are given. The types are: