====================================================================
 PDQ (Pretty Damn Quick) Queueing Analyzer 6
====================================================================
PDQ is an analytic queueing-circuit analyzer made freely available under
MIT/X11 license from www.perfdynamics.com
See the COPYING file (same level as this README) for more legal gore.

New features of PDQ 6
---------------------
The main purpose of this release is improved compatibility and stability 
between PDQ and the R statistical package environment. Many PDQ models 
found in the /examples directory can now also be accessed by issuing the 
demo() command in the R-console. Otherwise, PDQ should look cosmetically 
the same as the version 5 release.

After installing PDQ, issue the following commands in the R-console:
> library(pdq)
> demo(package="pdq")

and a list of available PDQ-R models will be displayed.

These PDQ-R scripts can be executed separately and studied entirely from 
within the R environment. For an online introduction, issue the command:
> help(pdq)

To see a listing of the PDQ function calls (in the PDQ library), go to the 
bottom of the Help page in R and click on the Index link.

Too see the R source code for any of the PQQ-R models, click on the 
Code demos link at the top of the PDQ listings page.

Another useful trick, now available in PDQ-R 6, is the ability to save 
the PDQ report output, which is normally only displayed in the R-console, 
to a file. This is done by wrapping the PDQ function Report() with sink() 
function calls as follows:
> sink("myPDQrpt.txt")
> Report()
> sink()

The PDQ report output will be found in the file named myPDQrpt.txt. The 
second sink() call returns default character output to the R-console.

Please read http://www.perfdynamics.com/Tools/PDQcode.html for the 
definitive description of all the release changes.

******************* DISCLAIMER OF WARRANTY ************************
Performance Dynamics Company(SM), Neil J. Gunther, and the developers 
of PDQ, make no warranty, express or implied, that the source code 
contained in the PDQ files or in any of the attendant books is free 
from error, or is consistent with any particular standard of
merchantability, or that it will meet your requirements for a
particular application. PDQ should not be relied upon for solving a
problem whose correct solution could result in injury to a person or
loss of property. The author disclaims all liability for direct or
consequential damages resulting from your use of this source code.
====================================================================

This software is intended to accompany the following books:

 "Analyzing Computer System Performance Using Perl::PDQ" (PPDQ)
 by Neil J. Gunther, 
 2nd Edition
 Springer-Verlag, 2011
 ISBN: 3642225829
 http://www.amazon.com/Analyzing-Computer-System-Performance-Perl/dp/3642225829
 
 The 1st edition was published in 2005.
 http://www.amazon.com/Analyzing-Computer-Systems-Performance-Perl/dp/3540208658

 PDQ models for the PPDQ book are located in the directory
 ../examples/ppdq_2005/
 See the table in the Appendix entitled "PDQ Scripts" to find the corresponding 
 PDQ model name in the relevant book edition.


 "The Practical Performance Analyst" (PPA)
 by Neil J. Gunther
 McGraw-Hill Companies (1998) ISBN: 0-079-12946-3 (First edition)
 iUniverse Press Inc., (2000) ISBN: 0-595-12674-X (Reprint edition)
 
 PDQ models (in C code) for the PPA book are located in
 ../examples/ppa-1998/

 "Guerrilla Capacity Planning" (GCAP)
 by Neil J. Gunther, 
 Springer-Verlag, 2007
 ISBN: 3540261389

 The accompanying PDQ models for the GCAP book are located in the directory
 ../examples/gcap_2007/

Various and sundry PDQ models can also be found in
../examples/misc/ 

A complete synopsis of the PDQ functions in Perl can be found in Chapter 6 
of the PPDQ book.


====================================================================

Top-level directories
---------------------
COPYING*	- the MIT/X11 license that PDQ is released under
Getversion*	- Script to report version of PDQ
Makeall*	- Used to install PDQ (see next section of this README) 
Makefile*
R/ 			- R support
README*		- This file
bin/		- Java support
examples/	- PDQ models discussed in the above-mentioned books  
java/		- Stand alone PDQ v4.2 in Eclipse-based Java
lib/		- PDQ library source code in C 
pdq.i		- configuration file for generating SWIG binding code
perl5/		- Perl5 support 
php/		- Stand alone PDQ v4.2 in PHP (*untested and deprecated*)
python/		- Python support 
tools/		- Miscellaneous translators



