PBS version 0.31
=======================

This is a perl binding for the Portable Batch System client library (as from
OpenPBS or Torque).  This allows you to stat the server, nodes, or jobs, submit
jobs, alter jobs, etc.  Demo code and a complete Curses-based interactive
monitoring program called 'pbstop', are included.

Specifically, the ifl, rpp, and rm APIs are implemented here.

The latest version of this software will be available at
http://www-rcf.usc.edu/~garrick/perl-PBS/

WARNING:  This software is emerging from "proof of concept" to alpha and should
be trusted appropriately.  It has only been tested with Torque 1.0.1, 1.1.0,
and 1.2.0 on Redhat Enterprise 3 on x86, x86_64 and ia64.  It _should_ work
with OpenPBS, but success and failure reports would be appreciated.  It has
been noticed that perl-PBS built against Torque 1.0.1 does not work correctly
with Torque 1.1.0, but the reverse works fine.

PBSPro is currently known NOT to work.  Patches are accepted!


DEPENDENCIES

This module requires these other modules and libraries:

   openpbs or torque client libraries and programs
   Curses perl modules from CPAN (to use pbstop)
   optionally, swig >= 1.3.19 (if you want/need to rebuild PBS_wrap.c)
   optionally, cpan2rpm (if want to build an rpm)

If you can't get the Curses module to build, be sure you have the brand new
1.07 version from Bryan Henderson on CPAN.

cpan2rpm seems to have several bugs right now.  Until cpan2rpm is fixed
upstream, this package is distributing a copy of it.  The Makefile.PL is
written to use it instead of a system copy.

swig 1.3.21 is known not to work.  If you need to generate a new PBS_wrap.c
(and you probably don't), consider downgrading to 1.3.19 or check for a newer
version.  1.1.x versions will definitly not work with pbs_ifl.h


INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

An RPM file can easily be generated with 'make rpm'.

Optionally, set INSTALLSCRIPT to wherever you want 'pbstop' to be installed.

If the first step fails to find pbs_ifl.h or libpbs.a (or it finds ones that
you don't want to use), export PBS_INCLUDE and PBS_LIB with the directories
that contain those files and try it again.

If there are any problems building PBS_wrap.c, then make sure swig 1.3.19
is installed and touch PBS.i.  This will force the generation of a new
PBS_wrap.c.  Note, 1.3.21 is known not to work.

On x86_64 and ia64 RedHat Enterprise 3 systems, it was necessary to rebuild
torque with -fPIC.  Simply export CFLAGS="-g -O2 -pipe -fPIC" before
configuring torque.  If this effects you, consider asking the SuperCluster
people to do this by default :)

Your PBS implementation will probably need to be built with the same compiler
as your perl build.  For example, perl can't load the extension if it was built
with the native Solaris compiler and torque was built with gcc.  Perl can tell
you what it was built with: perl -MConfig -e 'print "$Config{cc}\n"'

Makefile.PL uses ExtUtils::MakeMaker to create the Makefile, I recommend
reading 'perldoc ExtUtils::MakeMaker' for a wealth of valuable options.


PBSTOP

This package contains the 'pbstop' interactive monitoring program.  It is a
fully-functional and highly useful way to monitor your cluster.  After
installing, 'man pbstop' and 'pbstop -h' to get started.


DEMO CODE

There are currently three demo programs in the demos/ directory.  They are simple
scripts to demonstrate the data structures used by the module.  To run them,
simply type the following commands after building the module:

   perl demos/dumpmom
   perl demos/pbsnodes-a
   perl demos/qstat-f

Those demo programs optionally take one argument, nodenames or a jobid
respectively,  Set the PBS_DEFAULT environmental variable to change the server
hostname.  Note that the output of those programs is almost identical to the
"real" versions distributed with OpenPBS and Torque (qstat-f just needs to fold
the longer output lines).  'dumpmom' contacts the RM on the given node and
prints out some interesting information (this might need to be run as root).


GENERATED FILES

PBS_wrap.c is generated by swig from PBS.i.  Any modifications to PBS.i will
cause PBS_wrap.c to be regenerated.  Do not use the PBS.pm generated by swig,
use or modify the copy in lib/.  It is not required to rebuild PBS_wrap.c to
build this module.

perl-PBS.spec is generated by cpan2rpm.  If you add any files, or change the
version number, 'make clean' and 'make spec'  will cause a new spec file to be
generated.  Please look at Makefile.PL before trying to generate a specfile
manually.

If you change the version number in VERSION, be sure to also change it in
t/01_PBS.t and the top of this file.


SUBPACKAGES

The PBS::rm and PBS::rpp subpackages are fakes.  All they do is import the
correct symbols from the main PBS package.  Their real purpose is convenient
packaging of documentation.  That said, I think it will also help
user-programmers to better compartmentalize their programs.


COPYRIGHT AND LICENSE

Copyright (C) 2004, 2005, 2006 Garrick Staples

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation or under the same terms as perl itself.

