Created: 5/22/1995

Definition of important terms and abreviations:
CSL/SSL v1.0 is written based on the original csl/ssl libraries written by Yannis. There are many changes in CSL/SSL v1.0 from the original csl/ssl. CSL/SSL v1.0 is almost a complete rewrite. However, it maintains the global structures of the original csl/ssl.

  * The new libraries supports partial fetch of OEM objects.
  * SSL provides buffering to support fetch one and fetch children for
    those Tsimmis servers that support only full fetch.
  * Asynchronous communication between SSL and CSL.  Asynchronous
    communication allows translator to pipeline the process of getting the
    object from data source with transmission of objects to the client.
  * Improved network protocol, no redundant object copying during
    send or receive.
  * Value of an OEM object may be binary instead of only char strings.
    Using binary values, we can send/receive OEM object containing
    binary image such as a gif picture.
  * No limit on number of children an object can have.  You can add
    more children to an object at anytime.
  * No limit on size or number of objects send or received.
  * CSL returns OEM objects received in C data structures instead of
    char string buffer.
  * A few other things such as "undead" child processes and memory
    problems are not in CSL/SSL 1.0.
  * Source files are under source control using RCS.  (This is not
    really an improvement over the old csl/ssl since Kelly added
    source control to old csl/ssl.)
  * Supports 3 platforms, osf1 on Alpha, aix on RS6000, and ultrix on
    DEC MIPS.  Support for other platforms can be easily added.
  * Improved project make process to support different versions of
    object and binary files for different hardware platforms under the
    same project directory.


The layout for CSL/SSL v1.0 is different from the original csl/ssl.
CSL/SSL v1.0 is actually consisted of 3 libraries.  The libraries are:

        libtmcomm.a, libtmssl.a, and libtmcsl.a

libtmcomm.a provides supports for data types used throughout CSL/SSL
v1.0.  Two major data types supported by libtmcomm.a are TM_Object and
TM_Data.  libtmcomm.a also provides send and receive of these data
types through a network connection using either synchronously or

Both libtmcsl.a and libtmssl.a provides additional functions on top of
libtmcomm.a.  As a result, in order to use libtmcsl.a or libtmssl.a,
libtmcomm.a must be linked.

libtmcsl.a provides a set of functions to connect, query and extract
results from a Tsimmis server.

libtmssl.a provides a set of functions to set up a Tsimmis server loop
that takes in requests from a Tsimmis client and return results back
to the client.

The following two figures shows the configurations of different
Tsimmis programs that use CSL/SSL v1.0

           Tsimmis      |                       |
           Translator   |        User Code      |
                        |                       |
                        |       |  libtmssl.a   |
                        |       +-----^---------+
                        | libtmcomm.a |         |
                                      | network
                        | libtmcomm.a |         |
                        |       +-----v---------+
                        |       | libtmcsl.a    |
           Tsimmis      |                       |
           Browser      |        User Code      |
                        |                       |

Figure 1, example of a Tsimmis translator and Tsimmis browser, each 
program uses two out of the three libraries in CSL/SSL v1.0.

                |                                       |
                |               User Code               |
                |                                       |
                |       |  libtmssl.a   |  libtmcsl.a   |
                |       +-------|-------+-------|-------+
                |  libtmcomm.a  |               |       |
                                |               | 
                                v               v
                          To Tsimmis        To Tsimmis
                          Server Programs   Client programs

Figure 2, example of a Tsimmis mediator which uses all 3 libraries of 
CSL/SSL v1.0.

                |                                       |
                |               User Code               |
                |                                       |
                |               libtmcomm.a             |

Figure 3, A Tsimmis program can choose not to use any of the functions
provided in libtmcsl.a or libtmssl.a.  The program can write custom
routines to communicate with other programs using libtmcsl.a and
libtmssl.a.  libtmcomm.a provides all the neccessary networking codes.


A number of functions in CSL/SSL v1.0 dynamically allocates memory and
deallocate memory.  In general, each memory allocation function in
CSL/SSL v1.0 has a corresponding deallocation function.  Memory
management in CSL/SSL v1.0 follows the following rule of thumb:

  - CSL/SSL does NOT deallocate any memory that is not allocated
    by CSL/SSL.

This rule is important to remember when developing user code that
interacts with CSL/SSL.  For example, suppose a pointer in a CSL/SSL
data structure is set to point to a block of memory allocated by user
code, after calling CSL/SSL function the deallocate the CSL/SSL data
structure, the block of memory allocated by user code will NOT be
deallocated by CSL/SSL.  Here is a C code segment showing the above


        /* oem_object is allocated by CSL/SSL */
        oem_object = TM_NewObject(0); 

         * set label to point to memory location allocated outside
         * CSL/SSL.
        oem_object->label = pointer_to_label;

        /* deallocate oem_object using CSL/SSL routine */


         * at this point, memory pointed by pointer_to_label is NOT
         * deallocated
        printf(pointer_to_label); /* OK */


Conversely, if the user code receives a data structure from a CSL/SSL
function, and the same CSL/SSL function sets the pointer in the data
structure to point to another block of memory allocated during the
execution of the function, after deallocate the data structure by
another CSL/SSL function, the block of memory can NOT be assumed to
still exist.  The following C code segment shows the above senario:


         * TM_FetchObj retrieves a TM_Object from the network.  It
         * allocates the memory needed by the object and all the values
         * associated by the object such as label and type.  It
         * sets the pointers in TM_Object to point to the label and type.
         * It returns a pointer to the allocated TM_Object in 'oem_object'.
        err = TM_FetchObj(conn, TM_FETCH_ONE, NULL, &oem_object, &result);

        my_label = oem_object->label; /* make a copy of the label pointer */

        printf(my_label); /* OK, label points to a string allocated
                             by TM_FetchObj */

        /* deallocate oem_object using CSL/SSL routine */

        printf(my_label); /* !!! NOT OK !!! Since memory block pointed by
                             oem_object->label is allocated in automatically
                             in TM_FetchObj, when TM_FreeObject is called, 
                             the memory block is also deallocated.  The 
                             saved label pointer now points to a invalid
                             memory block.


COMM.DOC       - document on libtmcomm.a
CSL.DOC        - document on libtmcsl.a
SSL.DOC        - document on libtmssl.a
FETCH.PROTOCOL - document on partial fetch protocol