Examples directory
------------------
Big Book Store/	- PDQ circuit of a bookstore with separate browsing and buying facilities
Linux Magazine/	- PDQ models for Linux Magazine article "Streeeeeeetch!" (2007)
Makefile		- Make all PDQ models in the sub-directories
MultiServer/	- Test cases based on examples in Gross and Harris (Wiley 1998)
Passport/		- Uses NumPy import to PyDQ to solve traffic equations directly
gcap_2007/		- Contains Perl script PDQ models for GCAP book (2007) 
misc/			- Odds and ends (see next section of this README) 
ppa_1998/		- Contains PDQ models in C-code for PPA book (1998/2000)
ppdq_2005/		- Contains Perl script PDQ models for PPDQ book (2005)


Misc directory
--------------
These PDQ models were developed independently of the books mentioned above.

diskoptim.pl*	- Optimize response time for I/Os going to a fast & slow disk 
jackpdq.py*		- Jackson network problem in PDQ
jacksim.py*		- Corresponding Jackson network in SimPy simulator code
threadapp.pl*	- Threaded application model
floggit.py*		- M/M/1 queue model in PyDQ
spamcan.pl*		- Model of email spam-filters running on a 4-way SMP

====================================================================

Installing the Perl PDQ Module
--------------------------------
The Perl interpreter, needed to run PDQ, is intrinsic to a wide 
variety of platforms. In general, it is already installed on UNIX or Linux 
platforms, so the following sequence of commands can be used to install the 
PDQ perl module:

The PERL module is built and installed by the Makeall command which will
be run by doing a 'make' in the top level directory.

It may be built manually by as follows:

 Change to the pdq subdirectory: cd pdq and locate the directory perl5/
 Change to that directory: cd perl5
 Run the setup script: ./setup.sh
 Go back up to the pdq directory: cd ..
 You should be able to run the code examples provided.

More explicit instructions can be found at the web site www.perfdynamics.com.
You should also check that web site for any changes regarding future releases 
of PDQ. You are now ready to execute any of the Perl scripts listed in
in the tables at the back of the book. A similar procedure can
be applied to the installation of almost any Perl module, including those
from CPAN (www.cpan.org).

For other Perl environments, such as MacPerl (MacOS), ModPerl (Apache),
Active Perl (Microsoft Windows), you should consult the appropriate
documentation for the correct installation procedure.
Installation notes for ActiveState Perl have been provided by Tom Becker 
and can be read from the PDQ download page:
http://www.perfdynamics.com/Tools/PDQcode.html

A brief tutorial on performance modeling can be found at
http://www.perfdynamics.com/Tools/PDQ.html

Visit the blog http://perfdynamics.blogspot.com/ for additional
information on the book and other performance-related resources.


=======================================================================

Installation Gotchas
--------------------

The following items are typical of the installation problems that can prevent
Perl PDQ models from executing.

- Line termination in ASCII files. 
 Check CR/LF conventions in your environment.

- Permissions problems
 If you don't have root privileges, you will need to install the
 PERL module to a lib/ directory that is local to you.

- Pathing problems
 The Perl interpreter has to be able to find the pdq.pm module.
 The typical error message for this begins 
 "Can't locate pdq.pm in @INC (@INC contains: ...."
 
 To facilitate finding it on my MacOS X G4, for example, I had to export the
 UNIX environment variable PERL5LIB using the shell command:
 setenv PERL5LIB /Users/njg///lib/perl5/site_perl/5.8.6/darwin-.../
 You should then include this env var in your .cshrc or whatever login profile
 you use.
 
 Check this variable using the command:
 echo $PERL5LIB

*** See the README file in the Perl5/ directory for more details ***


Installing Python PDQ
---------------------

a) Run Makeall at the top-level directory (standard build).

 $ make

 or

 $ Makeall

b) Build manually as follows:

 $ cd python
 $ make
 $ ./test.py # to test


NOTES:
1) If using standard system installs of Perl and Python on UNIX
 and Linux systems, you will need superuser (root) privileges
 to install the Perl and Python modules into the system
 default locations.

2) See README in perl5 directory for what to do if you do
 not have root access and cannot install PERL and Python
 into normal system wide locations.

3) See README in perl5 directory if installing in Cygwin on
 Windows Vista
 
 
====================================================================

Problems compiling on Solaris and other UNIX flavors

PDQ has been compiled without problems on many UNIX and UNIX-like platforms
with GNU development tools: Linux, MacOSX, OpenSolaris, and Cygwin. Some
Solaris users have reported difficulty compiling. There is a
Makefile.solaris file that you could try using should you be unable to
compile with the regular Makefile. Try the following steps:
lib: make -f Makefile.solaris
perl5: setup.sh
python: make
R:  R CMD INSTALL pdq