README

# MiniVend V3.11
# 
# Copyright 1996-1998 by Michael J. Heins <mikeh@minivend.com>
#
# Based on Vend 0.2
# Copyright 1995 by Andrew M. Wilcox
#
# Portions from Vend 0.3
# Copyright 1995,1996 by Andrew M. Wilcox
#
# 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; either
# version 2 of the License, or (at your option) any later
# version. 
#
# This program 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 General Public License for more details.
#
# You should have received a copy of the GNU General Public
# License along with this program; if not, write to the Free
# Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
# USA.

Welcome to MiniVend, originally based on Vend.  This program is
completely unsupported, without warranty of any kind. The author is
interested in problems, suggestions, or comments, but does not have time
to offer free individual support in most cases. See the MiniVend website at
http://www.minivend.com/minivend/ for more information.

   IMPORTANT NOTE:  MiniVend 3.11 requires Perl 5.004 or higher.
   (It will probably work with 5.003 on some UNIX systems and *may*
   work with Perl 5.002 -- IF you comment out any lines which 
   contain "use locale;". Neither are supported.)

The information you need is in the following files:

    README     Copyright info, roadmap to installation
               and pointers to support system
    
    Copying    Your MiniVend license -- please read.

    INSTALL    Installation instructions

    README.OS  OS-specific information, if any

    doc/       The MiniVend documentation.

    WHATSNEW   Change information for all versions in this
               version family.

    MANIFEST   List of all core distribution files.
    
Major files/directories in the distribution:

    configure
    configure.bat
    Makefile.PL The installation scripts. Try typing "./configure"
                or "configure" to install.

    dist/       The distribution files, exclusive of library
                modules. Includes:

                minivend.cfg.dist   Distribution minivend.cfg
                simple/             The simple demo application.
                bin/                Executables including scripts
                src/                C and Perl code for CGI links

    doc/        The documentation.

    lib/        The library modules needed to run MiniVend.
                 
    win/        Windows-specific files
            
--------------------------------------------------------------

                        M I N I V E N D
                                       
   MiniVend is a full-featured electronic catalog system (commonly known
   as a shopping cart) with online ordering capability. It is designed to
   provide an interface complete with SSL security and full database
   support.
   
   MiniVend is freely-redistributable under the GNU General Public
   License -- you can download it via FTP.

    MiniVend 3.0 Features

       * Users maintain a "shopping cart" for ordered items
       * Multiple independent or shared catalogs allow one server
         to run many storefronts or a "mall"
       * SSL support means secure and practical credit card ordering
       * PGP support for secure off-site mailing of orders
       * Catalogs can be of almost unlimited size with excellent
         performance
       * Multi-server mode for very high capacity on systems with
         sufficient memory
       * Cookie support allows browsers to leave catalog and come
         back without losing session state
       * Complete addressable database support with virtually
         unlimited rows and columns
       * Complete SQL support including ODBC
       * Many, many, other features

    Powerful search capability

       * One-click scan and search -- build a whole search in a single HREF
       * Versatile built-in text search
       * Complete Glimpse interface
       * Fast binary search
       * Range searching, numeric and alphanumeric
       * Search sorting with reverse, numeric and case-insensitive options
       * Independent field search selection and return
       * Search any file, build results from any database

    Complete control of appearance

       * Full frames support
       * Catalog pages automatically selected -- either built
         "on the fly" from the database or pre-made for popular items
       * The on-the-fly page is selectable from the database
       * Embedded Perl and conditional HTML allow complex and
         flexible catalog pages to be completely built from
         the database

    Flexible Ordering Process

        * Multi-level order screens with configurable field
          verification
        * Multiple shopping carts per catalog, allows both buy
          and sell operations
        * Shipping calculation, mixed modes, with UPS table lookup
        * Sales tax calculation, with fully independent non-taxable
          item and taxed shipping
        * PGP encryption of credit card information or
          the entire emailed order
        * Fully-configurable discounts with coupons or
          across-the-board discounts
        * Fully-configurable quantity pricing
        * Fully-configurable item price adjustments
        * Sophisticated back end order entry capability including CyberCash(R)
        * Full client-side imagemap support, including frame targets and form
          submits
        * Fully configurable order reports and receipts

    Easy Administration

        * Automated installation and configuration
        * Runs under Perl 5.004, Windows, and almost any UNIX
        * Designed to be secure
        * Offline database builds
        * Static page build option for high performance
        * Works well with all browsers


-------------------------------------------------------------------

                         D E M O

There is a simple demo application included. 

To install the demo, go to the MiniVend installation directory
and run:

    bin/makecat simple

Follow the prompts and after restarting the MiniVend server you
should be able to access the demo catalogs.

-------------------------------------------------------------------

                      A V A I L A B I L I T Y
                              A N D
                     C O M P A T I B I L I T Y

MiniVend has been well-tested on Solaris 2, SunOS, Linux, HP-UX,
BSDI, FreeBSD, and OSF/Alpha. It also reportedly runs on SCO,
AIX, and other Unix ports.  It should work on any UNIX or Win32
OS with Perl 5.004 or higher. It may run with Perl 5.003 or
Perl 5.002, but the author disavows all responsibility for
the results.

