IIUG Software Repository Files

                       The DBspaces Package
                       ====================
Author: Jacob Salomon
        jakesalomon@yahoo.com
Date:   2017-06-12

This file describes the procedure for "installing" the DBspaces package.
That word is in quotes because no actual installation procedure is needed.
In a nutshell, there are three steps required.  These will be described
after this inventory.

The files in this archive are:
- DBspaces.pm       The Perl Module with the functions and methods that all the
                    .pl files below call 
- new-dbspace.pl    Utility to create a new DBspace
- add-chunk.pl      Utility to add a chunk to a specified DBspace
- drop-chunk.pl     Utility to drop a chunk from a specified DBspace
                    (provided it is empty, of course)
- drop-dbspace.pl   Utility to drop a a specified DBspace (provided it is
                    empty, of course)
- spaces.pl         Utility to give a quick listing of all or some DBspaces in
                    the current server.  Useful for looking out for DBspace at
                    the brink. (I have actually written a utility for that
                    but not yet included it in this package.)
- dup-spaces.pl     A utility not expected to be used often; recreates onspaces
                    commands that could be used to recreate this entire server's
                    DBspaces and chunks.  Perhaps in preparation for a HDR setup
                    or for recovering a destroyed server, before attempting a
                    restore from archive.
- set-symlinks.sh   A use-once utility to create symbolic links to the .pl
                    files minus the .pl suffix.
 
These are all in the .shar file, with the usual methods ofor unpacking the
shell archive.

Now there is the documentation for the perl module and the 6 utilities.
These are in the .tar file, which you unpack with the usual tar -xvf
command, ideally in the same directory when you have "installed" (Oh, there
he goes with the quotes again ;-) the module and utilities.  Each items has
a .html and a .pdf, to be viewed with a browser or pdf reader of your choice.
These are:

- DBspaces.pod.html     and DBspaces.pod.pdf
- new-dbspace.pod.html  and new-dbspace.pod.pdf
- add-chunk.pl.pod.pdf  and add-chunk.pod.html
- drop-chunk.pod.html   and drop-chunk.pod.pdf
- drop-dbspace.pod.html and drop-dbspace.pod.pdf
- dup-spaces.pod.html   and dup-spaces.pod.pdf
- spaces.pod.html       and spaces.pod.pdf


Note: This release of DBspaces is partiall-installed. You can begin with
step #3 below:

How to install this package on your system.
-------------------------------------------

0. CD to your target directory. You do not have to be user informix (nor
   root) to do this; just have permission to write to that directory.

1. Untar (tar -xvf) the downloaded tar file, which extracts the 7 html files
   listed, their corresponding PDFs, and the .shar file outlined above,
   DBspaces.shar.01.  Obviously you have already done this untar; you are
   reading this README file.

2. Unpack the .shar file:
   $ sh DBspaces.shar.01

3. Move the .pl files (6 files) into a directory that is in your $PATH
   environment variable.

4. Move the .pm file into a directory listed in the environment variable
   $PERL5LIB.  Perl has its internal set of directories to search for
   modules but since this package was not composed with CPAN-compatibility
   in mind, perhaps you should keep this in a separate directory.

   In my personal case, I have a directory named /ifmx-work/scripts and all
   of the above scripts, as well as the Perl module (.pm file) are in that
   directory.  Furthermore, both my $PATH and $PERL5LIB environment variables 
   include /ifmx-work/scripts. 

5. Run set-symlinks.sh, the script to create the symbolic links for the .pl
   utilities to names without the .pl suffix.

Each of the Perl scripts (.pl) has its own quick help option (-h or --help) as
well as a Perl POD, which can be accessed by the perldoc command. So does
the module so you can get help on the module with:

    $ perldoc DBspaces.pm

The HTML files above were generated using the pod2html utility.

The PDFs were generated by opening each .html file with the Chrome browser
and printing to [Save to PDF].  The pod2pdf utility didn't produce nice
enough PDFs.

Note: The dup-spaces and spaces utilities to not require you to subscribe
to the naming conventions described in DBspaces.pod.pdf.  The other four,
however, will work only under those conventions.

-- Jacob Salomon