Typed Data Transfer (TDT) User's Guide
Contents
1. 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 6 3 Example configuration file lt program name client gt lt channel name clnt_to_serv mode out host localhost port 2222 type socket datadesc datadesc xml gt lt channel gt lt program gt This configuration describes a program called client which has one com munication channel namely output socket 2222 from machine localhost The datadesc for this connection is in the file datadesc xm1 Note that the attribute filename is not required in this example 7 Sample applications The sample applications are provided with Makefiles in order to compile and link the programs 19 7 1 C Examples The sample C programs testclnt c and testserv c in the tests subdirec tory of the TDT source directory demonstrate writing data from a client ap plication 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 7 2 Fortran examples The sample Fortran applications are two programs progi f and prog2 f in the ftdt t2. C The identifier for this data transfer 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 Output parameter None Example CALL tdt_fwrite tdtstate astruct astruct 3 2 4 tdt_fread Purpose To read data from the connection given by the TDTState parameter as per the XML identifer string parameter name Input parameters C The identifier for this data transfer tdtstate 10 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 Output parameter None Example CALL tdt_fread tdtstate astruct astruct 3 2 5 tdt_ fclose Purpose Closes the connection or open files and frees TDT allocated memory Input parameters C The identifier of the connection to be closed ts Output parameter None Example CALL tdt_fclose tdtstate 3 2 6 tdt_fend Purpose Frees memory allocated by the TDT for the configuration information Input parameters C The identifier of the stored configuration data tc Output parameter None Example CALL tdt_fend tdtconf 11 3 3 Compiling and linking 3 3 1 Compiling the library 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 file
3. following XML lt xml version 1 0 encoding ISO 8859 1 gt lt data_desc gt lt decl name vardouble gt double lt decl gt lt decl name astruct gt lt struct gt lt decl name elemi gt lt array size 2 gt int lt array gt lt decl gt lt decl name elem2 gt double lt decl gt lt struct gt lt decl gt lt decl name varint gt int lt decl gt lt decl name dyn gt lt array size 0 gt double lt array gt lt decl gt lt data_desc gt represents describes the data being transferred in the client program above It describes the following C declarations double vardouble struct int elemi 2 double elem2 astruct int varint double dynarray 6 TDT Configuration files The configuration files used by TDT are also written in XML 18 6 1 lt program gt tag The document level tag for a configuration file is the lt program gt tag Attributes name abcde where abcde is an alphanumeric string 6 2 lt channel gt tag The lt channel gt 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 mode the mode of the channel i e input or output in out 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
4. for i 0 i lt varint i dynarray i i 0 33 Get the configuration tc tdt_configure clntconf xml Establish the connection ts tdt_open tc clnt_to_serv now write the data tdt_write ts amp vardouble vardouble tdt_write ts amp astruct astruct tdt_write ts amp varint varint we haven t yet told TDT how big dynarray will be so do that now tdt_size_array ts dyn varint 55 56 57 58 59 60 61 62 63 and write it tdt_write ts dynarray dyn tidy up close connections etc tdt_close ts tdt_end tc return 0 The TDT specific lines to note are these 5 Includes tdt h 25 26 Declare TDTState for connection specific configuration and TDTConfig for program specific configuration 42 Calling tdt_configure gets all the configuration data required 45 Open the connection clnt_to_serv is the name in clntconf xml which uniquely identifies the connection to open 48 49 50 Each call to tdt_write does just that it write the data On line 48 for example the variable vardouble is written to connection ts and the description comes from vardouble Note that the name of the decl in the data description does not have to be the same as that of the variable but it makes it clearer if it is 53 Using tdt_size_array to dynamically size an array Note that we ve al ready written the variab
5. The TDT specific lines are the following 4 5 Declare two TDTStates One is for a tdt_fread and the other for a tdt_fwrite 6 Declare a TDTConfig variable 15 Parse the configuration data 17 Open the first connection 18 Write data on the open connection 20 Open another connection 21 Read data from the new connection 26 27 28 Close connections and tidy up 3 5 Error conditions 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 13 4 Using the TDT in Python 4 1 Prerequisites 4 1 1 Imports The line from tdt import TDT should appear at the start of your programs This requires that tdt py be in your PYTHONPATH 4 1 2 Declarations Declare a new instance of a TDT object like this tdt TDT 4 2 User Functions 4 2 1 config Purpose Read and parse the given configuration file Input parameter config_filename the name of the config file to be parsed Output parameter None Example tdt config clntconf xml1 4 2 2 open Purpose open opens the communication channel specified by the connection name Input parameters channel_name the name of the channel to be opened Example tdt open channel1 14 4 2 3 read Purpose To read the data specified by the given XML identifier Input parameters datadesc the description of the data being read variable the data to be read Ex
6. Typed Data Transfer TDT User s Guide Ciaron Linstead lt linstead pik potsdam de gt 18th November 2004 Revision History 04 03 2002 CL version 0 1 12 09 2003 CL version 0 2 extensive revision 29 07 2004 CL version 0 3 converted master document to AT X from LyX 18 11 2004 CL version 0 4 minor mods to C section added Python section 1 Introduction 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 In this way complex data types i e data types composed of elements with different data types like a struct in C can be passed between TDT enabled programs with a single function call The TDT library also takes care of byte swapping when transferring data be tween big endian and little endian architectures The speed of transferring blocks of homogenous data like arrays is practically the same as with the non TDT method The flexibility of the TDT approach means that modules can be coupled in var ious configurations and by various communications methods simply by altering configuration files no re compilation of modules is necessary 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 so
7. ample tdt read d a_double 4 2 4 write Purpose To write data identified by the given string Input parameters datadesc the description of the data being written variable the data to be written Example tdt write d a_double 4 2 5 size array Purpose This function is used to redefine the size of an array given in a datadesc If your program uses dynamically sized arrays you probably won t know in advance what size the array is when you create the datadesc XML In this case you can set the array size to zero in the datadesc and adjust the size later Input parameters array the array being resized size the new size of the array Example tdt size_array dynarray 10 15 10 11 12 13 14 15 16 17 18 19 20 21 22 23 4 2 6 end Purpose Closes connections or open files and releases TDT structures Input parameters None Example tdt end 4 3 Example programs from tdt import TDT tdt TDT tdt config servconf xml1 tdt open inputi d tdt read new_double print d str d astruct tdt read astruct print astruct repr astruct i tdt read new_int print i str i tdt size_array dyn i dyn tdt read dyn print dyn tdt end 5 TDT Data descriptions in XML XML eXtensible Markup Language is a widely used format for structured data and documents For a more deta
8. ay is when you create the datadesc XML In this case you can set the array size to zero in the datadesc and adjust the size later Input parameters TDTState ts identifier for this data transfer String name name of the array being resized int size the new size of the array Output parameters None Example tdt_size_array ts dyn new_int 2 2 6 tdt_close Purpose Closes the connection or open files and frees TDT allocated memory Input parameters TDTState ts The connection to be closed Output parameters None Example tdt_close ts 2 2 7 tdt_end Purpose Frees memory allocated by the TDT for the configuration information Input parameters TDTConfig tc The config data to be freed Output parameters None Example tdt_end tc 2 3 Compiling and linking 2 3 1 Compiling the library The TDT can be compiled as a static 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 2 3 2 Linking with your own programs First build the library libtdt a as explained above Compile your application gcc c I lt location of tdt h gt Wall lt program gt c and link gcc lt program gt o L lt location of TDT library gt ltdt lexpat_linux o lt program gt
9. ckets 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 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 2 Using the TDT in C 2 1 Prerequisites 2 1 1 include s To include the TDT library simply include tdt h 2 1 2 Declarations 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 TDTConf ig is also required This is used to refer to the data which will be read from a configuration file Examples TDTState ts TDTConfig tc 2 2 User functions 2 2 1 tdt_configure Purpose Read and parse the specified configuration file Input parameter String config_filename the name of the config file to be parsed Output parameter TDTConfig tc a parsed copy of the configuration file Example tc tdt_
10. configure config xml 2 2 2 tdt_open Purpose tdt_open opens the communication channel specified by the connection name Input parameters TDTConfig tc the TDTConfig variable String connection_name the connection to open Output parameter TDTState ts a completed TDTState variable Example ts tdt_open tc client_to_server 2 2 3 tdt_read Purpose To read the data specified by the given XML identifier from the connection given in the TDTState parameter Input parameters TDTState ts identifier for this data transfer void value where to store the incoming data String name the name of the data to be read as it appears in the datadesc Output parameters None Example tdt_read ts amp astruct astruct 2 2 4 tdt_write Purpose To write data to the connection given by the TDTState parameter as per the XML identifer string parameter name Input parameters TDTState ts identifier for this data transfer void value pointer to the data being written String name the name of the data to be written as it appears in the datadesc Output parameters None Example tdt_write ts amp astruct astruct 2 2 5 tdt size array Purpose This function is used to redefine the size of an array given in a datadesc If your program uses dynamically sized arrays you probably won t know in advance what size the arr
11. e a dictionary an integer and a dynamic array a Python list To run the examples go to the python tests directory and run python clnt py and serv py in any order If the following error occurs Traceback most recent call last File clnt py line 1 in from tdt import TDT ImportError No module named tdt you need to adjust the PYTHONPATH variable on your system to include the location of the tdt py file 9 Further information If you need further information have comments or requests for enhancements or you ve found a bug you can contact the authors Ciaron Linstead lt linstead pik potsdam de gt Cezar Ionescu lt ionescu pik potsdam de gt Dan Beli lt beli pik potsdam de gt 21
12. ests 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 progi and prog2 8 make parameters The following parameters can be passed to make FF specifies the name of the Fortran compiler default is x1f 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 make FF g77 EXPAT expati 95 2 OS AIX all 20 make clean will remove old object 0 files and executable programs from the tdt tests and tdt directories or ftdt tests and ftdt 8 1 Python examples The Python examples are two programs c1nt py and serv py in the python tests subdirectory which read and write data between each other clnt py writes four items to serv py a doubl
13. iled introduction to XML see http www w3schools com xml default asp 16 5 1 lt data_desc gt tags This is the root element or document element required by XML Attributes none 5 2 lt decl gt tag Each XML description of a model is made up of one or more variable declara tions which are identified by lt dec1 gt tags Attributes name abcde where abcde is one or more alphanumeric characters 5 3 lt struct gt tag The lt struct gt and lt struct gt tags surround one or more declarations analo gous to a struct declaration in C Attributes none 5 4 lt array gt tag The lt array gt and lt array gt tags surround a text element indicating the primi tive type or a declaration if the array is made up of composite types Attributes size n where n is an integer If the size of the array is unknown at the time the datadesc is being created it can be set to zero and later given a size with the tdt_size_array function 5 5 lt addr gt tag The lt addr gt and lt addr gt tags surround declarations indicating that this is a pointer to a value not the value itself Attributes none 5 6 Text elements 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 lt decl gt or an array lt array gt The allowed values are int double float and char 17 5 7 Example The
14. le varint to the server It will use this variable in a similar call to tdt_size_array before reading the dynamic array 59 60 Tidying up tdt_close closes the connection ts We could re open it later but not after we ve called tdt_end which removes the configuration information from memory 2 5 Error conditions 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 3 Using the TDT in Fortran 3 1 Prerequisites 3 1 1 Declarations The following declarations are needed INTEGER tdtstate INTEGER tdtconfig 3 2 User functions 3 2 1 tdt_fconfigure Purpose Read and parse the specified configuration file Input parameter C the name of the configuration file configfilename Output parameter C a parsed copy of the configuration information tdtconf Example CALL tdt_fconfigure tdtconf config xml 3 2 2 tdt_fopen Purpose tdt_fopen opens the communication channel specified by the connection name Input parameters C a TDTState variable tdtstate C a TDTConfig variable tdtconf C the connection name connection Output parameter C a completed TDTState variable tdtstate Examples CALL tdt_fopen tdtstate tdtconf client_to_server 3 2 3 tdt_fwrite Purpose To write data to the connection given by the TDTState parameter as per the XML identifer string parameter name Input parameters
15. s Running make lib from within the tdt source directory will rebuild the TDT library 3 3 2 Linking with your own programs First build the library libtdt a as explained above Compile your application xlf c Wall lt program gt f and link xlf lt program gt o L tdt o lt program gt ltdt lexpat_linux 0 lt program gt where lt program gt o is the output from the compilation of lt program gt f 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 xlf lt program gt o L lt location of TDT library gt ltdt L lt location of Expat library gt lexpat 3 4 An example program PROGRAM fclnt INTEGER datai 2 5 REAL 8 data2 10 15 10 10 INTEGER tdtstatel INTEGER tdtstate2 INTEGER tdtconf DO k 1 2 DO 1 1 5 datai k 1 k 10 1 PRINT datat k 1 12 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 END DO END DO CALL tdt_fconfigure tdtconf clntconf xml CALL tdt_fopen tdtstate1 tdtconf conn1 CALL tdt_fwrite tdtstate1 a data1 CALL tdt_fopen tdtstate2 tdtconf conn2 CALL tdt_fread tdtstate2 b data2 PRINT I read PRINT data2 CALL tdt_fclose tdtstate1 CALL tdt_fclose tdtstate2 CALL tdt_fend tdtconf END
16. where lt program gt o is the output from the compilation of lt program gt c 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 gcc lt program gt o L lt location of TDT library gt ltdt L lt location of Expat library gt lexpat o lt program gt 2 4 An example program The following client program and it s associated server and a Makefile can be found in the tdt tests subdirectory of the TDT distribution CLIENT WRITER EXAMPLE include lt stdio h gt include lt stdlib h gt include tdt h int main int argc char argv 10 TR 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 a loop counter int i declare the variables we re going to write double vardouble struct int elem1 2 double elem2 astruct int varint double dynarray declare some variables required by TDT TDTConfig tc TDTState ts Now make up some meaningful data to write astruct elemi 0 10 astruct elemi 1i 20 astruct elem2 199 99 vardouble 123 45 varint 12345 dynarray double malloc varint sizeof double
Download Pdf Manuals
Related Search