IMPORTANT NOTE FOR WINDOWS: MiniVend will NOT run with the
ActiveState port, otherwise known as 5.003 build 1XX. It
REQUIRES, repeat REQUIRES, the standard version Perl 5.004. See
http://www.perl.com/ for information on how to obtain it.

Windows does not support fork(), so the server runs in the
foreground. You need the DB_File module for best results,
and that is not included in the standard distribution. You can
get it at http://www.perl.com/CPAN-local (or any CPAN archive)
in the ports/win32/Standard/x86/ directory.

BSDI and FreeBSD are known to have problems with Perl socket
code, which MiniVend relies heavily upon. You will probably
need to run in INET/TLINK mode instead of UNIX/VLINK mode.

-------------------------------------------------------------

                      I N S T A L L A T I O N

WINDOWS INSTALLATION
--------------------

    Obtain the self-extracting executable minivend-3.11.exe
    and double-click on it. You MUST already have Perl 5.004
    INSTALLED and in your PATH.

    Alternatively, you can unzip the file yourself and run
    "setup".

UNIX INSTALLATION
------------------
Here is the short version:

    gzip -dc minivend-3.11.tar.gz | tar xvf -
    cd minivend-3.11
    ./configure

More information is in the file INSTALL.

-- WHEN IN DOUBT, RE-START THE SERVER.  It won't take but a few
   seconds, and changes in configurable options don't take effect
   until it is done. You may even change a page and not see the
   effect until the server is restarted.

-------------------------------------------------------------

                     D O C U M E N T A T I O N

The documentation is in 2 files in the doc/ subdirectory of
the main MiniVend directory:

       toc.html       Table of contents
       minivend.html  Main documentation file

These files will be copied to the same HTML directory as
the simple demo gateway files -- they would normally
be referenced as:

           http:/www.yourserver.com/simple/toc.html

-------------------------------------------------------------

                    K N O W N   P R O B L E M S

RedHat Linux 5.0:
        RedHat Linux 5.0 has a bad Perl distribution that causes
        problems with POSIX. The real solution is to obtain the
        latest.tar.gz file from CPAN and build a new Perl. Here
        is the script to do that once you have obtained the 
        latest.tar.gz file:

            tar xzf latest.tar.gz
            cd perl5.004*
            perl -pi.dist -e \
                "s:/ bsd / /:/ net / /' | sed -e 's/ bsd / c g /:; \
                s/^#(POSIX_cflags)/POSIX_cflags/" \
                hints/linux.sh
            ./Configure -des && make test

        That should get you a Perl which passes make test
        one hundred percent and that works with MiniVend and
        other programs which use the POSIX library. After
        you have verified the "make test" passes fully
        you should of course su to root and "make install".

        This may soon be corrected by the Perl porters or by
        RedHat, so bear in mind this is time-sensitive. The above
        works well as of Jun. 3, 1998.

IRIX, Solaris, Digital UNIX:
       The server may not terminate immediately,
       as the select() call blocks signals. It
       will stop at the next request, or at the
       end of the occasional houskeeping
       cycle, set by the directive HouseKeeping in
       minivend.cfg. Set to less than 10 to achieve
       decent response.

BSDI, FreeBSD:
       The BSDI library code is not safely re-entrant
       when used in combination with signals, so no
       signals are sent during server usage.  This is
       transparent to the user.

       MiniVend may not as of this writing work with
       BSDI 3.0 in UNIX mode, so you should use the INET
       mode and the tlink program. This is the catalog
       configurator default.

       If the kernel parameter CHILD_MAX is not configured
       above the default of 40, expect problems. Same with
       SO_MAXCONN and some other kernel parameters. 

Solaris:
       If you are trying to run with Perl 5.003, which is
       NOT recommended, you must use the File::Lock
       module -- flock() emulation in Perl 5.003 does not
       work properly, and fcntl() locking must be used.
       This version of MiniVend includes File::Lock,
       and attempts to install it.

       Solaris 2.4 has problems with UNIX-domain sockets
       and you can expect problems.  Bottom line is that
       I will not support Solaris releases before 2.5, nor
       Perl before 5.004.

       You may not use OrderCounter when running Perl
       5.003 and Solaris.

       If you have Perl 5.004 you can disregard File::Lock.

       It is STRONGLY RECOMMENDED that you update to Perl 5.004
       when running on Solaris.

Windows:
       This is a new port, and just a few things don't work the
       same as UNIX. See the README-win.txt file for more information.

---------------------------------------------------------------------

I, the author, am very interested in learning your problems with
MiniVend, and am interested in clarifying the documentation for
future improvements.  I am not much interested in BEING your
documentation, though, unless you pay well and promptly. Please
send kudos, comments, questions, and complaints to:

       mikeh@minivend.com

Note that I receive thousands of emailed questions per year and cannot
answer them all. The more research you do on your own the more likely
I am to respond. Helpful suggestions and real bug reports are almost
always acknowledged.

Good luck with MiniVend!