# MiniVend V3.00 # # Copyright 1996,1997 by Michael J. Heins # # Largely 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, based on Vend, Andrew Wilcox's fine shopping cart program. This program is completely unsupported, without warranty of any kind -- but that doesn't mean the author is not interested in problems, suggestions, or comments. Please feel free to send them to Mike Heins, . ------------------------------------------------------------- W H A T ' S N E W MiniVend 3.00 is greatly changed from MiniVend 2.03, though catalogs should be almost completely compatible. The exceptions are one or two pricing and shipping database changes. In both cases, there is available backward compatibility. Changes include: * A powerful static page building capability is in place. This allows completely automated generation of static HTML pages based on MiniVend databases. Use it to build static category lists and product pages that will load quickly without the necessity of MiniVend parsing them. * Dynamic page parsing speed is increased by about 30% when using the standard syntax. * Multiple product databases allow the breakout of product lines, new-used product separation, multi-vendor order routing, and more. The database an item is ordered from is kept with the item in the shopping cart, so items ordered with the same part number from different databases will not overwrite each other. * Database tables are now writeable. Atomic incrementation is supported, which means that reliable inventory counts can be kept. Form-based database updates are expanded to encompass all databases, not just mSQL. * Transactions can be logged to an arbitrary file in an arbitrary format with [tag log file]data[/tag]. * Databases can be exported to an ASCII file with the [tag export ...] [/tag] construct. * Shipping is much improved, with built-in subroutine calls, error messages for out of bounds condtions, drop-in UPS zone files, configurable handling charges, UPS cost rounding, and more regular syntax. * Item attribute selection greatly improved, with automated building of the item attribute selection. Item attributes can easily be specified at the time of order. * Item attributes can cause price adjustments on either an item basis or attribute basis. * Uses Data::Dumper's C-based uneval code when available, improving session storage speed. * Database tables are only actually opened when referenced, improving speed greatly on systems that have a large number of tables in the database. * Experimental DBI/DBD example interface provided, which will allow attachment of supported SQL databases like Solid, Oracle, or Sybase. THIS IS EARLY ALPHA SOFTWARE. Use only on an experimental basis, never with live data. * Search engine has improved coordinated matching, with full field-independent case-sensitivity, substring matching, and negation. * Search speed greatly improved when doing complex field-coordinated searches. * The FullUrl directive allows different virtual hosts to have link programs with the same name, i.e. all named /cgi-bin/shop. * A new (and still experimental) page syntax allows more regular parsing of tags, removing some of the interpolation-order anomalies inherent in the old-style tags. It can be invoked on individual pages with the [new] tag. * Search cacheing is much improved, and searches can be pre-built when using the static page build capability. * Pages can be cached, which especially improves performance of large parsed pages. Static build is preferred to cache, but with large databases it is not practical to build every item in advance. * Supports Perl 5.004 transparently, making runtime changes to affected modules. * Better security with the NoAbsolute, AdminPage, .access, and AdminDatabase tags. * Improved handling of cookies, with savable sessions and dynamic expire times. * Mailed orders may have MIME attachements. Though the author loathes routinely-used MIME, it has value as a way to attach an encrypted credit card number for easy processing by an order entry workstation. * Search sorting bugs fixed. * New $Safe{'cgi'}->{form_value} access in embedded Perl allows complex conditional search or order routines to be more intelligent with regard to user input. * New FormIgnore directive allows certain variables to be expunged from the user session. * Many other minor bug fixes, improvements, and changes. ------------------------------------------------------------- I N S T A L L A T I O N We IMPLORE you to read all of the verbiage below. We know how most of us are, so we put the install procedure up here, but if you have problems please read all of this file, PLUS the MiniVend documentation in doc/minivend.html. Also, please check out the official MiniVend FAQ at http://www.iac.net/~mikeh/faq/ before you call for help. And send your system, Perl, and Minivend information, VERSIONS AND ALL! IMPORTANT NOTE: If you don't give evidence of having read and heeded the above heartfelt plea, your email may well be ignored. Caveat Emptor. Here is the short version: gzip -d mvend300.tar.gz tar xf mvend300.tar cd mvend300 ./configure su bin/makecat sample bin/makecat simple bin/start With comments: # Unzip and untar the file -- if you have GNU tar, you can combine # the first two steps with 'tar xzf mvend300.tar.gz' gzip -d mvend300.tar.gz tar xf mvend300.tar # Change directory to the one that was created -- this is a change # from MiniVend 1.0x. # cd mvend300 # If you have trouble with picking up the wrong Perl version, # try '/dir/where/perl/is/perl configure.pl /dir/where/perl/is/perl'. # # If you aren't already the user ID of the user who will run the # minivend server, you might want to 'su' to that user before # running this step. # # This step will set the MiniVend directory and Perl location, # and build the small dispatch program. # # If in doubt, the defaults are probably OK. # # If you are upgrading from a previous version, put the # former MiniVend root directory in when prompted for # VendRoot. # ./configure #### At this point, you can follow the instructions that the configure program generates. If you installed MiniVend in another directory besides the current one, you will have to change directories to that directory before continuing. #### # Become superuser if you are an ISP or other organization that # will be running multiple catalogs. If you don't have root access, # don't worry about it. # su # Make the demo catalogs -- either one or both. On the first # one, you will be prompted for some initial parameters, then # asked to re-run. This is OK. # bin/makecat sample # Make the other catalog. The extension .cat will be # put on the catalog configuration file that is created. # # If you want to make it with a different name, just use: # # bin/makecat yourname # bin/makecat simple # Start the MiniVend server # bin/start That should be it. If you have problems, please do what is asked above, and pretty please reference the web site. And -- 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 3 files in the doc/ subdirectory of the main MiniVend directory: toc.html Table of contents minivend.html Main documentation file tags.html Complete MiniVend tag reference These files will be copied to the same HTML directory as the sample and simple demo gateway files -- they would normally be referenced as: http:/www.yourserver.com/sample/toc.html ------------------------------------------------------------- K N O W N P R O B L E M S 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. If you want it to stop more quickly than the default (up to) 60 seconds, either make a page request or set HouseKeeping to a lower number. IRIX: The UNIX-domain socket version may not work on some operating system versions -- patch 596 is recommended. BSDI, FreeBSD: The BSD socket code does not appear to be reliable when combined with Perl, and you may observe server freezes as a result. MiniVend will not as of this writing even work with BSDI 3.0 -- nor will Perl socket code of any kind, for that matter. BSD is the only known OS with this problem -- it is recommended that you use another for MiniVend if at all possible. 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. In short, if you are using BSD you can expect problems with MiniVend. Infuriating, hard-to-trace ones. Solaris: 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. If you have Perl 5.004, you may be able to disregard File::Lock -- MiniVend will try if appropriage. If you are using GCC on Solaris, you may have to compile manually and pass -DSVR4 -lsocket on the compile command line, particularly if you have not disabled the script that is called 'cc' in many Sun distributions. If the vlink compile fails, run this series of commands *immediately* after running the configure script: cd src gcc -DSVR4 -lsocket -o vlink vlink.c cd .. If vlink compiles without error, you can make the catalogs and run normally. ------------------------------------------------------------- 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. IMPORTANT NOTE: MiniVend requires Perl 5.003 or higher and GDBM or DB_File databases. The program is no longer compatible with NDBM or Perl 5.001. It *may* work with Perl 5.002, but it is no longer supported. MiniVend 3.00 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 * mSQL support includes form-based inserts and updates * Many, many, other features Powerful search capability * Fast binary search * One-click scan and search -- build a whole search in a single HREF * Complete Glimpse interface * 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 * Full client-side imagemap support, including frame targets and form submits * Fully configurable order reports Easy Administration * Automated installation and configuration * Runs under Perl 5 and almost any UNIX * Designed to be secure * Built-in online help capability * Offline database builds * Static page build option for high performance * Works well with all browsers Andrew Wilcox wrote Vend, the copylefted shopping cart software. MiniVend is based on Vend V0.2, but enhanced considerably, adding support for frames, powerful searching, remote administration, superfast server mode, conditional HTML, user-customizable help and displays, and much more. This version of MiniVend includes an automatic configuration and installation utility, and continues to be free under the GNU copyleft. To learn more about MiniVend, see the HTML documentation, visit the offical MiniVend site, or download it. ------------------------------------------------------------------- D E M O There are two demos supplied. The 'sample' demo demonstrates frames on MiniVend, the 'simple' demo does not use frames. To install the demos, go to the MiniVend installation directory and run: bin/makecat simple bin/makecat sample Follow the prompts and after restarting the MiniVend server you should be able to access the new 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, and OSF/Alpha. It should work on any UNIX with Perl 5.003 or higher. BSDI and FreeBSD are known to have problems with Perl socket code, which MiniVend relies heavily upon. You can expect some reliability problems with those operating systems. DB_File is the fastest DBM for use with MiniVend -- GDBM is the easiest to build if you must install it yourself. For Solaris 2, you may need the File::Lock module, which is now included with MiniVend (installation is attempted). Please let the author know if you have successfully run MiniVend on any additional platforms -- patches would be appreciated. ------------------------------------------------------------------- S E T T I N G U P Y O U R C A T A L O G Setting up a MiniVend catalog can be quite complex, and that is why the documentation and demos were provided. They should be sufficient to get you started. Many hours have been spent in documenting the features of MiniVend, and thoughtful users should almost always find their answers there. Key things that people sometimes don't understand: -- The actual pages of the catalog are NOT in HTML document space. They are in the catalog directory of the catalog that is in question. -- The highly interpolative nature of MiniVend and HTML tags means that order is often important. -- The first thing to do in setting up a custom MiniVend catalog is to define the database. Everything with MiniVend stems from the products database -- many of the custom features depend on the shipping, salestax, accessories, pricing, and other databases. Determine your data set first. -- The demo pages are there to be played with. With MiniVend 3.00, you can't stop the system simply by changing a page. -- Many of the configurable features of MiniVend are determined by the directives in catalog.cfg (or minivend.cfg in a standalone catalog). -- WHEN IN DOUBT, RE-CONFIGURE THE CATALOG. It won't take but a few seconds, and changes to many of the configurable options don't take effect until it is done. The author is very interested in learning your problems with MiniVend, and is interested in clarifying the documentation for future improvements. (He isn't much interested in BEING your documentation, though, unless you pay well and promptly.) Please send kudos, comments, questions, and complaints to: mikeh@iac.net ------------------------------------------------------------------- M I S C E L L A N E O U S O S N O T E S Recommended DBM Tested on Notes ----------------- ------------ ----------------------- Linux DB_File 1.2.x & up This is what MiniVend is developed on -- all features should work normally. FreeBSD DB_File 2.1.0, 2.1.5 Many users run MiniVend on this OS, but there are known problems with reliability. Take care. BSDI DB_File Many users run MiniVend on this OS, but there are known problems with reliability. Take care. Solaris 2 GDBM 2.4,2.5 Many users run MiniVend on this OS, no known problems once you get it going. File::Lock less of a problem, GCC problems should be caught by the configurator. SunOS 4.1.x DB_File 4.1.3 Some users run MiniVend on this OS, no known problems DEC/OSF, aka GDBM 3.0 Some users run MiniVend on Digital UNIX this OS, no known problems IRIX GDBM 5.3 Server may be difficult to stop for re-configuration. No other known problems. HP/UX ???????? 10.1 A few users, may be some trouble with vlink/tlink compilation. SCO ???????? ?????? No known users, looking for reports of compatibility AIX ???????? ?????? No known users, looking for reports of compatibility