"libtmcsl.a" contains functions that allows a Tsimmis client to communicate with a Tsimmis server. These functions basically simulates RPC calls by sending messages to the Tsimmis server to invoke one of the hook functions (see SSL.DOC on hook functions), then retrieves results using partial fetch protocol (see FETCH.PROTOCOL).
The set of functions provided in "libtmcsl.a" matches one to one with 5 hook functions defined in "libtmssl.a". "libtmcsl.a" is a client to "libtmcomm.a". It is possible for user not to use "libtmcsl.a". In that case, the user can make "libtmcomm.a" network calls directly to communicate with a Tsimmis server following the partial fetch protocol.
| ^
=======================|===================|=============
|| | | |
|| "libtmcomm.a" | | |
|| TM_RecvData() TM_SendData() |
|| | | |
|| | | |
||=====================|===================|============+
|| V |
|| |
|| tmInit(), tmShutdown(), |
|| tmQuery(), tmFetchRef(), tmFetchObj() |
|| |
|| "libtmcsl.a" |
|| |
+=======================================================+
Figure 1, Interaction Between "libtmcsl.a" and "libtmcomm.a"
*************
* INTERFACE *
*************
To access the 5 functions defined in "libtmcsl.a", the following
header file should be included:
tmcsl.h -- contains declaration for "libtmcsl.a" functions
* Including "tmcsl.h" automatically includes "tmconnend.h" and
"tmtypes.h".
Functions:
---------
## List of functions available in "tmcsl.h" ##
TM_Init - inits the server
TM_Shutdown - shuts down the server
TM_Query - sends a query to server
TM_FetchObj - fetches result object
TM_FetchRef - fetches result reference
TM_ConnectToServer - makes a TCP stream connection to server
## More detailed explaination ##
--
TM_Error TM_Init(TM_ConnEnd *conn, TM_Data *options, uint32 *trigger)
Sends a init comand to the server to execute the hook 'tmInit' with
option parameters in 'options'. 'conn' is the TM_ConnEnd that is
connection with the server. 'trigger' is not used right now because
this function executes synchronously.
RETURNS:
TM_NO_ERROR - no error
TM_INIT_FAILED - server failed to initialiaze
TM_ERR_MEMORY - memory problem
TM_ERR_CONNEND - bad TM_ConnEnd
TM_ERR_SEND - error during send
TM_ERR_RECV - error during receive
--
TM_Error TM_Shutdown(TM_ConnEnd *conn, TM_Data *options, uint32 *trigger)
Sends a shutdown comand to the server to execute the hook
'tmShutdown' with option parameters in 'options'. 'conn' is the
TM_ConnEnd that is connection with the server. 'trigger' is not
used right now because this function executes synchronously.
RETURNS:
TM_NO_ERROR - no error
TM_ERR_MEMORY - memory problem
TM_ERR_CONNEND - bad TM_ConnEnd
TM_ERR_SEND - error during send
TM_ERR_RECV - error during receive
--
TM_Error TM_Query(TM_ConnEnd *conn, char *query, uint32 *trigger)
Sends a query comand to the server to execute the hook 'tmQuery'.
'query' contains the query string to be executed by the server.
'conn' is the TM_ConnEnd that is connection with the server.
'trigger' is not used right now because this function executes
synchronously.
RETURNS:
TM_NO_ERROR - no error
TM_QUERY_FAILED - query failed on server
TM_ERR_MEMORY - memory problem
TM_ERR_CONNEND - bad TM_ConnEnd
TM_ERR_SEND - error during send
TM_ERR_RECV - error during receive
--
TM_Error TM_FetchObj(TM_ConnEnd *conn,
uint32 fetchType,
TM_Data *objRef,
TM_Object **result,
uint32 *trigger)
Fetches objects that are the results of the latest 'TM_Query()' call
to the server. 'fetchType' indicates how many objects to fetch.
Currently, 'fetchType' can be:
TM_FETCH_ALL - fetch all objects
TM_FETCH_ONE - fetch only one object
TM_FETCH_CHILDREN - fetch one object and its 1st level child
'objRef' points to an object reference that references the object or
root of objects being fetched. If 'objRef' is NULL, it refers (by
default) to the top most level object in the result.
'result' points to a TM_Object pointer in which object returned by
the server will be placed. This function dynamically allocates
TM_Object's as return values. After user finishes using objects
returned in 'result', user should deallocate the object by call to
"TM_FreeObject()" or "TM_FreeAllObject()".
'conn' is the TM_ConnEnd that is connection with the server.
'trigger' is not used right now because this function executes
synchronously.
RETURNS:
TM_NO_ERROR - no error
TM_FETCH_FAILED - unable to fetch result at server
TM_INVALID_REFERENCE - object reference is invalid
TM_NULL_RESULT - server returns NULL result
TM_NO_SUPPORT - fetch mode not supported by server
TM_ERR_MEMORY - memory problem
TM_ERR_CONNEND - bad TM_ConnEnd
TM_ERR_SEND - error during send
TM_ERR_RECV - error during receive
--
TM_Error TM_FetchRef(TM_ConnEnd *conn,
uint32 fetchType,
TM_Data *objRef,
TM_Object **result,
uint32 *trigger)
Fetches object references that reference result objects of the
latest 'TM_Query()' call to the server. 'fetchType' indicates how
many objects to fetch. Currently, 'fetchType' can be:
TM_FETCH_ALL - fetch all objects
TM_FETCH_ONE - fetch only one object
TM_FETCH_CHILDREN - fetch one object and its 1st level child
'objRef' points to an object reference that references the object or
root of objects whose object reference is being fetched. If
'objRef' is NULL, it refers (by default) to the top most level
object in the result.
'result' points to a TM_Object pointer in which object references
returned by the server will be placed. This function dynamically
allocates TM_Object's as return values. After user finishes using
objects returned in 'result', user should deallocate the object by
call to "TM_FreeObject()" or "TM_FreeAllObject()".
'conn' is the TM_ConnEnd that is connection with the server.
'trigger' is not used right now because this function executes
synchronously.
RETURNS:
TM_NO_ERROR - no error
TM_FETCH_FAILED - unable to fetch result at server
TM_INVALID_REFERENCE - object reference is invalid
TM_NULL_RESULT - server returns NULL result
TM_NO_SUPPORT - fetch mode not supported by server
TM_ERR_MEMORY - memory problem
TM_ERR_CONNEND - bad TM_ConnEnd
TM_ERR_SEND - error during send
TM_ERR_RECV - error during receive
--
int TM_ConnectToServer(char *hostName, int portNumber)
Makes a TCP stream connection with a Tsimmis server. 'hostName' is
the Internet name of the machine on which the server runs.
'portNumber' is the port number on which the server accepts connection.
This function does not correspond to any function on the server
side. This function is provided as a convinence so that you do not
have to write any low level network code. You can just call this
function to establish a connection with the server. Then creates a
TM_ConnEnd using the returned socket number. Then you can call any
one of the above 5 functions using the TM_ConnEnd.
For example:
int sock;
TM_ConnEnd *conn;
sock = TM_ConnecToServer("db.stanford.edu", 6666);
if (sock < 0) {
printf("unable to connnect to server\n");
exit(1);
} else {
TM_InitConnEnd();
conn = TM_CreateConnEnd(sock);
}
/* do client specific stuff */
...
TM_Init(conn, NULL);
...
/* client is done */
TM_DeleteConnEnd(conn);
TM_ShutdownConnEnd();
close(sock);
exit(0);
RETURNS:
<0 - unable to connect to server
>=0 - socket number of a connection with server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~