Ciaron Linstead <linstead@pik-potsdam.de>
Revision History:04/03/2002 CL - First version.
12/09/2003 CL - Second version, extensive revision
The Typed Data Transfer (TDT) Library provides a simple, consistent interface for the transmission of data between programs in a platform- and language-independent way. It moves the complexities of handling data types and data sources into a self-contained library of functions.
The purpose of this document is to explain the use of the TDT function library when writing programs in C or Fortran. Some example programs are included and will be explained.
The TDT functions are written in C, and are provided with Fortran interface functions for using the library in Fortran programs. Opening and closing of sockets and files are handled by TDT functions, and data is written or read by means of a call to the appropriate TDT function.
Apart from adding function calls the code, a programmer must also provide an XML (eXtensible Markup Language) description of the data to be transferred and a configuration file for each program, also in XML. Each data structure being transferred needs its own XML description, each of which may be in separate XML files, or in just one.
To include the TDT library, simply
It is necessary to declare a variable of type TDTState. This variable serves as a unique identifier for each data item being transferred, by bundling an XML description and a descriptor for the communication channel.
A variable of type TDTConfig is also required. This is used to refer to the data which will be read from a configuration file.
Examples:
TDTConfig tc;
Purpose
Read and parse the specified configuration file.
Input parameter
/* to be parsed */
Purpose
tdt_open() opens the communication channel specified by the connection name
Input parameters
TDTConfig tc /* the TDTConfig variable */
String connection_name /* the name of the connection to open */
Purpose
To read the data specified by the given XML identifier, from the connection given in the TDTState parameter.
Input parameters
String name /* the name of the data to be read, */
/* as it appears in the XML description */
TDTState ts /* The identifier for this data transfer */
None.
Example
Purpose
To write data to the connection given by the TDTState parameter as per the XML identifer string (parameter "name").
Input parameters
String name /* the name of the data to be written, */
/* as it appears in the XML description */
TDTState ts /* The identifier for this data transfer */
None.
Example
Purpose
Closes the connection or open files and frees TDT-allocated memory.
Input parameters
None.
Example
Purpose
Frees memory allocated by the TDT for the configuration information.
Input parameters
/* configuration data */
None.
Example
The TDT can be compiled as a library, libtdt.a. This must be in the library path of the development environment, or a directory specified by the -L flag in gcc. A makefile is included with the source files. Running 'make lib' from within the tdt source directory will rebuild the TDT library.
First build the library libtdt.a as explained above.
Compile your application...
This assumes that the Expat XML parser library is available system-wide on your machine. If it is not, and you want to use the Expat library supplied with the TDT, use the following link command:
-ltdt -L<location of Expat library> -lexpat -o<program>
The following declarations are needed:
INTEGER tdtconfig
Purpose
Read and parse the specified configuration file.
Input parameter
configfilename
tdtconf
Purpose
tdt_open() opens the communication channel specified by the connection name.
Input parameters
tdtstate
C a TDTConfig variable
tdtconf
C the connection name
connection
tdtstate
Purpose
To write data to the connection given by the TDTState parameter as per the XML identifer string (parameter "name").
Input parameters
tdtstate
C the data being written
val
C a string containing the name of the data to be written,
C as it appears in the XML description
name
None.
Example
Purpose
To read data from the connection given by the TDTState parameter as per the XML identifer string (parameter "name").
Input parameters
tdtstate
C the data being read
val
C a string containing the name of the data to be read,
C as it appears in the XML description
name
None.
Example
Purpose
Closes the connection or open files and frees TDT-allocated memory.
Input parameters
ts
None.
Example
Purpose
Frees memory allocated by the TDT for the configuration information.
Input parameters
tc
None.
Example
The TDT can be compiled as a library, libtdt.a. This must be in the library path of the development environment, or a directory specified by the -L flag in gcc. A makefile is included with the source files. Running 'make lib' from within the tdt source directory will rebuild the TDT library.
First build the library libtdt.a as explained above.
Compile your application...
This assumes that the Expat XML parser library is available system-wide on your machine. If it is not, and you want to use the Expat library supplied with the TDT, use the following link command:
-ltdt -L<location of Expat library> -lexpat
The user functions of the TDT will crash, returning with error code 1, if an error occurs. It will also output a debugging message to stderr.
This section will not explain XML syntax. For a short introduction to XML, see here:
This is the root element (or document element) required by XML.
Attributes : none.
Each XML description of a model is made up of one or more variable declarations, which are identified by <decl> tags.
Attributes : name="abcde" where abcde is one or more alphanumeric characters.
The <struct> and </struct> tags surround one or more declarations, analogous to a struct declaration in C.
Attributes : none.
The <array> and </array> tags surround a text element indicating the primitive type, or a declaration if the array is made up of composite types.
Attributes : size="n" where n is an integer.
The <addr> and </addr> tags surround declarations, indicating that this is a pointer to a value, not the value itself.
Attributes : none.
Text elements are the value which appear between start and end tags. For TDT XML, text elements are used to indicate the primitive data type of a declaration (<decl>) or an array (<array>).
The allowed values are "int", "double", "float", and "char".
The following XML
<decl name="astruct">
<struct>
<decl name="anarray">
<array size="2">int</array></decl>
<decl name="adouble">double</decl>
</struct>
</decl>
</data_desc>
int anarray[2];
double adouble;
} astruct;
The configuration files used by TDT are also written in XML.
The document-level tag for a configuration file is the <program> tag.
Attributes: name=''abcde'', where ``abcde'' is an alphanumeric string.
An <input_channel> tag is made up of zero or more <channel> tags which, as the name suggests, are the channels on which the program will read data.
Attributes: none
This tag is made up of zero or more <channel> tags, and groups together the channels on which output data will be sent.
Attributes: none
The <channel> tag specifies all the information required to establish a TDT connection and send or receive the data in the correct format.
Attributes:
name : the name by which the channel will be referenced in the code.
type : the type of the connection: "socket" | "file"
host : if type is "socket", the hostname to use
port : if type is "socket", the port to use
filename : if type is "file", the filename to read/write from/to
datadesc : the name of the datadesc XML which describes the data that will pass on this channel
<program name="clnt">
<input_channels>
<!- mode is implicitly READ ->
</input_channels>
<output_channels>
<!- mode is implicitly WRITE ->
<channel name="clnt_to_serv"
host="localhost"
port="2222"
type="socket"
datadesc="example.xml">
</channel>
</output_channels>
</program>
The sample applications are provided with Makefiles in order to compile and link the programs.
The sample C programs (testclnt.c and testserv.c in the tests subdirectory of the TDT source directory) demonstrate writing data from a client application (testclnt) to a server application (testserv). testclnt writes three variables (a double, a struct containing an array of int and a double, and an int) to testserv. In this case, only one TDTState (for one XML description and one communication channel) is required.
Building the examples
Type "make all" from within the tdt/tests directory.
In tdt/tests this will create the programs "serv" and "clnt".
The sample Fortran applications are two programs (prog1.f and prog2.f in the ftdt/tests subdirectory) which read and write data to/from each other. prog1 writes a 2x5 matrix of INTEGERs for prog2 to read and reads a 5x2 matrix of doubles (REAL*8) which is written by prog2.
Two XML files are provided ("example.xml" and "example2.xml"). These describe the two matrices. In these examples the XML files are expected to be in the same directory as the programs reading them.
Two TDTState variables are used by each program (tdtstate1 and tdtstate2). Each TDTState contains information about one matrix and the channel by which that data will be transferred.
Building the examples
Type "make all" from within the ftdt/tests directory.
In ftdt/tests, the programs will be called "prog1" and "prog2".
The following parameters can be passed to make:
FF : specifies the name of the Fortran compiler (default is xlf).
EXPAT : specifies the location of the Expat libraries (default is ../../expat).
OS : specifies the operating system (Linux or AIX). This is used to select the appropriate Expat library (default is Linux).
Example:
If you need further information, have comments or requests for enhancements, or you've found a bug, you can contact the authors:
Ciaron Linstead <linstead@pik-potsdam.de>
Cezar Ionescu <ionescu@pik-potsdam.de>
Dan Beli <beli@pik-potsdam.de>
This document was generated using the LaTeX2HTML translator Version 2002 (1.62)
Copyright © 1993, 1994, 1995, 1996,
Nikos Drakos,
Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999,
Ross Moore,
Mathematics Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -split 0 -nonavigation -show_section_numbers user_guide-v2.tex
The translation was initiated by Ciaron Linstead on 2003-09-13