.TH EASY-SERV l "Nov 1, 1990"
.SH NAME
easy-serv \- simple server/multi-client program library in perl.
.SH SYNOPSIS
.br
.B require """easy-serv.pl""
.br
.B "&register_serv(socket, port)"
.br
.B "&run_serv()"
.br
.B "&cleanup_serv()"
.br
.B "&register_client(socket,  host, port)"
.br
.B "&send_request(socket, request)"
.br
.SH DESCRIPTION
Easy-serv is a set of routines to support constructing
server/client programs.
Although it has a limited features only, it's still useful
for experimental or simple applications.
a server can serve multiple clients at the same time.
Tcp protocol is used for the purpose.
Someone might find some conceputual similarity with Sun's RPC
(Remote Procedure Call).
However there is no XDR (eXternal Data Representation) supports (sorry).
.PP
Routines &register_serv(), &run_serv(), &cleanup_serv() are
used in server side.
The rest &register_client(), &send_request() are used in client side.
.TP
.B "&register_serv(SOCKET, PORT)"
creates a internet tcp/ip SOCKET and bind it to the specified PORT.
This SOCKET will be used as server socket.
You can specify PORT as number or a symbolic name
found in /etc/service.
.TP
.B "&run_serv()"
processes all requests from multiple clients.
Before calling this routine, you must call
&register_serv() to have a server socket.
Users must supply a routine named
.B "&serv_body(REQUEST, SOCKET)"
which does actual services.
In REQUEST argument, you will find data from the current client.
And in SOCKET argument, you have the current client's socket name.
Each client's socket name is made to be unique within a server so that
you can distinguish clients within &serv_body() routine.
For example, if you make a server socket by  &register_serv(SERVER, 79999),
consequently each client's socket has a name like "SERVER..a", "SERVER..b" ..
and so on.
The return value of
&serv_body()
is sent back to the current client as it is.
See the example described below.
.TP
.B "&cleanup_serv()"
closes all sockets and exits.
This is used in &serv_boody() routine.
.PP
The following routines are used in clients.
.TP
.B "&register_client(SOCKET, HOST, PORT)"
makes a client side SOCKET connecting to the specific PORT
on the specific HOST.
For HOST, you can supply a name found in /etc/hosts or
a internet address format like 11.22.33.44.
PORT's format is same as &register_serv().
.TP
.B "&send_request(SOCKET, REQUEST)"
sends an REQUEST to the corresponding server via SOCKET which
is created by &register_client() call.
It waits a reply from server and returns it.
.PP
Easy-serv library routines rely on the routines defined in
easy-ipc.pl.
You might be able to build
more sophisticated applications by using them directly.
.SH EXAMPLE
.sp
A server
.sp
.nf
.ft LP
#/usr/local/bin/perl

require "easy-serv.pl";	# loading the library

&register_serv(SERVER, 7999);	# make a server socket on port 7999

&run_serv();	# dispatching (never returns)

sub serv_body {	# Users must supply this routine.
		# $_[0] : request data sent from a client
		# $_[1] : socket name corresponding to the current client

    print "client sock name=" . $_[1] . "\n";

    if ($_[0] eq "who") {
	$reply = `who`;
    } elsif ($_[0] eq "ps") {
	$reply = `ps`;
    } elsif ($_[0] eq "kill") {
	&cleanup_serv();
    } else {
	$reply =  "who  : who is on this host\\n" 
		. "ps   : show process\\n" 
		. "kill : kill server\\n" 
		. "help : show this message\\n";
    }
    $reply;	# This value is sent back to the current client
}

.ft P
.fi
.sp
A client
.sp
.nf
.ft LP
#/usr/local/bin/perl

require "easy-serv.pl";	# loading the library

&register_client(CLIENT, "myhost", 7999);
			# connecting to port 7999 on "myhost"

$| = 1;
print "-> ";
while(print "-> ", <STDIN>) {
    chop;
    $reply = &send_request(CLIENT, $_); # send a request
    print $reply;			# print the reply
}
.ft P
.fi
.SH FILES
/usr/local/lib/perl/easy-serv.pl : easy-serv library
.br
/usr/local/lib/perl/easy-ipc.pl : low level util. library
.br
/usr/local/lib/perl/sys/socket.ph (not included)
.br
/usr/local/lib/perl/sys/fcntl.ph  (not included)
.SH "IMPORTANT NOTE"
.SH BUGS
Package isn't used (yet).
.br
Tested only on perl v3.0 patchlevel > 37.
.SH AUTHOR
Sakoh, Hiroshi: Software Research Associates, Inc.
.br
sakoh@sra.co.jp or uunet!sra.co.jp!sakoh