README for Net::SMPP Perl module
================================
12.3.2001, Sampo Kellomaki <sampo@symlabs.com>
7.7.2001,  added SMPP 4.0 support --Sampo
28.9.2001, fleshed out the readme --Sampo
29.4.2005, a small update --Sampo
$Id: README,v 1.7 2005/03/29 19:23:20 sampo Exp $

This readme describes version 0.92 of the module,
implementing SMPP 3.4 and SMPP 4.0.

WARNING: This is still highly experimental code. Some of the V4.0
  features have been tested against real world SMSC. Version 3.4 has
  only been tested against this module itself. Please, if you do not
  know what you are doing, don't ask me to teach how SMPP works. If you
  understand SMPP, please submit bug reports and preferrably
  patches. I am also very interested in success/failure reports on
  testing different features against real world SMSCs.

That being said, version 1.03 was in use for over two years by
multiple sites, thus I guess some stability and correctness is
implied. Current version as of 29.4.2005 is 1.04. Given that the
release cycles have been in multiple years, people have asked if its
maintained at all. Yes its maintained by me, but only to fix bugs. No
new development has been done in ages. I guess this is a stable piece
of software so not many updates are needed. If someone wants to start
new big project to overhaul this code base and significantly add to
it, you are welcome.

Introduction
------------

Net::SMPP is an implementation of Short Message Peer to Peer protocol
over TCP. This protocol is frequently used in the telecoms and mobile
operator world to pass short messages between systems that implement
the short message service (SMS). It is applicable to both european GSM
and american CDMA based systems. The SMPP protocol is documented at

	www.smpp.org

This module aims at fully implementing version 3.4 of the
protocol. During the 0.xx version series the implementation will still
be incomplete or may contain parts that are implemented but never
tested. Read comments in the source to see if testing has been
done. If you test a previusly untested PDU (protocol data unit),
please report success, failure, or difficulties to the author.

This module also implements 4.0 and aims to support it fully as
well. The 4.0 code is based on documentation freely obtained
from Logica (i.e. not under NDA).

SymLABS (www.symlabs.com) uses this module in real life product
development. Despite our commercial objectives, we have decided
to make this module available to public in the belief that

	- someone else will benefit from it and thus will
	  help us debug and improve it
	- we promote better sharing of information about
	  specifications and commonly encountered usage
	  patterns (which may not always be 100% in spec)
	- open distribution protects our client's interests

We are committed to keep this module under license substantially
similar to the one under which the present release is offered and hope
this will encourage contribution from the community. If you need other
licensing arrangements, we as copyright holders are willing to
accommodate you.

To build an entire solution takes much more than just this protocol
module. We are specialists in integrating various internet and telco
protocols and building whole solutions. For integration and support
services, please contact symlabs@symlabs.com

Building
--------

	perl Makefile.PL
	make
	make test
	make install	# su to root prior to this, if needed

Testing
-------

Make test target has not been properly developed yet.

Check from smsc.pl and esme.pl that you are contacting appropriate
server, such as localhost. Launch two windows and execute following
commands

	window1: ./smsc.pl
	window2: while ./esme.pl; do echo -n '.'; done

This tests
	- v34 bind_transmitter
	- v34 submit_sm
	- v34 unbind

Repeat

	window1: ./smsc.pl 4
	window2: while ./esme.pl 4; do echo -n '.'; done

This tests the same functionality for version 4.0

Benchmark
	window1: ./smsc.pl
	window2: ./esme-hammer.pl

	# on U1 167MHz (psrinfo -v) with both processes on the same machine 
	# I get ca. 130 synchronous submit - response pairs
	# per second. Client seems to be slightly heavier than
	# the server. This would seem to indicate that the encoding
	# process is heavier than decoding (client needs to encode
	# a big PDU and decode small one while server decodes big
	# PDU and encodes small one). This test wa bound by CPU.
	
	# Same test over 100Mbps ethernet seems to be bound by
	# round trip delay (because this test uses synchronous mode)
	# and gives 135 sync submits. Test client: U2 (2x 296MHz)

	# Same test over 100Mbps ethernet seems to be bound by
	# round trip delay (because this test uses synchronous mode)
	# and gives 100 sync submits. Test client: U5 (270MHz), happy

	# Same test over 100Mbps ethernet seems to be bound by
	# round trip delay (because this test uses synchronous mode)
	# and gives 105 sync submits. Test client: U5 (270MHz), joder

	# Same test over net with 2 clients (running on same U2). Server
	# is reaching CPU saturation. This gives 240 sync submits/sec.

	# Same test over net with 3 clients (running on U2 & U5). Server
	# is reaching CPU saturation (84% User, 10% kernel). This
	# gives 250 sync submits/sec.

	# Same test over net with 4 clients (running on U2 & U5). Server
	# is reaching CPU saturation (84% User, 10% kernel). This
	# gives 272 sync submits/sec.

	# Next test: 4 client boxes (2x U5, 1x U1 with 2 cpus)
	time perl -e '$x = 5; for (1..$x) { fork && exec "./esme-hammer.pl 3 1000" } for (1..$x) { wait; }' 2>/dev/null
	# User 83%, kernel 14%, 259 submits / sec (20 parallel clients)

	time perl -e '$x = 25; for (1..$x) { fork && exec "./esme-hammer.pl 3 1000" } for (1..$x) { wait; }' 2>/dev/null
	# User 82%, kernel 17%, 274 submits / sec (100 parallel clients)

	time perl -e '$x = 250; for (1..$x) { fork && exec "./esme-hammer.pl 3 100" } for (1..$x) { wait; }' 2>/dev/null
	# Fairly long ramp up time can be noticed. There is idle time on server CPU so
	# probably clients are being saturated. On server the number of processes does
	# not seem to go over 250. maxproc limit on server?
	# 1000 parallel clients: there start to be some weird problems and truput for
	# some clients drops to about 80 submits/sec and as low as 22..32 submits/sec
	# Due to many figures not fully matching expectations (e.g. number of processes
	# on the server never reached anywhere near 1000) these results can not be taken
	# as conclusive.
	
	window1: ./smsc.pl
	window2: ./bind-hammer.pl
	# on U1 167MHz with both processes on the same machine 
	# N.B. this benchmark causes the server to fork one
	#      process per iteration of the test. 50% of the
	#      CPU is spent in the kernel during the test.
	# ca. 11 bind-submit-unbinds per second

License
-------

Net::SMPP is copyright (c) 2001 by Sampo Kellomaki (sampo@symlabs.com),
All rights reserved. Portions copyright (c) 2001-2005 by Symlabs
(symlabs@symlabs.com), All rights reserved.  You may use
and distribute Net::SMPP under same terms as perl itself.

NET::SMPP COMES WITH ABSOLUTELY NO WARRANTY.

--Sampo