
PRELIMENARY NOTES ON USING THE SR STRUCTCODEC
=============================================

relevant files:
  structcodec.[ch]
  sr_structcodec.[ch]

example code may be found in 
  testserver.c
  testclient.c

The purpose of the structcodec is to allow the separation of the process
handeling the SR/Z39.50 communication over OSI or TCP from the process(es)
handeling database interface. These processes are called "database processes"
below while the process handeling the SR-communication is called the
SR-server.

The SR-server accepts connect requests from SR-clients over the SR-protocol.
The SR-clients indicate which databases they want to work towards, and the
SR-server knows based on a configuration file how to communicate which each
database server. This will be by communicating with a database process. Each
such communication channel may either be set up to handle requests from a
single SR-client or to handle requests from all SR-clients operating towards
the database server represented by the database process.

The actual communication may take place over tcp/ip or over a pipe.  The
database process sets itself up as server by calling CreateServer(). The
SR-server extablish connection to a database process by calling
ConnectToDatabaseServer(). After a connection has been established the same
routines are used both from the SR-server and from the database process.


srPktStatus = createListener ( connectionParameters, int *fd, elemDesc *struct_top )   [sr_structcodec.c]

Call this function to set up this process as a listener for connections from
the SR-server. struct_top is a reference to the structure description to be
used. If the communication method is connect_tcp_ip the function will not
return in this process, but fork a subprocess which will handle the
connection. If the communication method is connect_tcp_ip_multi the function
will return imediately with a filedescriptor that should be selected on. If
read-activity is reported the function createListener2() should be called to
accept a new client.

Boolean createListener2 ( int fd, elemDesc *struct_top, int *fd )

Call this function to accept a client if connect_tcp_ip_multi connection
method was specified when calling createListener. If True is returned a new
client have been accepted with the file number returned through the last
parameter. 

srPktStatus = connectToDatabaseServer ( connectionParameters, int *fd )   [sr_structcodec.c]

Call this function to connect to a database process.

srPktStatus = closeConnection ( int fd )   [sr_structcodec.c]

Call this function to close down a connection to a database process or to a
SR-server.

socketStat handle_socket ( int fd, Boolean read, Boolean write, Boolean exception,
                           Boolean *selectForWrite );                     [structcodec.c]

Call handle_socket() when select(2) shows activity on any of the
sockets used for structcodec based communication. Set the appropriate
Boolean parameters to indicate if read, write or exception was
indicated for this socket. A value is returned indicating if: 1) a
packet is ready to be read of this socket, 2) the socket has been
destroyed or 3) if no further action is required. The last parameter
is used to indicate if the using code should select for write on this fd. 


Boolean send_struct ( int fd, void *p, Boolean *selectForWrite )      [structcodec.c]


Call send_struct() to serialise and send a structure over the
specified socket. The socket must previously have been initialised
through a call to initialise_socket(). The second parameter of this
function is the structure to be coded. The function returnes a Boolean
indicating its success. The last parameter is used to indicate if the
using code should select for write on this fd.


Boolean read_struct ( int fd, void ** );       [structcodec.c]

Call read_struct() when handle_socket() indicates a structure can be
read of this socket. A Boolean will be returned indicating the success
of the function. The structure will be returned though the second
parameter of this function. 





