gitpan / db2-admin Goto Github PK

=head1 INTRODUCTION

Please see the INSTALLATION section below for build instructions.

This module provides access to the administrative functions of DB2 for
Linux, Unix and Windows.  The administrative functions are those
functions not accessible through SQL, which normally require use of
the DB2 command line processor (the "db2" command).  IBM has been
making some of these available through administrative view and the
SYSPROC.ADMIN_CMD stored procedure.

Using these functions from perl is faster and can provide more
detailed results than the command-line processor.  For example, when
reading configuration parameters, the administrative API will not just
tell you which values are set to "automatic", but also which options
support the "automatic" setting.  In a similar manner, when loading
data into a DPF database, the API returns detailed information for
each node and agent, allowing far more fine-grained error handling.

The DB2 administrative function module provides the following
functionality:

=over

=item *

Monitoring: get snapshot information and read event monitor files

=item *

Bulk data transfer: export, import, load

=item *

Configuration: get/set instance and database level configuration parameters

=item *

Directory: read or modify the database, node and DCS directory

=item *

Utilities: force applications, runstats, rebind, list history, list utilities

=back

=head1 PLATFORMS

This package has been known to build with the following combinations
of software.  Please report problems and additional platform / DB2
release combinations to the maintainer.

  Operating System        DB2 Version        Perl Version
  ================        ===========        ============
  AIX (unknown release)	  8.2		     5.8
  Red Hat EL 3 (x86)      8.2                5.8
  Red Hat EL 3 (x86)      9.1                5.8
  Red Hat EL 3 (x86)      9.5                5.8
  Red Hat EL 4 (x86_64)   8.2                5.8
  Red Hat EL 4 (x86_64)   9.1                5.8
  Red Hat EL 4 (x86_64)   9.5                5.8
  Red Hat EL 4 (x86_64)   9.5                5.10
  Red Hat EL 5 (x86_64)   9.7                5.8
  Solaris 10 (SPARC)      9.1                5.8
  Solaris 10 (SPARC)      9.5                5.8
  Windows Vista Business  9.5                5.8

=head1 INSTALLATION

This module can only be installed if you have the C compiler used to
build perl itself, plus a version of DB2 with the header files
installed (the developer's edition).  You generally cannot build this
module if you've downloaded a pre-compiled version of perl (but see
Windows / ActiveState instructions in the next section).

You need to run the test portions under a userid with DB2
system administration privileges.

Make sure the pre-requisite module Params::Validate has been
installed.

As a first step, set the environment variable DB2_VERSION to the DB2
release you have installed.  For example, if you're running DB2 Viper
(V9.1), do:

  export DB2_VERSION=V9.1

If you're not on Linux, Solaris or AIX (or if you've installed DB2 in
a different location than the Makefile.PL file expects), you also have
to specify the path where the DB2 files can be found, for example:

  export DB2_PREFIX=/opt/IBM/db2/V9.1

The common environment variables DBAPTH, DB2DIR and DB2_HOME can be
used as well.

Please report the default prefix for platforms that the author doesn't
have access to (i.e. not Linux, Solaris), so the module can support
them in the future.

Then do:

  perl Makefile.PL
  make

The test step requires you to create a SAMPLE database with a set of
tables used for the export, import and load tests.  The supplied
"create_test_db" script will create the SAMPLE database using the
IBM-supplied "db2sampl" utility and create some additional tables.
Make sure you have sourced the DB2 environment before running the
script.

  create_test_db
  make test

You can run the tests against any other database you want, but please
make sure you update the CONFIG file before running the test script.

Once the test completes, you can install the module with:

  make install

=head1 INSTALLATION - WINDOWS

Mike O'Reilly conttibuted the following notes to build the DB2::Admin
module on Windows.

The ActiveState Perl 5.8.8 for x64 is available for download built
with Microsoft Visual C v6 with the freely available compiler in the
"Microsoft Windows 2003 Server SP1 Platform SDK".  It is necessary to
use the same compiler to build any Perl modules that use the C
language. For VS2005 and VS3008 modules do not bind against MSVCRT.DLL
(but instead use MSVCR90.DLL or MSVCR71.DLL etc). 

The filename (on FTP search) that contains the correct compiler is
"5.2.3790.2075.51.PlatformSDK_Svr2003R2_rtm.img" (aka PSDK). It may
not be available on Microsoft websites, but is available elsewhere. It
is not possible to build modules with Visual-Studio-2005 or
Visual-Studio-2008 and get them to work with the pre-built ActiveState
Per 5.8.x (unless you also rebuild perl itself from sources with the
same toolkit, something I did not attempt).

When DB2 is up and running (install as 'Administrator', then add
target users to the DB2ADMNS or DB2USERS groups as appropriate), it is
necessary to open a DB2CMD window , execute the PSDK "setenv /XP64
/X64 /RETAIL" in that window, and perform the build in that
window. Then I ran the following sequence of steps.

  set DB2_VERSION=V9.5
  perl parse_constants.pl
  build/test/install Pod::Simple
  build/test/install Pod::Escapes
  build/test/install Test::Pod
  modify CONFIG appropriately
  perl create_test_db
  perl makefile.pl
  nmake
  nmake test

=head1 RELEASE NOTES

The CHANGES.html file has a complete, historical list of all
user-visible (and some invisible) changes to this code.

=head1 AUTHORS

The code is currently maintained and supported by:

  Hildo Biersma <[email protected]>

=cut

#
# $Id: README,v 165.1 2009/04/22 14:05:35 biersma Exp $
# 
# Copyright (c) 2007-2009, Morgan Stanley & Co. Incorporated
# See ..../COPYING for terms of distribution.
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation;
# version 2.1 of the License.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser
# General Public License for more details.
# 
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
# 02110-1301  USA
#
# THE FOLLOWING DISCLAIMER APPLIES TO ALL SOFTWARE CODE AND OTHER
# MATERIALS CONTRIBUTED IN CONNECTION WITH THIS DB2 ADMINISTRATIVE API
# LIBRARY:
#
# THIS SOFTWARE IS LICENSED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
# FOR A PARTICULAR PURPOSE AND ANY WARRANTY OF NON-INFRINGEMENT, ARE
# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THIS
# SOFTWARE MAY BE REDISTRIBUTED TO OTHERS ONLY BY EFFECTIVELY USING
# THIS OR ANOTHER EQUIVALENT DISCLAIMER AS WELL AS ANY OTHER LICENSE
# TERMS THAT MAY APPLY.