VERSION
Document version: $Id: faq.pod,v 1.3 1999/08/14 07:39:23 mike Exp mike $
This document describes MiniVend 3.14 and earlier.
MiniVend General Information
MiniVend is a freely-redistributable database retrieval and display application focused on e-commerce. In other words, a high-end and powerful shopping cart. It serves any number of catalogs via the World Wide Web, allowing users to select items for placement on their shopping list, or cart, and then buy them by filling out an order form.
MiniVend supports Secure Sockets Layer (SSL), PGP/GPG strong encryption, and online payment services to improve security. It is designed never to write an unencrypted credit card number to disk.
MiniVend has a host of features -- a partial list is available at its web home page:
http://www.minivend.com/A more complete list is in its documentation, available via links from above.
A full list can only be seen by examining its source code. 8-)
MiniVend is written and maintained by Mike Heins, but much credit goes to Andrew Wilcox, who originated Vend and created many of the underlying algorithms.
MiniVend is freely redistributable under the GNU General Public License, a copy of which should come with every MiniVend package. Basically this means that you can use it for commercial or non-commercial purposes for free, but you you have certain responsibilities if you modify and/or redistribute it. See the GNU GPL for more information.
Where can I get MiniVend? How much does it cost?
You simply download it from:
http://www.minivend.com/minivend/download.htmlYou also need Perl 5.005 or higher, available from CPAN. A list of CPAN locations is always available at
http://www.perl.com/CPAN/As to cost, MiniVend is free within the confines of the GNU General Public License. Basically, any individual or company can use MiniVend free of charge -- you have certain responsibilities if you modify your copy then redistribute it. See the GPL at:
http://www.gnu.org/copyleft/gpl.txtWhat else do I need to run MiniVend?
MiniVend is a complex system requiring the services of other complex pieces of hardware and software. While it can be very easy to install, it is not always. You must look at the ongoing environment as well as just the initial installation.
- Perl
-
First of all, you need a recent Perl. MiniVend 4 will not run on anything less than Perl 5.005.
- Perl modules
-
MiniVend will run with a stock Perl, but to use some features of MiniVend (like the MiniMate interface) you will need some extra modules. If you are on UNIX you can use the CPAN module and run:
perl -MCPAN -e 'install Bundle::Minivend'and it should install all of the modules necessary except the DBM/DBI ones.
These modules are strongly recommended:
MD5 MIME::Base64 SQL::Statement URI::URL Safe::Hole GDBM or DB_File (comes with most i386 Perls)These are definitely recommended:
Storable Bundle::LWP (contains MIME::Base64 and URI::URL)These are nice to have but are not essential:
Business::UPS (comes with MiniVend) Term::ReadLine::Perl Term::ReadKeyYou will need the DBI module if using SQL, along with the appropriate DBD module for your database.
The recommended packages for ActiveState Perl for Windows are:
MD5 MIME::Base64 LWP SQL_Statement DB_FileFUTURE: The MiniVend setup program will attempt to use
ppm.pl, the ActivePerl package manager, to install them at installation time. - Operating System
-
UNIX is best. The Windows version, while perhaps more than just a toy, is not suitable for high-volume catalog serving. This is mostly due to NT not fitting the UNIX fork() model which works so well with MiniVend.
A catalog designed on a Windows machine should just move over to a UNIX machine with no changes, so Windows might be a suitable development environment.
Mac OS is not supported. If the time comes when it starts to reasonably support normal POSIX services, then an attempt to port will be made. This is not likely, in my estimation. MiniVend does run fine on OS/X.
- Machine
-
The server should be fast and have lots of memory. A 200MHz Pentium Pro or equivalent with 128MB of RAM works well and can serve many catalogs if that is all it does.
If you are located on a machine with many hundreds of domains, as sometimes happens with low-cost hosting operations, you can expect some problems. It is difficult to maintain a stable environment with that many users.
MiniVend will run about as well as the platform beneath it. It routinely runs for months non-stop in a stable environment.
If you are having problems
MiniVend is not guaranteed to be supported in any fashion other than to make full source code of the current version available. However, the author is interested in making MiniVend as reliable and trouble-free as possible. Forward bug reports, questions and comments to the mail list, minivend-users@minivend.com.
MiniVend is powerful and correspondingly complex. If you are looking to "point-and-click" your way to a catalog, you probably should look elsewhere. While MiniMate can make administration easier, you should not expect to put up a catalog with no effort.
Do understand that any problems answered in this FAQ or the documentation will likely be ignored. Other problems will also be ignored if you don't:
mention that you have referenced appropriate items in the documentation and FAQ.
include the various version information that is appropriate.
mention what is (or is not) in the error.log files
The official MiniVend web site is:
http://www.minivend.com/The latest version of the software, this FAQ, and the documentation, are available there. Your problem may not be unique -- check the site first. There is a search feature that encompasses the documentation and FAQ; there is also a mail list and an archive for it.
The most common problem on UNIX is receiving the "We're sorry, the MiniVend server is unavailable..." message. This almost always means that permissions are not properly set up, or that the link program is not in the right location.
If your provider uses CGI-WRAP or SUEXEC, it will probably error out if you selected UNIX mode and didn't reply "Yes" to the question Do you use CGIWRAP?. To unset the setuid bit for another try, telnet in and do
chmod u-s cgi-bin/simplewhere cgi-bin is the directory that the program is located.
To reenable it:
chmod u-s cgi-bin/simpleIf that doesn't work, it usually means you are on a virtual host with limited command set.
To verify that this is the problem, try temporarily changing the permission of the MINIVEND_ROOT/etc/socket file to be read/write by setting in minivend.cfg:
SocketPerms 0666If MiniVend then works you will have to make sure the user that the VLINK program runs as matches the user who is running the MiniVend daemon. It is usual to create a special mvend or minivend user to run the daemon and the link program. This means the directory listing for your CGI-BIN should be something like:
-rwsr-xr-x 1 minivend users 6312 Dec 30 11:39 cgi-bin/simpleand for the socket file it should be:
srw------- 1 minivend users 0 Dec 30 11:41 etc/socketSee the next section for troubles with running MiniVend on ISP sites.
Beyond that, if you are unable to get MiniVend installed you should check to see if you can run any CGI program from the path it is trying to use. The next most common problem is the user giving the wrong information to makecat.
MiniVend is intended to work on Perl Version 5.005 and higher, but the author does not have the resources (read time) to regression test all versions with the different versions of Perl, nor the differing operating systems that exist. MiniVend will definitely be tested with the last major release of Perl at the time of package release. As of this writing, MiniVend's version is 4.0 and Perl's latest release version is 5.005_03.
Please understand that the first remedy in the case of unknown problems will be to upgrade Perl to the latest version.
Information Needed for Support
First, check the the official MiniVend web site for information:
http://www.minivend.com/If you are unable to get MiniVend installed, it is almost always a problem with your answers to its questions or with the the Perl installation. Common problems include:
Your Perl has threading enabled. This may cause problems for MiniVend on some operating systems. Try building a Perl without threading.
Occupied default port (8786) or interfering firewall during the test. This causes part of 'make test' to fail while MiniVend might still work just fine.
Very old machine or a machine with very low memory (less than 64M). The test programs might time out while MiniVend might still work. It won't work very well; expect very slow performance if you don't have sufficient memory.
Bad installation of Perl. While not as common as it used to be, since Perl 5 is distributed with so many systems, it does happen. A proper Perl will need to be installed.
If MiniVend does a core dump or causes a segmentation fault, this is most certainly the problem.
Inadequate system privileges or quota restrictions. If you have a virtual memory quota then MiniVend can easily exceed it.
HPUX may not be able to compile vlink.c and tlink.c. Use tlink.pl as your link program. In addition, Solaris often comes with either no tools or your path may not point to /usr/ccs/bin where some of the tools are.
There are many more possible problems. See the README file for other OS-specific problems.
Second, double check that you have done the following things:
Checked all of the error.log files? There is one for each catalog, and a global one in the MiniVend software root directory.
Try INET mode if UNIX mode fails, and vice-versa.
If you run CGI-WRAP or SUEXEC, have you turned off the SUID bit for vlink with a
chmod 755 cgi-bin/simpleor the like? (Themakecatprogram does this if you answer its question correctly.)Have you tried copying the INET mode link program
tlinkover the/cgi-bin/simpleorsimple.cgiprogram?That you have proper permissions on all files that need to be written. This includes the product database ASCII source files, needed because of locking.
If the function in question is from an external program (such as PGP) you have tried the command as shown in the directive from the command line, and as the same user ID as the minivend daemon.
The vlink CGI program is being executed on a machine that has the socket file etc/socket on a directly attached disk. UNIX-domain sockets will not work on NFS-mounted filesystems! That means the server minivend.pl and the CGI program vlink must be executing on the same machine. In most cases, you can use INET mode and the tlink program instead if you must cross NFS boundaries.
If you have a problem you are not able to correct, and you have taken all of those steps, you can send email to the MiniVend users list:
minivend-users@minivend.comPlease include your operating system name and version, your Perl version, the DBM library in use, and the contents of ALL error logs.
Please see this if you don't get an answer:
http://www.minivend.com/minivend/the_authors_life.txtMiniVend is an ambitious and complex program, and is not presented as being easy to use, easy to install, or bug-free. The configuration script was done to try and make a very painful process only slightly painful. Some people install in one pass. Others never make it. Determined and thoughtful users almost always make MiniVend work.
If you are intending to run MiniVend on an ISP
The great majority of ISPs provide some CGI service, and more and more run systems that are compatible with MiniVend. The catalog configurator for MiniVend is designed to figure out many ISP directory setups.
Almost any Internet Service Provider (ISP) system should be able to run MiniVend, but some cannot (or will not) run MiniVend at all. On top of that, many times ISP personnel are too busy to help, won't help, or don't know enough to help. Some are secretive about details of the setup of their systems.
MiniVend does require a stable platform underneath it. Many ISP servers are heavily loaded (especially low-cost ones). If you run on a server which is constantly running out of memory and file descriptors, you will not be happy with your results with MiniVend.
Virtual servers that don't provide shell access are not really usable for MiniVend without direct support from the ISP -- unless you are a CGI/Perl wizard who can figure out how to do it. 8-) It can be done (with a good deal of difficulty) on some virtual servers.
Iserver.com and others who use an chroot HTTP daemon for each user will require some source-code twiddling to get the paths for vlink right -- the catalog configurator will not do the trick. See the mail list archives for the hack.
MiniVend does require a lot of memory, and it does run as a daemon. You will find that that vexes a fair number of ISPs. I have found it difficult to provide power and speed without using memory, so it will have to stay that way for the time being.
All in all, you can have a fair amount of confidence that your ISP can run MiniVend. Or, you can get one who will. 8-)
How can I unzip the file?
Use your ZIP program to extract to a directory and then run setup.bat or configure.bat.
The ZIP file is identical to the tar file except for the presence of three files, cygwin.dll, setup.pl, and setup.bat.
If you are planning on installing it on UNIX, it really should be untarred on a UNIX machine. Though some Windows ZIP clients will handle the file type, it is best if you just get the README file from the same place you got the distribution and read that.
On the UNIX machine, typically your company server or ISP server, you need to do:
gzip -dc minivend-X.XX.tar.gz | tar xvf -If you have transferred the file to your Wintel machine before then transferring it to the ISP, make sure you have done all transfers in BINARY mode. You will have weird problems if you have made one or more of the transfers in ASCII mode.
About Vend, MiniVend's ancestor
Vend was written by Andrew Wilcox in the early part of 1995, and the first released (beta) version was 0.2. Vend 0.2 is the parent of MiniVend, and the first version of MiniVend (called Vend 0.2m7) was totally based on that. It added searching and DBM catalog storage. Subsequent versions took parts from Vend 0.3, especially the VLINK and Server.pm modules, which were adapted to run with MiniVend.
The first release of MiniVend (0.2m7) was on December 28, 1995, making it over four years old. A veritable eon in web time!
Other portions of Vend, notably the database interface from 0.3, were adopted, but the commonality between the original Vend and MiniVend is minimal.
Why doesn't my question get an answer on the mail list?
Usually it is for one of the following reasons:
It is of the "It doesn't work. HEEELLLP!!!" variety. Such messages are often ignored by people on the mail list. (They figure you need help if you are posting a question.)
The question is posted in HTML. Many people don't have HTML-capable mailers and will not bother to read it. Your message is more likely to be answered if you put it in plain old ASCII format.
You used the wrong return email address, or you spam-blocked the email address. Most people will not field the instructions nor bother to re-send when it bounces.
The subject line is not informative. "[item-list] tag" is better than "It doesn't work".
Information needed for support is not included or is not intelligible. Version of MiniVend, operating system and/or virtual server type, HTTP server (i.e. Apache), and database types in use are all relevant to most questions.
Question is answered in this FAQ, the README, or by doing a simple text search (with keywords you mention) in the documentation. Most people won't do manual reading for you -- they expect you to take the time yourself.
The message does not mention what is in all of the error logs, i.e. both the main error.log and your catalog error.log. HTTP server error log entries are also nice to know about, though it is understood that many people don't have access to them.
The message does not mention what is NOT in the error logs. If you don't mention it, it will be presumed you did not look.
No one knows the answer.
I sent the author a REAL IMPORTANT question and he didn't answer!
I know your problem is important to you, but please take note of these facts:
MiniVend has been downloaded over a million times, and is included on CD-ROMs that have been distributed hundreds of thousands of times.
The mail list has had over 30,000 posts in its lifetime, many of them questions.
The author has received tens of thousands of messages about MiniVend.
There are thousands of users running tens of thousands of catalogs with Minivend.
The author is only one person, has a family, has a living to earn, and is still actively developing MiniVend.
If you think about these things, you will see why the web site and the mail list are the only reliable support for MiniVend.
There are a number of consultants who frequent the mail list, and the MiniVend web site has a list of people who have declared that they do MiniVend consulting.
Bear in mind that companies spend up to millions of dollars to put a high-quality catalog operation on line. MiniVend has been used to provide catalogs that rival those high-end operations in many ways. But, as they say, TANSTAAFL.
Is MiniVend secure?
Maybe. It has been downloaded over 500,000 times (availability at 50+ FTP sites means it is unknown how many more times than that) with no reported system security problems. It uses the Perl Safe.pm module for user-embedded Perl subroutines and conditionals to make use of those pretty carefree.
However, there are definite potential problems with credit card number security that can be avoided:
Unencrypted credit card numbers stored on disk.
If you don't use MiniVend's encryption capability for encrypting credit card numbers, or the real-time payment (CyberCash, etc.) interface, then there will be unencrypted credit card numbers present in your session database files.
If your system is the target of a break in, then these numbers would be available to any user ID that can read the session files.
This is the reason MiniVend defaults to read/write permission for the MiniVend user only.
Unencrypted credit card numbers sent via email.
The same things apply for orders sent via email. If it is not encrypted with PGP, then it is at risk.
The default demos also store the orders in the file etc/tracking.asc, so you should check there as well if you want to scrub existing credit card numbers on disk.
Running in INET mode from another machine.
If you are using INET mode, and the transmission is going via the network to another machine (i.e. not localhost), then you should be possibly concerned about which wires your SSL-encrypted data is traveling over. You should be behind a firewall, firewall router, or at least some sort of spoofing-protected filter.
Running SQL databases without WRITE_CONTROL or other permission blocks.
It is possible to enter arbitrary SQL in some search definitions. Though MiniVend tries to block non-select calls, this is not bulletproof. It is best to have certain tables be read-only for MiniVend, i.e. no insert or update permission. For tables that must be updated (i.e. userdb, transactions, and orderline) should use the WRITE_CONTROL capability and the NoSearch directive to protect them.
The bottom line is that security needs to be your concern. MiniVend tries to warn you and provide means for protecting customer data, but it can't stop you from doing all unwise things. The author stands behind the license for MiniVend and disclaims all responsibility.
What HTML editors work with MiniVend?
None, really, though by accepting a performance penalty you can embed many MiniVend tags inside of regular HTML with things like:
[pragma no_html_parse 0]
<A HREF="[href minivend_page]">Link</A>
<SCRIPT LANGUAGE=MV MV="set Action">
mv_todo=return
mv_nextpage=your_page
</SCRIPT>You will probably have to edit MiniVend pages by hand.
Some HTML editors have a tag like <NOTOUCH></NOTOUCH> that defines regions which should not be wrapped or reformatted by the editor. You should use this.
Also, if uploading a page from a Mac or PC make sure to upload in ASCII (i.e. non-image) mode. If you ignore this, you can break your MiniVend catalog!
What can you expect in the way of support?
(This is the author, Mike Heins, speaking.)
I am interested in creating a better MiniVend. However, it has become pretty popular and you should not expect individual support.
What I will typically do:
Follow up on cogent bug reports, usually with fairly quick response. A bug is not that you cannot install MiniVend -- it is a demonstrated fault in the program logic that can be duplicated. A cogent bug report is detailed and concise, and includes HTML/code snippets that demonstrate the problem.
Take note of faults in the demo. Any fixes will be discussed on the mailing list and may be fixed in the next release version of MiniVend. The demos are demos -- not a finished application.
Take note of faults in the documentation and update the next release version of MiniVend. If you provide edited replacement text it is appreciated. The documentation source is available if you would like to see how it is maintained.
Try to answer some of the well-presented questions that appear on the mailing list.
Try to constantly and incrementally improve the FAQ and other supporting information.
All of these are things I try to do. There is no commitment -- check your license for MiniVend. All are done on a time-available basis. If you don't include all relevant information I will probably ignore the question. I answer on the mailing list so that information can get to more people and be archived for posterity.
What I will not do:
Accept phone calls about MiniVend.
Answer questions that are URGENT or cry for HELLLPPP!!!!
Conduct tutorials.
Visit a URL to look at a problem.
Conduct a Q&A to extract needed information.
Where can I get more help?
If you cannot work with MiniVend without more help, you should engage a consultant to help with integration and administration. The ideal consultant will have a complete understanding of web servers, HTML, databases, and Perl.
If you cannot find a consultant, you might post to the mail list and solicit help. Several competent consultants frequent the list and may respond.
How does MiniVend compare with other shopping carts?
MiniVend is a full-featured shopping cart with high-end power. It can and does maintain databases of hundreds of thousands of items or more, and is frequently used in catalogs with hundreds or many thousands of items.
MiniVend is database-based. It has a complex implementation and a fairly steep learning curve. If all you are ever going to catalog is just a few items, and/or the items will not frequently change, MiniVend is probably overkill for your needs. It may make more sense to go with a simpler cart that embeds the product information in the page and does not require database setup.
Things that might call for the use of MiniVend:
hundreds of items or more
many different catalogs maintained by same organization
product offering will frequently change
need for programmable product display
need for complex ordering interaction
delivery of soft goods after real-time charge of credit cards
need flexible searching and categorization options
When Minivend might not be the right choice and you might want to use another free cart
only a few items
items will not change much
When to consider a commercial product
you want power, but want to interact only through a site building system like MS FrontPage or Netobjects Fustion
you want to interact only through a GUI like Windows and not edit files
When comparing MiniVend to commercial products, the comparison is better drawn to the higher end ones costing thousands of dollars rather than the low end ones costing hundreds of dollars.
Subjectively, people have both good and bad experiences with MiniVend.
After investing tens of thousands of dollars and almost
a year of effort in commercial software, we switched
to MiniVend and were operational within weeks.
-- large corporation
MiniVend is too difficult for the user to configure. There
are too many things that must be gotten just so.
-- Small internet service provider
I really like the new site, its laid out well and the
documentation is so good I've decided to use it even though
I'm not a programmer.
-- happy prospective user
Your documentation is awful.
-- not-so-happy prospective user
Your documentation is some of the best and most comprehensive
we have seen for a freeware program.
-- happy user
And the your pages don't have the right information in
them and that's MY FAULT? How about the fact that your
configure script acts differently every time it gets run?
-- not-so-happy user(Obviously, mileage varies with the user. Thankfully, the happy ones *seem* to heavily outnumber the unhappy ones...)
One user says:
-- MiniVend is an electronic commerce development environment;
*not* a shopping cart.This is not far from the truth, though modifying the "simple" or "basic" demo seems to work for many users.
Despite being free, MiniVend will require an investment -- either your time or the money to engage a consultant skilled in the web and in databases. If given its due, MiniVend can provide power that no other free shopping cart has.
I want to partner with you, or exchange links, or ....
We receive many, many requests for this type of thing. The answer is almost always no, we are not interested. We might be interested if there is a big check or significant Perl expertise being offered.
- Payment gateways
-
There are literally dozens of different companies doing e-commerce payment services on the web. We have received inquiries from many of them over time. The only way we will consider putting in support for a specific payment gateway is if it is a funded consulting project. This is usually thousands of dollars and is prohibitive
Users have integrated Minivend with many different payment gateways -- we have done various versions of CyberCash, Signio, and Authorize.net over time. We support CyberCash directly in MiniVend as the market leader; Minivend 4 makes it pretty easy to integrate your own gateway.
- Directory listings
-
You may list Minivend in your software directory, but we won't maintain the listing and we don't want to be on your mail list.
- CD-ROM distributions
-
You may distribute MiniVend unchanged on your CDROM. We like to get a copy if you do, but that is not strictly required.
- Reselling
-
You can't resell Minivend because it is Gnu GPL licensed; but you can give it away. See the www.gnu.org website for more information.
Windows-specific questions
"Bad command or file name" when double-clicking on the setup icon
This means Perl is not in your PATH or is not installed.
You might try:
c:\full\path\to\perl setup.plIf you still have problems, it probably means Perl is not installed properly. You need the ActiveState 5.005 version, i.e. build 5xx. (If you can build your own Perl we assume you won't need the help of this question.)
http://www.perl.com/pace/pub/perldocs/latest.htmlSee the Perl distribution for details on how to install it, the MiniVend README-win.txt file for pointers to exact URLs, or visit
http://www.perl.comfor more information.
NOTE: MiniVend will not work with the ActiveState version 5.003 build 3xx distributed with the NT resource kit.
Configuration Problems
Most MiniVend configuration and setup problems are due to one of:
- Wrong information given to makecat program
-
THIS IS BY FAR THE MOST COMMON PROBLEM.
To install a working demo, MiniVend needs to know what DocumentRoot is and how to run CGI programs. Details of this setup are server- and site-specific, and you may need to do some research.
Re-run the configuration again, and pay close attention to the prompts given. There are examples given which apply to most systems.
If your web server is Apache or NCSA, Minivend will try and parse its
httpd.conffile to help you along, but many ISPs don't allow users to read these and it may fail. - Too-low version of Perl
-
If you have a Perl earlier than 5.005, MiniVend will not work. Don't even try an earlier version; you must update.
- Perl compiled with USE_THREADS
-
Run
perl -V. If you see -DUSE_THREADS in the compilation definition, you might run into problems with MiniVend.
VLINK or TLINK compile problems
(None of this is valid for Windows. Use the precompiled tlink.exe or tlink.pl.)
The latest version of vlink.c and tlink.c have been compiled on the following systems:
AIX 4.1
BSD2.0 (Pentium/x86)
Digital Unix (OSF/Alpha)
FreeBSD 2.x and 3.x
IRIX 5.3, IRIX 6.1
Linux
SCO OpenServer 5.x
Solaris 2.x (Sun compiler and GCC)
Solaris 7 (Sun compiler and GCC)
SunOS 4.1.4Some problems may occur. In general, you can ignore warnings about pointers.
Make sure that you have run the configure program in the src directory. If you use MiniVend's makecat program it will try to compile an appropriate link at that time, and will substitute tlink.pl if that doesn't work.
You can compile manually with the proper settings with this series of commands:
cd src
./configure
perl -e 'do "syscfg"; system ("$CC $CFLAGS $DEFS $LIBS -o tlink tlink.c")'
perl -e 'do "syscfg"; system ("$CC $CFLAGS $DEFS $LIBS -o vlink vlink.c")'There is also a compile_link program which has docmentation embedded and which will compile an approprate link.
If you cannot compile, try using the tlink.pl script which should work on most any system.
We're sorry, the MiniVend server is unavailable...
This is the most common problem on UNIX systems. It almost always means that permissions are not properly set up, or that the VLINK program is not setuid. Try temporarily changing the permission of the MINIVEND_ROOT/etc/socket file to be read/write to all groups (chmod 666 etc/socket). This must be done after the server is started, as MiniVend deletes and recreates the socket every time it starts. If MiniVend then works you will have to make sure the user that the VLINK program runs as matches the user who is running the MiniVend daemon.
<HR> It is not recommended that you install the MiniVend software as root. If you are setting MiniVend up for the entire machine, and not just as a virtual host user, it is usual to create a special mvend or minivend user to run the daemon and the link program. This means the directory listing for your CGI-BIN should be something like:
-rwsr-xr-x 1 minivend users 6312 Dec 30 11:39 cgi-bin/simple
and for the socket file it should be:
srw------- 1 minivend users 0 Dec 30 11:41 etc/socket
Once you have set up the software, you can easily install catalogs as root as long as your umask is set to 2 or 22.
(The following assumes you have made the MiniVend software owned and run by the special user mvend and that each user has a MiniVend catalogs directory /home/user/catalogs).
The following policies should be automatically offered when installing MiniVend 3.06 or higher.
The best way to set permissions on a multi-user system is to make all files group readable and writable (660 or 664 mode). If you have a system setup that places each user in their own group, then make mvend a member of each user's group and set ownership and permissions with:
find /home/user/catalogs -print | xargs chown user find /home/user/catalogs -print | xargs chgrp user find /home/user/catalogs -print | xargs chmod g+rw
For best results, make the user's default umask be 2 so that they will by default create files that have the proper permissions.
If you have all users in the same group, the above is not secure. You should put mvend in a group of which no user is a member (perhaps mvend would be a good choice) and then make all files owned by the group mvend and all directories be set to mode 2775:
find /home/user/catalogs -print | xargs chown user find /home/user/catalogs -print | xargs chgrp mvend find /home/user/catalogs -print | xargs chmod g+rw find /home/user/catalogs -type d -print | xargs chmod g+s
This will make files default to the proper group when created (on most UNIX versions, anyway). <HR>
If you are on a virtual hosting system, the procedure varies. Making the program setuid should work for most systems -- if your setup uses CGI-WRAP or another setuid scheme it should still work OK, though you may have to unset the setuid bit with chmod u-s cgi-bin/simple or the like. If you have a non-standard CGI setup, as some virtual host systems do, you will need to know something about UNIX and the web -- or engage a consultant -- to properly set the paths up. Usually switching to TLINK/INET mode is the easiest thing to do, though with Iserver and a few others it may take more than that. <HR>
If you used the makecat program to build the catalog, it should warn you if it was not able to make the link program setuid. To set the program (in the file cgi-bin/simple in this example) to be setuid, you use the command:
chmod u+s cgi-bin/simplePlease understand that the first remedy in the case of unknown problems will be to upgrade Perl to the latest version.
Error -- the MiniVend server was not running...
This indicates that the link CGI is not communicating with the MiniVend server.
IMPORTANT NOTE: The server should always be started by the same user ID which owns the suid vlink program. (This does not apply to TLINK/INET mode.)
The server must be running, first of all. If you didn't start it, you can do so by going to the MiniVend home directory and typing:
bin/startYou can check to see if your server is running by typing:
Linux, SunOS, BSD: ps -ax | grep minivend
Most other systems: ps -elf | grep minivendNote: Solaris and IRIX truncate the string, and doesn't allow setting of the $0 parameter. You may have to grep for 'perl' instead.
If the server is not running, it may have failed due to another process occupying the TCP socket 7786. If using VLINK, you may start MiniVend with 'start -u', which will not monitor the internet-domain socket.
If VLINK is not communicating with the server, there are a number of possible reasons. First, if you are trying to run MiniVend on an ISP, go to the section about ISP problems -- it is probably one of those. If you are running MiniVend on a single machine, it is probably one of:
1. Permissions problems
2. MiniVend on NFS-mounted file systemPermissions are easy. If you for some reason can't run VLINK as an SUID program (SUID to your user ID, not to root), then you will need to make permissions more permissive. See the MiniVend documentation for how to use the ReadPermission and WritePermission directives to make the session files and sockets 'group' or 'world' readable and writable. If you can make your UID, or the one you have chosen to own MiniVend, the same group as your HTTP user, then you can make the files group read-write. If you can't, you will have to set the dreaded 'world' permissions.
If you are running MiniVend on an NFS-mounted file system it cannot run in server mode, because UNIX-domain sockets don't work on NFS. You will need to change to static mode from server mode, or better yet, put MiniVend on a file system that is directly mounted.
As of MiniVend 2.03, you can use MiniVend in INET mode along with the tlink.c program to allow running across NFS boundaries. If you have not changed the configured defaults, and still it will not communicate, you should try setting the LINK_HOST and LINK_PORT directives in tlink.c and recompiling. <hr>
I get messages like 'Config.pm not found'. What does it mean?
This means your Perl is not properly installed, or that MiniVend is not using the proper Perl binary. On UNIX, try reinstalling MiniVend and using the standard Perl installation sequence:
/complete/path/to/proper/perl Makefile.PL
make
make test
make installOtherwise, contact your system administrator.
Your demo has a very large price for the first item, and when I change the quantity the price drops precipitously.
This is a feeble attempt at humor. Check out the Quantity Pricing feature of MiniVend. Try looking at:
http://www.minivend.com/cgi-bin/simple/quantity?;00-0011Can't locate lib.pm in @INC. BEGIN failed--compilation aborted.
Your Perl is not properly installed. Someone has put a Perl up on your system, then either moved or removed the library directory.
Contact your system administrator and ask them to re-install Perl.
Can I run MiniVend on my Macintosh?
No. MiniVend will not run on a Macintosh running System 7 or other "Finder" operating system. If some technically-oriented user would port it, or someone will give MiniVend's author a PowerMac, then it might. 8-)
MiniVend's *files* can be manipulated by any computer. As long as uploads/downloads of database source, pages, and configuration files are done in ASCII mode, there is no reason you can't edit them on your Mac. And with MySQL or other ODBC databases on your UNIX-based ISP, you can even directly interface to the database you use with MiniVend -- provided you have the scarce ODBC middleware needed for the Mac. But you must run it on UNIX or another Mac operating system. MiniVend does run on MkLinux, Linux PPC, and OS/X.
Shopping cart is dropped when using SSL.
This is usually due to the HostnameLookups (Stronghold/Apache parameter) not matching for the two servers, secure and non-secure.
If it still does not work, then try changing some of the appropriate configuration parameters in minivend.cfg:
DomainTail No
IpHead YesIf you still are having problems, try this combination in catalog.cfg, the catalog configuration file:
SessionExpire 10 minutes
WideOpen YesThe above setting will typically make MiniVend work when it is possible to work.
Segmentation fault or other core dump
If this happens when you run the MiniVend test or server, it is always a Perl that has a problem. Not sometimes, always.
A proper Perl should never have a segmentation violation, period. And it should not dump core (unless you passed it a -u option somehow).
You will need to either update Perl or report the bug to the proper personnel. Depending on your situation and technical ability, this may be your system admin, ISP, or the Perl porters.
XXXXXX.pm does not match executable version.
This is a Perl which does not have the right Perl library installed. It usually results from a naive system administrator who thinks they can bypass the 'make install' for Perl and just copy the Perl binary or directories.
In any case, it has nothing to do with MiniVend when you are running on UNIX. MiniVend does not include any compiled libraries.
MiniVend doesn't work with RedHat 5.0 (glibc)
This is a defective Perl distributed by RedHat. The problem is that they don't take GLIBC into account. It will pass make test 100%, but strftime dumps core on a segfault.
You shouldn't run RedHat 5.0 anyway; it has drastic security problems. Update to a later version and build a new Perl.
ISP Problems
Great strides have been made since MiniVend's early days. The great majority of ISPs provide some CGI service, and more and more run systems that are compatible with MiniVend. The new catalog configurator for MiniVend makes setup much easier.
A word of warning -- if you chose your ISP mostly on price, you can expect problems. There is no such thing as a free lunch; the low-cost providers typically have heavily-loaded machines and many domains. The more domains and the more load the unhappier you will be with MiniVend. MiniVend works best on a fast machine with plenty of memory.
A few Internet Service Provider (ISP) systems still have difficulty with one or the other aspect of running MiniVend. A few cannot (or will not) run MiniVend at all. On top of that, many times ISP personnel are too busy to help, won't help, or don't know enough to help. Some are secretive about details of the setup of their systems.
All in all, you can have a fair amount of confidence that your ISP can run MiniVend. Or, you can get one who will. 8-)
No shell access allowed on my ISP.
This used to mean that you were totally out of luck. You probably still are, but it is at least possible to run MiniVend on a virtual server such as HWY.NET.
You should be able to use the tlink.pl program and INET mode to start using MiniVend -- with quite a bit of work. You will need to hand-edit all of the configuration files, and use tlink.pl with the appropriate settings. Long term, you should put a compiled tlink in place.
You will also have to start the MiniVend daemon via a CGI program that you write.
Bottom line: don't try this unless most people call you a wizard. 8-)
The MiniVend web site has pointers to ISPs who happily host MiniVend.
No C compiler to compile VLINK or SVEND.
Since VLINK needs certain values set in the source before compilation, a pre-compiled version will not work. It is recommended that you get the latest version of MiniVend and run in INET mode along with the tlink.pl Perl-based link program.
A pre-compiled tlink.c might also work for you if you can use the defaults of 'localhost' and port 7786.
Perl version too low
MiniVend requires Perl 5.005 or higher. Perl 5.005_03 or higher is strongly recommended.
MiniVend 3 can run on Perl 5.004, but it is no longer being actively developed.
We're sorry, the MiniVend server is unavailable...
The below all assume you were able to start the MiniVend server.
This could be almost anything, but with a properly configured MiniVend it is almost undoubtedly due to your CGI-BIN and/or your MiniVend directory being located on a different filesystem than the actual machine that is executing the program. VLINK uses UNIX-domain sockets, which don't work on NFS-mounted filesystems.
Iserver.com and other systems which use chroot HTTP servers require quite a bit of extra configuration to get going.
If you have not been careful to set permissions properly when running in VLINK/UNIX mode, the link CGI will not be able to communicate with the MiniVend server. Please read the documentation, which covers this in detail.
You can run in INET mode with the tlink link program to prevent those problems.
Document contains no data or premature end of script headers (especially on BSDI or FreeBSD)
This usually means that your HTTP server ran out of resources during the execution of the link program. It couldn't create more sockets, is unable to create a process, or can't open any more files.
This happens especially in frames catalogs, when MiniVend is sending more than one page simultaneously. And even more especially on FreeBSD and BSDI, which are often distributed with the kernel parameters SOMAXCONN and CHILD_MAX set to levels unsuitable for serving the web.
Go to
http://www.deja.comand try searching on for MAXUSERS -- this should give you plenty of pointers on how to set those parameters properly.
My provider runs Windows NT
MiniVend is unlikely to work on Windows NT ISPs in the near future. If you have a dedicated NT machine, there is a version of MiniVend for Windows NT. It may work for you, but there are differences in operation from the UNIX version (mostly due to NT's lack of fork() or and lack of user-space threading support in Perl).
MiniVend server only runs for a while, then dies.
Many ISPs don't allow your user ID to run a program unless it is logged in! The moment a watchdog program notices a daemon running with a non-logged-in UID, it terminates the program. Or it terminates programs that haven't been active for XX minutes. Contact your ISP about this -- they may be able to do something for you.
Things about MiniVend that people sometimes don't understand....
There are a few things that seem to escape some users in the documentation. This is no doubt due to the author's closeness and familiarity with the concepts of MiniVend.
This section attempts to explain some of these basic issues.
Is MiniVend a script, an application, or what? Why is it so big?
MiniVend is not just a script. It is a combination of many programs, Perl modules, and links to other subsystems such as SQL databases, CyberCash, PGP, and the Glimpse search engine.
It is so big because it is more than just a shopping cart -- it is a complete database access and retrieval application. It uses a lot of memory because the author got a case of feeping creaturitis and added too many features while attempting to maintain backward compatibility with older catalogs.
This means that MiniVend is probably not a good choice for someone who is going to offer only a few products. It is optimized for catalogs of more than a hundred items -- catalogs that expect to change and grow over time. It is suitable for very large catalogs.
What is a daemon? Why is MiniVend a daemon?
A daemon is a program that always is running in the background on the system, initialized and waiting for something to do. MiniVend runs as a daemon in the normal course of events.
Other programs that you may be familiar with that run as daemons in most cases:
HTTP server (Apache, etc.)
MySQL, mSQL, Oracle, and other SQL servers
Sendmail
MiniVend takes an appreciable amount of time to compile and load even on the fastest systems. It has many configuration options, and can serve hundreds of catalogs. If it were to be loaded every time a user accessed it, it would be unusable.
The daemon approach allows a rich set of features to be accessed fast. The actual CGI program (vlink or tlink) is a small program written in C -- it communicates with the minivend daemon.
One of the side effects of this is that when you change a configuration file, you must tell MiniVend. You do this either by restarting the server, or better yet, using the reconfig script to reconfigure an individual catalog.
Hey, where are the pages?
MiniVend pages are not kept in normal HTML space. Look in the catalog subdirectory pages.
The pages are always filtered through the MiniVend daemon before being delivered.
Hey, where are the images?
MiniVend is a CGI program, and if you tried to use relative image paths you would end up with IMG tags like
<IMG SRC="/cgi-bin/simple/../whatever.jpg">Not what you want. So MiniVend by default uses an ImageDir for a prefix. In the demo that would be /simple/images/, so image specs that have no absolute path information are prefixed with that.
In your MiniVend page, this tag
<IMG SRC="ordernow.gif">will become
<IMG SRC="/simple/images/ordernow.gif">and this:
<IMG SRC="items/00-0011.jpg">will become
<IMG SRC="/simple/images/items/00-0011.jpg">Absolute image paths are not affected, so if you reference an image at /other/images/whatever.gif, it will not be touched.
My [item-field name] tag isn't working! (or [loop-field ...] or [foo-field ..]
Read the fine manual. You probably want [item-data foo name] instead.
The [item-field name] tag normally only references items in the products table.
The reason for this is the scenario where you split your products over multiple tables using the ProductFiles directive, Perhaps you have one named new and one used, or one for several different vendors.
The [item-field ...] tag will select the data from the first ProductFiles entry that pertains.
If you want to call data from a specific table, use [item-data table column].
How do you pass variables from page to page?
No effort needed -- MiniVend does this automatically.
Every user session that is started by MiniVend automatically creates a variable set for the user. As long as the user session is maintained, and does not expire, any variables you set on a form will be "remembered" in future sessions.
Don't use the prefix mv_ for your own variables -- MiniVend treats these specially and they may not behave as you wish. Use the mv_ variables only as they are documented.
Also, because you can set so many variables, MiniVend does not unset variables it does not find on the current form. That means you can't expect a checkbox to become unchecked unless you explicitly reset it.
How can I tell when I need to quote a tag inside a tag?
In general, you don't need to quote the following tags which are interpreted first within a list:
[item-code] [item-data ...] [item-field ...] etc.
[loop-code] [loop-data ...] [loop-field ...] etc.
[foo-code] [foo-data ...] [foo-field ...] etc.This is because they are interpreted as a part of the surrounding [loop], [item-list], [search-list], [sql list], or [tag each table] constructs.
So this will work:
[item-list]
[page [item-field url]]detailed info[/page] on [item-description]
[/item-list]This will not work:
[page [value mypage]]The [value ...] tag is not interpolated before page, and the parser will not know to do so. It needs to be instead:
[page href="[value mypage]"]Clear as mud, right? Well, at least if you quote them all you can't go wrong. 8-)
You might wonder why unquoted tags are even allowed. The answer is performance; if you have large lists of tags you can achieve significant speedups by using positional parameters. It requires CPU power to parse and disassemble the named parameters.
Can I use MiniVend with my existing static catalog pages?
Yes, but you probably won't want to in the long run.
MiniVend is designed to build pages based on templates, from a database. If all you want is a shopping cart, you probably should use a simpler program.
It is not difficult to convert existing static pages to MiniVend, but maintaining them can be a nightmare.
That being said, all you usually have to do to place an order link on a page is:
<A HREF="/cgi-bin/simple/order?mv_order_item=SKU_OF_ITEM">Order!</A>Replace /cgi-bin/simple with the path to your MiniVend link.
Setup Questions
MiniVend is quite powerful, but also quite complex. There are many possibilities opened up with its conditional HTML, but also many pitfalls.
Read the documentation thoroughly, then inspect the basic and simple demo pages for help. Pay particular attention to:
browse*.html
flypage.html
results.html
ord/basket.html
ord/checkout.htmlThese pages use many of the powerful features of MiniVend, and studying them will be instructive.
Can I run multiple catalogs on one server?
Yes. MiniVend supports multiple independent catalogs. There are users who run more than 500 catalogs on a single machine. The capacity is usually a function of how busy the catalogs are and how much memory and processor speed your system has.
How do I start MiniVend when I reboot?
Use the standard facility on your operating system. For BSD style systems, the file is usually called rc.local (in the /etc directory).
On SVR4 systems, it is quite a bit more complex -- look for the /etc/rc.d directory and see what other programs do. Often the file is called S99startup or something similar.
IMPORTANT NOTE: MiniVend must not run as root, which is the user that the startup file executes as.
The technique to start up depends on the facility of your su(1) command. This should work on most operating systems:
su minivend <<EOF
/your/minivend/dir/bin/restart
EOFThe EOF must be the only thing on the line (no leading or trailing whitespace).
If your su(1) command has a -c option (as most System 5 UNIXes do) then you can just do:
su -c /your/minivend/dir/bin/restart minivendMiniVend supplies a restart script which tries to do the above portably. It works on many operating systems (Linux and Solaris have been tested by the author.)
How do I set up a Mall?
MiniVend can share product databases, session files, and any other databases. It has many features which support mall building.
You can easily build separate and mostly identical catalogs which you link to via HTML.
But building a mall is as much an exercise in data and process as in software. Consider the following questions:
Who will be clearing payment?
What happens if everyone doesn't have the same tax rate?
How will you clear orders to multiple vendors?
How will you bring together multiple types of shipping?
How will the vendors get product data (including images) to you?
If you cannot answer those questions and then visualize how to build a mall, then you probably should not try.
Can I attach a size or color to a product?
MiniVend has product modifiers, or attributes, which can be carried around with the product.
The [item-accessories attribute] tag will automatically place a suitable select widget on an HTML form, and "remember" what should be selected. See the MiniVend documentation for Item Attributes.
You can use the SeparateItems directive or set the mv_separate_items variable on the order form to cause ordered items to be put on separate lines in the shopping basket. (This is the default in the demo catalogs.) This makes size/color handling much easier for multiple items. They can be stacked, which means that you can add multiple instances of a size or color to an individual product within a shopping cart entry line, but this is too much trouble.
The attribute information is placed on the form with form fields, like:
<INPUT TYPE=XXXXX NAME="[modifier-name size]" VALUE="[item-modifier size]">The embedded Perl capability of MiniVend means that you can discover the number of items on order of each type, and build quite detailed input forms.
The MiniVend demos have some examples which should help you -- try ordering the T-Shirt and visiting its flypage.
PGP encryption -- Server Error
As always, check the error log. The most common problem is something like:
minivend.com 3Ex5lvta:minivend.com - [01/Sep/1997:09:08:43] simple /cgi-bin/simple
> Encryption error:
>Probable causes:
- Minivend user ID doesn't have keyring
-
You must have a
.pgpor.gnupgdirectory in the home directory of the user running MiniVend. It is also possible to set an environment variable (variously PGPPATH or GNUPGPATH) to orient the program correctly. - Trust problems
-
If the key you are sending to has not been signed by another (trusted) user, then you will get error returns from some flavors of PGP, which causes the problem. Sometimes the fix is to route the error output to /dev/null (at least on UNIX) by changing the EncryptProgram directive in catalog.cfg:
EncryptProgram /usr/bin/pgp -fat -r sales@your.com 2>/dev/nullFor GNU Privacy Guard, GPG, you would use something like:
EncryptProgram /usr/local/bin/gpg -fa --always-trust -r sales@your.comOn Windows or other operating systems, the only fix is to sign the key or otherwise prevent the error from occurring.
PGP encryption -- What do I do now that it is working?
This depends on what you do with orders once you receive them by email.
Some PC mail agents (notably Eudora) will decrypt the PGP message embedded within the message text. In that case, you can simply embed the [value mv_credit_card_info] call right in the message and be done with it.
If your mailer will not decrypt on the fly, the best way to read the credit card number is to set up MIME encoding of the order email. To do this, find the order report you are using. In the standard demos it is pages/ord/report.html or etc/report.
Set up two MIME regions in that file. First, at the top of the file:
[tag mime type TEXT/PLAIN; CHARSET=US-ASCII][/tag]
[tag mime Order Text]
ORDER DATE: [calc]localtime[/calc]
ORDER NUMBER: [value mv_order_number]
Name: [value name]
Company: [value company]
(Rest of order text, including item list)
[/tag]Then, at the bottom of the report.html file, put the credit card info:
[if value mv_credit_card_info]
[tag mime type application/pgp-encrypted][/tag]
[tag mime Credit Card Information]
[value mv_credit_card_info]
[/tag]
[/if]Once this is done, you can then read mail, using your PGP client as a helper application to decode the MIME attachment. This does not require a fancy setup -- you can use the standard MIT PGP 2.6.2 if desired. If you are using UNIX, set up as the helper for the MIME type application/pgp-encrypted:
xterm -e pgp -m %sOn windows, it might be:
c:\mycommands\pgp -m %sMore automated or user-friendly setups are left as an exercise for the user.
How do I get the number of items in a shopping cart?
If it is simply the total number, extended according to quantity, then you can use the [nitems] tag. If you need this number for use in an embedded Perl script, you can use
$number = $Tag->nitems();If it is the number of line items you need, then you can use a Perl script:
[perl]
return scalar @{$Carts->{main}};
[/perl](The 'main' refers to the main shopping cart.)
If you have SeparateItems in effect, and need the number of unique items, you could use:
[perl]
my $cart = $Carts->{main};
foreach my $item (@$cart) {
@items = split /\|/, $items;
$count = 0;
for (@items) {
$count++ unless $seen{$_}++;
}
$count;
[/perl]The demo doesn't do...(pick one)
That is because it is a demo. It is not intended to be a finished catalog, just a starting point.
Though the author likes to get reports of malfunctions in the demo, he feels absolutely no urgency about fixing or responding to such reports.
How can I use MiniVend with Microsoft Access?
Though MiniVend has ODBC capability, the Microsoft Access ODBC driver is not a network driver. You cannot access it on a PC from your ISP or UNIX system.
However, you can turn it around. Once you have created a MySQL or other SQL database on the UNIX machine, you may then obtain the Windows ODBC driver for the database (mySQL has a package called myODBC) and use the UNIX database as a data source for your PC-based database program.
Here is a quick procedure that might get you started:
Get and mySQL from:
http://www.mysql.comInstall it on your UNIX box. On Linux it is as easy as getting the RPM distribution:
http://www.mysql.com/rpm/You install it by typing, as root,
rpm -i mysql-3.XX.XX.rpm. If you are not root, you will have to build the source distribution.To avoid permissions problems for your testing, stop the mysql daemon and allow global read-write access with:
mysqladmin shutdown safe_mysqld --skip-grant-tables &Obviously, you will want to study mySQL permissions and set up some security pretty quickly. It has excellent capability in that area, and the FAQ will help you get over the hurdles.
Set up a database for testing on the UNIX machine:
mysqladmin create test_odbc mysql test_odbcMake an SQL query to set up a table, for example:
mysql> create table test_me ( code char(20), testdata char(20) ); Query OK, 0 rows affected (0.29 sec) mysql> insert into test_me VALUES ('key1', 'data1'); Query OK, 1 rows affected (0.00 sec) mysql> insert into test_me VALUES ('key2', 'data2'); Query OK, 1 rows affected (0.00 sec) mysql>Get and install myODBC, also from the MySQL site (use a mirror):
http://www.mysql.comYou install this package on your Windows 95 or NT box. It is a simple setup.exe process which leads you to the control panel for setting up an ODBC data source. Set up a data source named
test_odbcthat points to the databasetest_odbcon the UNIX box. You will need to know the host name and the port (usually 3306).With MS-Access, you can then open a blank database and select File/Get External Data/Link Tables. Select File Type of 'ODBC databases', and the proper data source, and voila! You should have access to the database residing on the UNIX side.
Difficulty interacting with browser: Request method for form submission is not POST
There are many possible causes for this error. Using MiniVend 3.08 and above, the main 3 are:
This most common case is where the user bookmarks a shopping cart after Recalc or bookmarks a checkout page. Those pages are usually the results of form submissions, and are not really a candidate for a bookmark. You should make sure you provide links to both of those pages on the interact special page (in special/interact if you have started with the demo).
User hits BACK with a very small cache. There are quite a few users who have decided 10Kbytes is enough of a cache, and that won't quite cut it. 8-) (Actually, they probably assumed the number to enter was in megabytes.)
One possible cause is that you must define METHOD=POST in all of your forms, not METHOD=post. The lower case form is not recognized in the HTTP spec.
If you are using SSL and don't have a later HTTP server (released after say September of 1997), there is a bug in earlier versions Microsoft Internet Explorer's version of SSL3. Stronghold 2.1.1 works around this bug, so if you use Stronghold you should update.
MiniVend 3.05 and later has a new TolerateGet directive which allows you to have forms with METHOD=GET. To use, set the session ID in your form
<INPUT TYPE=hidden NAME=mv_session_id VALUE="[data session id]">then set TolerateGet Yes in minivend.cfg (the main configuration file) and use METHOD=GET on forms that have problems.
This may prevent errors due to one of the causes above.
How can I trace the source of a purchase and run a partners program?
MiniVend has a facility that adds a parameter called source to the session database for that user.
You should give your partners a source code, which must contain at least one letter character (A-Za-z only). It is placed in the sourcing URL after two semicolons as a query string of:
;;Source1If this is appended to the URL with which the user calls MiniVend it will then be placed in the session identifier source.
This URL:
C<<>A HREF="http://yourcatalog.com/cgi-bin/yourcat/sp_offer?;;Source1">
Special offer!</A>Will yield Source1 from the MiniVend tag [data session source].
How can I send an email copy of the receipt to a user?
There are several ways, but this is a more complex question than it may seem like it is.
You will have to deal with bad email addresses, deciding which information to send, showing delivery times, etc. You also have to be very careful with credit card information -- if you have not taken the proper security measures (by enabling PGP credit card encryption or using CyberCash) you might just mail them their own unencrypted credit card number!
If you still decide to do this, then I will show what I consider to be the best method -- and Caveat Emptor.
Use a GlobalSub
This is the best way, as it is fairly secure. (In case you are one of those people who go light on the documentation 8-(, you will need to read it in this case.)
GlobalSub <<EOF
sub form_mail {
my($to, $subject, $reply, $body) = @_;
my($ok);
return '' unless $to;
$subject = 'Copy of your order' unless $subject;
$reply = '' unless defined $reply;
$reply = "Reply-to: $reply\n" if $reply;
$ok = 0;
SEND: {
open(Vend::FORMMAIL,"|$Vend::Cfg->{SendMailProgram} -t") or last SEND;
print Vend::FORMMAIL "To: $to\n", $reply, "Subject: $subject\n\n", $body
or last SEND;
close Vend::FORMMAIL or last SEND;
$ok = ($? == 0);
}
if (!$ok) {
logError("Unable to send mail using $Vend::Cfg->{SendMailProgram}\n" .
"To '$to'\n" .
"With subject '$subject'\n" .
"With reply-to '$reply'\n" .
"And body:\n$body");
}
return $ok ? 'Copy mailed to user.' : 'EMAIL COPY FAILED.';
}
EOFThe above routine can be called on the report.html page with:
[perl arg=sub interpolate=1] form_mail (
q{[value email]},
'Your order from mycompany.com',
'sales@mycompany.com',
<<'EndOfOrder' )
NAME: [value name]
ADDRESS: [value address]
[value city] [value state] [value zip] [value country]
[item-list]
[item-quantity] [item-code] [item-description] [item-price]
[/item-list]
SUBTOTAL: [subtotal]
SALESTAX: [salestax]
SHIPPING: [shipping]
TOTAL: [total-cost]
EndOfOrder
[/perl](With the old parser, you use [perl sub] ... [/perl] with double brackets around some of the inside MiniVend tags.)
Of course you can place any valid tags in the body -- which is that area before the EndOfOrder "here document" marker. The usual here document caveats apply -- must be by itself at the beginning of a line, with no trailing whitespace, and watch those carriage returns if you use a Wintel machine.
Configuring catalog whatever...Use of uninitialized value at Config.pm line 1614, <CONFIG> chunk 322.
This is a warning from Perl indicating that an empty value was found where one is expected. The warning is left in so that you know that something is missing.
Whatever it is, it can be found at the specified "chunk", or line, of catalog.cfg -- if you use the #include capability, it would have to be factored in as well.
The usual reason is that a file is specified in one of the directives (usually one of Help SearchProfile OrderProfile Buttonbars UpsZoneFile) and does not exist. See the documentation for the directive on how the file name should be specified.
<H3> Mini-FAQ: Why isn't the error more enlightening?</H3>
Because Perl won't tell us what exactly went wrong -- see it's FAQ for why.
We need some more information! Problem: unspecified error
This is a fault in the order profile, and can be due to any of:
Problems with encryption
Inadvertently setting the same variable twice on the form, causing problems due to the embedded null.
Changing the checkout profile and not testing properly under all conditions.
On earlier versions of MiniVend, the demo order profile was placed in an outboard file. On newer versions, it is embedded right in the checkout page. Try replacing [set checkout_profile] with:
[set checkout_profile]
&final=yes
&set=mv_Junk 1
[/set]If the order completes, then you have a problem in your profile. Also, check the RequiredFields directive in catalog.cfg, as that is set to name in the demo. If the name variable is blank, then you will find that the order doesn't complete.
The order profile must not have non-blank lines that don't contain valid check procedures (excluding comments). If you are using a Perl routine in the profile, as above, you must take care that the routine returns a valid check routine.
Sorting doesn't work across multiple pages
This is a bug in all versions of MiniVend prior to 3.12. Update to solve the problem.
I am searching for a string and it is not found. I know it is there!
Set mv_substring_match to yes (su=yes in one-clicks).
This most commonly happens when searching for non-ISO-8859 (Cyrillic, or characters like umlaut and eacute) characters in word-match mode. The problem is, that unless your locale is set up properly that Perl doesn't think a non-ISO-8859 and a space character is a boundary.
Also, if you are searching for non-alpha characters then they will also not be interpreted as word characters and the boundary problems will still exist.
How do I display Euro pricing?
(Thanks to Thomas "Balu" Walter for this answer.)
You can use MiniVend's II8N facilty via the Locale directive:
In catalog.cfg:
# to define the euro-Settings (PriceDivide is for converting from DM)
Locale eur_EUR PriceDivide 1.95583
Locale eur_EUR p_cs_precedes 0
# this is great - you can even use HTML-Tags to display an euro-image
Locale eur_EUR currency_symbol "<IMG src="/path/to/image/euro.gif">"
Locale eur_EUR p_sep_by_space 2
Locale eur_EUR mon_decimal_point ,
# and the DM
Locale de_DE
Locale de_DE p_cs_precedes 0
Locale de_DE p_sep_by_space 2On your pages (this is from a search results page, the [item-.... ...] notation may be different depending on your context):
[item-price]<br><!-- german is default -->
[setlocale eur_EUR]
[currency convert=1][item-field price][/currency]<br><!-- the euro -->
[setlocale]Any questions? Read the docs about "Internationalization".
Performance issues
MiniVend is not a lightweight program.
If you are running it on a low-end ISP whose major selling point is low cost, you will frequently find that MiniVend performance is very poor. This is due to either:
- Not enough memory
-
If memory is low, the program will "swap" to disk. If lots of swap is used, you can expect very bad performance. This is the most common speed problem.
If your ISP uses IDE hard disks you can expect REALLY bad performance. IDE disks are very slow for multi-user machines, which should have SCSI if ANY swapping is to be done.
- Too many domains
-
If there is a huge amount of traffic on the system, then it can run at a very high "load average". IF load average runs routinely above 2, you can expect problems.
- Underpowered machine
-
If it is an old machine, it may be too slow for MiniVend. A Pentium of less than 100MHz is probably not good enough unless it is completely dedicated to MiniVend. The faster the processor, the happier you will be.
MiniVend runs, but it's sooo sllooowww...
This is almost certainly due to a system that has inadequate memory or network bandwidth. On a moderately fast ISP server with sufficient memory, pages should start displaying in less than 2 seconds. On a fast server, pages should start loading almost instantaneously.
MiniVend slows down over time
There are many possible reasons for this, but most have to do with memory or session database size.
See the documentation on MINIVEND ADMINISTRATION and learn how to expire your session database. If it gets many megabytes large, then accessing a key will get slow.
Second, if your machine is memory-poor you will find that MiniVend gets swapped to disk. Unless your system is very fast, this will greatly hurt performance. MiniVend works best on a machine that rarely if ever swaps to disk.
Third, this often has nothing to do with MiniVend at all but has to do with your HTTP server. Any long-running daemon has the potential for a memory leak -- try stopping and starting your HTTP server and seeing what happens to performance.
On Windows, you will want to stop and re-start your MiniVend server at least once per day. You can use a system agent to automate it -- you will want to stop the server to expire the session database anyway. You need to do this because MiniVend requires the Unix-specific fork() call to spawn multi-tasked servers, and without multi-tasked servers there is a strong possibility of a memory leak -- especially if you use embedded Perl or conditional tags.
The browse page (from the demo) is SLOW+!
(This old page is not used any more starting at 3.12.)
That is because it is only useful for small product lines. It pulls out all keys from the entire database and iterates over them, which is not reasonable for more then 50 products or so (depending on your server speed).
A better approach is to use a search and browse by category, an example of which is given in the demo.
You could also try something like:
[perl arg=scratch]
$start = tag_data('session', 'arg') || 1;
$chunk = 1;
if($start =~ /(\d+):(\d*)/) {
$start = $1;
$chunk = $2 || 1;
}
$prev = $start - $chunk;
if($prev < 1) {
$prev = 0;
}
$Safe{'scratch'}{'start'} = $start;
$Safe{'scratch'}{'chunk'} = $chunk;
$Safe{'scratch'}{'next'} = $start + $chunk;
$Safe{'scratch'}{'prev'} = $prev;
$Safe{'scratch'}{'not_shown'} = 1; return '';
[/perl]
[search-region arg="
ra=yes
fm=[scratch first]
ml=[scratch chunk]
sp=browse
tf=category
to=f "]
[search-list]
[on-change 1]
[condition][item-field category][/condition]
<TABLE WIDTH="80%"><TR BGCOLOR="#cccccc" TEXT="WHITE"><TD ALIGN=CENTER>
<BR><H1>[item-field category]</H1>
</TD></TR></TABLE>
[/on-change 1]
<P>
[if-field image]
<IMG SRC="[item-field image]">
<P>
[/if-field]
<H2>[item-description]</H2>
<P>
[L]Catalog[/L] [L]Number[/L]: [item-code]
<P>
[L]Price[/L]: [item-price]
<P>
[page [item-code]]<IMG BORDER=0
SRC="details.gif" ALT="[L]More Info[/L]">[/page]
[order [item-code]]<IMG BORDER=0
SRC="ordernow.gif" ALT="[L]ORDER NOW[/L]">[/order]
[/search-list]
[/search-region]
[if scratch prev]
[page href=browse1 arg="[scratch prev]:[scratch chunk]"]
<B>[L]Previous[/L]</B>
</A>
[/if]
[if type=explicit compare="[calc]
[value mv_search_match_count] > [scratch next]
[/calc]"]
[page href=browse1 arg="[scratch next]:[scratch chunk]"]<B>[L]Next[/L]</B></A>
[/if]I am using SQL, and MiniVend is so SLOW.....
It isn't MiniVend.
First of all, did you index your 'code' field? The reason MiniVend doesn't do it for you is that every SQL database seems to do that a bit differently. Even then, you can do some stuff with MiniVend's COLUMN_DEF parameter:
Database products COLUMN_DEF code=char(16) PRIMARY KEYThat will index at least the code field for MySQL. Other databases differ.
MiniVend can return VERY fast SQL search results. But you need to at least give it something to work with. The proper method for fast selection is:
[sql type=list
query="select code,category,title,price from products" ]
Category: [sql-param category]<BR>
Title: <A HREF="[area [sql-code]]"> [sql-param title] </A><BR>
Price: <A HREF="[area order [sql-param 0]]"> [sql-param price] </A><BR>
[/sql]IMPORTANT NOTE: The sql-param tag did not accept named fields before MiniVend 3.12beta4. Access with [sql-param n], where n is a modulus-zero positional field set from your query. In the example above, code=0, category=1, title=2, price=3.
This is especially powerful when you consider a joined query like
SELECT code, price, title, extended.desc
FROM products, extended
WHERE products.category = 'Renaissance'That will index at least the code field for MySQL. Other databases differ.
Don't forget that you must index your fields if you want fast searching with them as a criteria.
Here is a nice synonym for [sql type=list ...]:
[new]
[search-region arg="
st=sql
ml=1000
sq=select code,title,artist,price from products where code < '5'
"]
<PRE>
[search-list][item-code]: [item-param title] [item-param artist] [item-param price]
[/search-list] </PRE>
[/search-region]My server is getting loaded. How do I use the static page capability?
Here is an example based on the simple demo.
To set up the simple demo catalog statically, all that is required is to put in catalog.cfg:
StaticDir /ext/htdocs/simple/static
StaticPath /simple/static
StaticAll Yes
StaticFly Yes
NoCache ord specialThe root WWW directory (DocumentRoot) on my system is /ext/htdocs -- you would change your StaticDir accordingly. Make sure the directory is empty -- MiniVend will overwrite files there!
Then edit a couple of the pages -- catalog.html and results.html. They have "dynamic" elements, ones that prevent the static build for those two pages (and any searches calling them for a template) from succeeding. Insert anywhere in the page:
[tag flag build][/tag]This tells the builder to go ahead and build the static page anyway, despite the dynamic elements. (The elements in this case are the Perl code telling the user their name in catalog.html, the dynamic "Check Basket" icon on the results page, and some sorting parameters that are not used in the one-click search.)
At that point, if you are in control of the MiniVend software directory and changed directory to it, you should be able to run:
bin/minivend -build simple(Users who are provided a catalog without control of the server will not be able to do this. The administrator would need to get involved.)
You will see some output from the build command, giving you the status of the build for individual pages. (HINT: send the standard output to a file to get a full report.) It will show information like:
Checking page catalog ......................................done.
Checking page browse .......................................done.
Checking page canceled ...............skipping, dynamic elements.
...
Checking part number 00-0011................................done.
...
Checking part number 00-342.................................done.
Building page browse........................................done.
...
Building page catalog ......................................
>> found search mp=0/se=Renaissance.........................save.
>> found search mp=0/se=Impressionists......................save.
>> found search mp=0/se=Surrealists.........................save.
>> found search mp=0/se=Americana...........................save.
>> found search mp=0/se=Contemporary........................save.
done.
Building part number 00-0011................................done.
...
Building part number 00-342.................................done.
Re-checking /simple/static/scan5.html.......................none.
...
Re-checking /simple/static/scan3.html.......................none.
done.Restart the server and re-enter the catalog. Now all accesses should be fast whenever possible. One-click searches and flypages are in static HTML space, and only orders and checkout ops should be parsed by MiniVend.
This should get you started -- see the documentation for more information, particularly the section on what are "dynamic" tags and how to flag databases as dynamic with the DynamicData directive.
My session files change to owner root every day!
You have the expireall -r entry in the root crontab, and it should either be in the Minivend user crontab or run as:
44 4 * * * su -c "/MINIVEND_ROOT/bin/expireall -r" MINIVEND_USERNAME
Shipping questions
MiniVend has one of the most complete and flexible shipping calculators found in an ecommerce program. You can do most anything with a global UserTag, even to the point of looking up a cost at a remote calculator. (See the [ups-query] tag in the flycat or usertag directories for an example.)
However, all of this comes at the price of complexity. Many questions have already been answered on the user list.
I am using "price" as the shipping criteria and it seems to be wrong
When you put price in the field, MiniVend will do exactly what it says in the documentation; multiply the value of the products database field price by the number of items in the cart. If you have quantity discounds, price adjustments, or other discounts in force via CommonAdjust or another facility they will not be taken into account.
The solution is simple -- put [subtotal] instead of price in the criterion field. MiniVend will interpret MML tags normally in that position, as it will in the cost field.
I can't get shipping subroutines to work
I don't blame you. The interface is terrible and has gone away in MiniVend 4.
The best way to do this is to define a UserTag and use it as the subroutine method. For example, in the flycat demo (or in the MiniVend 4 usertag/ directory) you will see a UserTag:
UserTag ups-query Order mode origin zip weight country
UserTag ups-query Routine <<EOR
sub {
my( $mode, $origin, $zip, $weight, $country) = @_;
BEGIN {
eval {
require Business::UPS;
import Business::UPS;
};
};
$country = uc $country;
$country = undef if $country eq 'US';
my ($shipping, $zone, $error) =
getUPS( $mode, $origin, $zip, $weight, $country);
if($error) {
$Vend::Session->{ship_message} .= " $mode: $error";
return 0;
}
return $shipping;
}
EORThis is called via entries in shipping.asc:
GNDRES Ground Residential weight 0 150 f [ups-query
origin="[dv origin_zip]"
zip="[default zip 98366]"
country="[default country US]"
mode="GNDRES" weight="@@TOTAL@"
] [dv ups_adder]NOTE: The above should be all on one line, or you need to escape the newline with a \.
This is very flexible, but you can make the call much less complex if you do the parameter checks and substitutions in your own routine (i.e. read the value of $::Values->{country} or $Values->{country} instead of passing a parameter).
CHANGES
$Log: faq.pod,v $ Revision 1.3 1999/08/14 07:39:23 mike Added static build stuff
6 POD Errors
The following errors were encountered while parsing the POD:
- Around line 888:
You forgot a '=back' before '=head1'
- Around line 1608:
You have '=item 1' instead of the expected '=item 2'
- Around line 1612:
You have '=item 1' instead of the expected '=item 3'
- Around line 1616:
You have '=item 1' instead of the expected '=item 4'
- Around line 1620:
You have '=item 1' instead of the expected '=item 5'
- Around line 2180:
You forgot a '=back' before '=head2'