Troubleshooting Notes

Merchant OrderForm Web Based Shopping Cart System @ 2001
 Notes on Troubleshooting, Tips on Troubleshooting

Table of Contents | FAQ | Installation | Security Issues | Building Input Pages | Formatting
Configurations1 | Configurations2 | About Configurations | Troubleshooting | Customizing

These programs are protected by copyright and may not be resold or distributed. Please see the copyright notice for more information on your end user license for this program.

What's In This Document:

  1. Mail problems
  2. Maintenance issues
    How to clean up those scratch files

  3. no FTP privileges on invoice files
  4. unable to write to datafile using $delete_cart_final
  5. Expiring MOF's cart : how it works
  6. I get "unsecured items" browser message using SSL with MOF
  7. Edit Cart button on Billing screen causes error using SSL
  8. Installing MOF under SSL

 

 

GENERAL NOTES Sections LIst How Do I ?

The Internet is a complicated place. If you are not familiar with cgi scripts, installation issues, and troubleshooting issues, then you should realize that a cgi script is only one part of a larger operation. Unlike windows programs, which interact directly with the operating system, a cgi script is dependent on many other pieces of technology coming together, over multiple connections, etc.

A cgi script can only do what the surrounding container will let it do. A cgi scripts operation is completely dependent on the web server software, operating system permissions, Internet connection, and even browser settings, browser bugs.

Many things can go wrong with the larger container: a browser's cache settings may be set to interfere with dynamic web content, a web server is mis configured, the operating system is not allowing cgi operations, or limiting operations, file saving, etc., the Internet connection may have problems, shared SSL processing is overcrowded and sluggish. All of these things must come together for any cgi script to function flawlessly.

So, your first task at troubleshooting any cgi script is to ask yourself where the problem is located: Is it a script error, or a server error ? If something is not working, you should not assume that the script is the source of the problem.

Ninety Nine percent of folks who contact us with installation problems have made some common error in installation and/or configuration of the script settings, mostly beginners.

You may find other support notes at the Merchant OrderForm site, support pages:
http://www.merchantorderform.com/support.html

 

 

THREE LEVELS OF PROBLEMS Sections LIst How Do I ?

1. server errors

The first level of problem has to do with getting the scripts to run on the server. These type of problems cause Internal Server Errors.  This is a message from the server that the cgi program you attempted to run did not run correctly on the server.  This is not a Merchant OrderForm error.  It is your server telling you it could not run the script for one reason or another.  Follow the checklist below until you get it right.  When both main script files are up and running in ?test mode, then you are ready to tweak out all the ways that MOF will operate on your site.

2. MOF data processing errors, operational errors

The second level of problems occur after the main MOF script files are running on the server, but MOF is not operating successfully in one or more processes.  This is the number one, hands down, most common request we get from folks about installation problems: path problems, file permissions, directory location, directory permissions, syntax errors in the modified configuration files.

3. Formatting, layout, product input problems

The third level of problems is when MOF is running in all processes with no file access errors, but things like templates, images, buttons, etc, just aren't doing what you expected them to do.  Products are not showing up like you expected, templates don't look right, etc.  These are problems getting the layout, formatting, and product input to work as you want, getting all the support images, templates, addressed correctly in the various places, and getting the <FORM></FORM>s to work correctly. If using SSL, it can get real confusing, when and where all the various components are addressed between HTTP and HTTPS. 

 

 

ENABLING TROUBLESHOOTING MODE Sections LIst How Do I ?

  1. Open up both configuration files in your ASCII editor
      • mof.conf
      • mofpay.conf

  2. Find the setting called $ERRORMODE in each (close to the top)
    around LINE 56

  3. Set the $ERRORMODE = 0;

  4. FTP (ASCII only) both configuration files back to your server

While MOF is in $ERRORMODE = 0; all configuration errors, path errors, etc. will be reported with more detail to help you diagnose where the problems are.

Remember to set the $ERRORMODE back to 1 or 2 when you have completed your troubleshooting and testing, so that your customers will get friendlier error messages. Once all the problems are worked out with your installation, the most common Error Message is from customers' using browser back, forward buttons, and triggering a cgi cache error. So, the customer friendly ERRORMODE looks much better and helps folks get back to the cart and the site easily. You want to get customers quickly back to your store without being alarmed, ERRORMODE = 2; is set up to do that.

 

RUN ?test Sections LIst How Do I ?

After setting the $ERRORMODE = 0; then you can run an initial ?test

  1. Run the ?test mode for each of the main scripts:
    Type in the full URL to <mof.cgi> on your server, append the "?test" command
    Type in the full URL to <mofpay.cgi> on your server, append the "?test" command

    http://www.site.com/cgi-bin/mcart/mof.cgi?test
    http://www.site.com/cgi-bin/mcart/mofpay.cgi?test

Each script should give you an information page with the headings:

  • Merchant OrderForm v2.4 is Running [Front End - Cart Collection]
  • Merchant OrderForm v2.4 is Running [Back End - Payment Processing]

If you do not get this message, then consult the next sections Run ?test does not work.

Run ?test will perform some initial tests, and can show you where some of the more glaring problems are.

If all looks well there, but you're having some other problems, then continue testing the cart while in troubleshooting mode, and consult any error messages presented by MOF

 

RUN ?test DOES NOT WORK Sections LIst How Do I ?

If you cannot get the scripts to run ?test

MOF's troubleshooting feedback is only good if the scripts are actually running on the server. Troubleshooting mode can help you locate MOFcart operational errors, usually because of faulty paths, permissions, settings.

Tip: refresh your browser regularly, empty the browser cache, etc. to make sure you are not viewing cached browser pages, instead of real live error pages

  1. Open up both main program files in your ASCII editor
      • mof.cgi
      • mofpay.cgi

  2. Find the exact second line in each file, which looks like this:
    # use CGI::Carp qw(fatalsToBrowser);

  3. Uncomment the line to make it active (remove the # character in front)
     use CGI::Carp qw(fatalsToBrowser);

  4. FTP (ASCII only) both program files back to your server

This will set up an additional level of feedback from the servers CGI environment. Most of the messages will report "Software Errors." You must read the messages carefully for clues on what you did wrong.

 

COMMON PROBLEMS IN RUNNING SCRIPTS Sections LIst How Do I ?

If you just cannot get MOF's ?test to give you the "Merchant OrderForm v2.4 is Running" message, then consult this list of possible reasons.

Tip: refresh your browser regularly, empty the browser cache, etc. to make sure you are not viewing cached browser pages, instead of real live error pages

Here are the most common things that go wrong for beginners, listed in order of probability:

  • One or more script files did not transfer ASCII mode: help
  • Do not have execute permissions on the *.cgi files: help
  • You have Perl syntax errors in configuration files

    Enable CGI::Carp (instructions above). CGI::Carp will report filename(s) and line number(s) where the Perl interpreter found errors. If you need help with Perl syntax rules see: Docs > AboutConfigurations.html, then check the lines surrounding what CGI::Carp is reporting

  • One or more script files are missing: help
  • Make sure the path to perl is correct (pretty uncommon)

    First line in mof.cgi and mofpay.cgi
    In the package, Path to perl is set to #!/usr/bin/perl
    Your server may ask you to set it to #!/usr/local/bin/perl
    or perhaps even something different

  • You are on an NT/Win server and scripts do not have execute privileges
  • You are on an NT/Win server and need to adjust @INC
  • You are on an NT/Win server and need to run MOF as *.pl files only
    Find NT help here

  • In very rare cases I have seen where the server actually requires script files to be stored on the server in Unix format. If on windows, you'll need an ASCII text editor which can SaveAS UNIX



NT/WINxx NOTES Sections LIst How Do I ?

The first thing to do when installing under NT/Win is research the help or support areas for "how to" stuff on installing CGI scripts. They will have some specifics there.

File and directory access privileges on NT do not operate like on Unix-Linux.  You'll have to contact your Admin or hosting help pages to determine what you need to do to get all privileges operating correctly.  Sometimes, the cgi-bin under NT systems is not even set up to execute PL files, so you'll need to contact someone to even have that enabled.

Correct privileges

Make sure your directories and files have the correct privileges needed.

  • Execute privileges for:
    • mof.cgi (PL)
    • mofpay.cgi (PL)

  • Write privileges for:
    • mofnumber.dat
    • ../invoices/ directory
    • ../orderdata/ directory
    • ../orderinfo/ directory


Do you need *PL scripts ?

Most NT servers run CGI scripts under the PL extension. If your NT/Win server help instructs that you can only run Perl scripts using the extension "PL," then simply rename the two cgi program files to PL extensions.

    • mof.cgi --> mof.pl
    • mofpay.cgi --> mofpay.pl

Note: if you have to rename *.cgi --> *PL extensions, then you'll have to adjust all the POST actions in the Example pages to PL and both of the configuration files will need URLs for the programfile and paymentfile reset to PL

    • $programfile = 'URL-TO-MOF.CGI';
    • $paymentfile = 'URL-TO-MOFPAY.CGI';


Adjust absolute paths

You may need to adjust all template paths and DATA paths to NT/Win standards:

  • Make sure you use the backslash and not the forward slash.
  • Make sure the setting is not enclosed in double quotes.
  • Using the backslash inside double quotes causes malformed paths that don't work.

Here's an example for the template paths:

$accept_order_template = 'D:\websites\domain\mofcart\mofviewcart.html';

  • notice the beginning Drive letter
  • notice the backslashes, not forward slashes
  • notice the path completes with the template file name
  • in mof.conf
    $accept_order_template = 'D:\PATH-TO-WEB\mofcart\mofviewcart.html';
    $validation_template = 'D:\PATH-TO-WEB\mofcart\mofvalidate.html';
    $preview_info_template = 'D:\PATH-TO-WEB\mofcart\mofshipping.html';
    $preview_template = 'D:\PATH-TO-WEB\mofcart\mofsummary.html';

  • in mofpay.conf
    $payment_info_template = 'D:\PATH-TO-WEB\mofcart\mofbilling.html';
    $final_template = 'D:\PATH-TO-WEB\mofcart\mofconfirmation.html';
    $save_invoice_template = 'D:\PATH-TO-WEB\mofcart\mofinvoice.html';


Here's an example for the DATA paths:

$datadirectory = 'D:\PATH-TO-DATA\orderdata\\';
$infodirectory = 'D:\PATH-TO-DATA\orderinfo\\';

$save_invoice_path = 'D:\PATH-TO-WEB\invoices\\';

If you are referencing a directory then you'll need two ending backslashes.  If you don't do this you'll get a Server Error.  What happens is that the backslash has powerful meaning in Perl, and you need to tell Perl that you want a backslash as a literal ending character on the pathway, else, Perl will truncate the ending quote.


Other path problems

All files that would normally run under the native cgi-bin relative location via Unix-Linux should be given full pathways for NT. 

These settings are in the *.conf files

$use_country_list = 'D:\websites\domain\cgi-bin\mcart\countries.txt';
$use_state_list = 'D:\websites\domain\cgi-bin\mcart\states.txt';
$coupon_file = 'D:\websites\domain\cgi-bin\mcart\coupons.txt';


problems in @INC

MOF requires certain support files to load when it runs.  NT may want you to declare these support files in Perl's @INC setting, before you can require them in the script.

At the top beginning lines of each MOF program file you'll need to declare the full absolute paths to the support files MOF will require. Using the example path above, do this:

in mof.cgi (PL) put in these settings (examples only)

BEGIN {
push(@INC, 'D:\websites\domain\cgi-bin\mcart\mof.conf');
push(@INC, 'D:\websites\domain\cgi-bin\mcart\moflib.pl');
}

in mofpay.cgi (PL) put in these settings (examples only)
Note: if you're using any of the extra PlugIns they are declared too

BEGIN {
push(@INC, 'D:\websites\domain\cgi-bin\mcart\mofpay.conf');
push(@INC, 'D:\websites\domain\cgi-bin\mcart\mofpaylib.pl');
push(@INC, 'D:\websites\domain\cgi-bin\mcart\customer.mail');
push(@INC, 'D:\websites\domain\cgi-bin\mcart\merchant.mail');
push(@INC, 'D:\websites\domain\cgi-bin\mcart\invoice.pl');
}


getting mail to work

See the next section on Mail problems. You will need to use the enable Net::SMTP module to have MOF use an external SMTP mailer on NT. Net::SMTP comes in the standard Win32 Perl distribution, so it should be operational on your NT. If not, ask your NT Admin if they will put it in.



MAIL PROBLEMS Sections LIst How Do I ?

is mail turned on ?

In mofpay.conf are these settings enabled ?

# 11. MAILING MERCHANT
$mail_merchant_invoice = 1;

@mail_merchant_addr = ('SEND-ORDERS-TO@YOURSITE.COM');

# 12. MAILING CUSTOMER
$mail_customer_receipt = 1;


Yes, mail is turned on

  1. Set the $ERRORMODE = 0; in mofpay.conf

  2. Run the ?test mode for the mofpay.cgi script:
    Type in the full URL to <mofpay.cgi> on your server, append the "?test" command

    http://www.site.com/cgi-bin/mcart/mofpay.cgi?test

  3. For the "Mail" check line: do you get the message :
    Mail: Cannot find common UNIX, Linux (Qmail or Sendmail) Paths, problem

    -- > Yes : enable Net::SMTP

    1. Open the merchant.mail and customer.mail files in your ASCII editor

    2. around LINE 68 find the section:
      # DO YOU WANT TO USE Net::SMTP EXTERNAL MAILER ?

    3. enable Net::SMTP by uncommenting both these lines:
      and defining the SMTP available to your domain

      $use_external_smtp_server = 'yoursmtp.com';
      use Net::SMTP;

-- > No : enable one of the other sendmail paths for UNIX/Linux

  1. Open the merchant.mail and customer.mail files in your ASCII editor

  2. around LINE 53 find the section:
    # WHERE IS THE LOCATION OF YOUR SENDMAIL ?

  3. change mail_program to a correct path shown in ?test:

    $mail_program = '/usr/lib/sendmail -t';
    $mail_program = '/var/qmail/bin/qmail-inject';

 

MAINTENANCE Sections LIst How Do I ?

MOF uses two directories to read, write, and store data for cart products and shipping information.  MOF creates a separate file for each customer, for both cart products and shipping address information.  The current version 2.4 of MOF does not have any provisions for cleaning out these scratch files.  Scratch files are made in these directories.

../orderdata/
../orderinfo/

You should periodically check these directories, sort them by the date files were created or modified, and delete any files in either of those directories that are older than the corresponding cookies settings you have for the cart and shipping information.

I have several thousand files operating out of one of my directories, so you don't need to worry that you may have accumulated too many files.  Unix-Linux is capable of housing many files without problems.  

You have cookie settings in mof.conf for how long to keep a customer's cart file and shipping information file.  See the sections:

How long (in hours) to hold/initialize cart ?
How long (in hours) to hold/initialize Order summary info ?

Any files that are older than your cookie settings can be safely deleted.  Any scratch files that are older than the cookie settings you have will not be used by MOF because even if the customer does return to your site, their reference number for stored information has been expired as an active cookie.  So go ahead and delete any of these files.

Don't worry.  It's okay to delete all the files if you want to.  The worst that will happen is the customer will have to complete their shipping information again, or they will not have a saved cart.  MOF will know to create them a new file, even if there is a cookie reference, but their file has been deleted.

Security Warning: When deleting files in these directories, do not delete the index.htm file or the .htaccess file (if installed). This will erase security measures installed for these directories



NO FTP FILE PRIVILEGES ON INVOICE FILES UNDER SHARED SSL Sections LIst How Do I ?

When running under shared SSL you may be unable to access, delete, or change the web copies of the invoice files that were created. UNIX/Linux only.

The Cause:

Usually MOF's Back End mofpay.cgi is running under shared SSL, and the server has designated all scripts running thusly as either "www" or some other UID (User ID). So when you log in under you normal FTP User ID, you don't have permissions to mess with those files.

In mofpay.conf enable the setting in the section:

# 13. SAVE WEB COPY OF INVOICE

$set_ssl_chmod = 1;

Enable this switch to have the MOF Back End create invoice files under shared uid (user Id's).  Note this is for Unix-Linux servers only and should not be enabled for NT/Win.

Note: this fixes the problem for any new invoices created under the new setting. It does not change ownership of all the existing files, created under the old setting. Your server Admin must change ownership of those files for you, or delete them for you.

 

UNABLE TO WRITE TO DATAFILE USING DELETE_CART_FINAL Sections LIst How Do I ?

This error is overwhelmingly caused by an incorrect path defined for the $delete_cart_final setting in mofpay.conf. Make sure that path is identical to the $datadirectory setting in mof.conf

In some rare SSL situations, assuming the path is correct, the error may be caused by a user ID situation under SSL:

The error is usually from the same cause as the above error.  You are running under shared SSL and the Front End and Back End are running under different uid (user ID's).  When the Delete Cart Final feature is enabled, then the Back End cannot access the cart data files that were created by the Front End.  Enable this fix switch to have the Front End create shared permissions so both ends of the cart can use those files.  This is for Unix-Linux only.

In mof.conf enable the setting in the section

# Fix shared SSL problem with delete_cart_final
# (1) turn on fix, (0) turn it off
$set_ssl_chmod = 1;

Note: after enabling this fix, delete the scratch files in your ../orderdata/ directory, but do not delete the security files ..

Security Warning: When deleting files in these directories, do not delete the index.htm file or the .htaccess file (if installed). This will erase security measures installed for these directories

 

EXPIRING MOF'S CART Sections LIst How Do I ?

The most professional looking way to have MOF empty the cart contents once an order is finalized is to set the feature for deleting the cart in mofpay.conf.

$delete_cart_final = 1;

A further explanation:

MOF has the ability to keep a visitors cart contents once they leave your site.  You can set the cart holdtime, and the visitors cart will still be there for that duration of time should they return to the site.

When the visitor completes the ordering process and finalizes the invoice, then MOF needs a way of emptying the cart if it is being held as specified in the holdtime setting.  MOF has two ways of doing this: 1. Expire the cookie, and 2. go in and actually empty the cart file that the cookie is referring to.

There is an advantage to holding the cart and physically emptying it only when an order is finalized: a visitor still has those items in their cart if they failed to purchase them, but returned to your site at a later date.  And, even after checkout, the customer's cart remains initialized, limiting possibilities of getting a nocookies message from MOF.

If the $delete_cart_final feature is not enabled, then at final checkout, MOF will forget the cookie associated with that customer's cart, however, the cookie remains until the customer actually closes their browser. If you are running MOF's front end on one server (HTTP) and MOF's back end on separateremote server (HTTPS), then this is the only option you have. You will not be able to use the $delete_cart_final setting.



I GET "UNSECURED ITEMS" MESSAGE UNDER SSL Sections LIst How Do I ?

If you have the MOF front end installed under regular non-secure HTTP protocol, and have the MOF back end installed under the secure HTTPS (SSL) protocol, then you have some meticulous double checking to do. 

The Rule:

Any object that could possibly come up under the SSL connection (being run via mofpay.cgi), must have a reference to the secure HTTPS location of that object.  This means any image, cart buttons, logos, template images, images for products placed in your cart, etc.  You'll have to track down just exactly where the non-compliant object is. Which image is still being called via the non-secure HTTP URL. 

There are three places non-secure images could be coming from.

1. mofpay.conf has a number of references to images for navigation buttons, validation cue images, paypal button, and background images for the Ship To and Bill To tabs on the Final invoice.

2. The two templates used for the Billing information screen and Order confirmation screen have references to images, CSS (if used).

mofbilling.html
mofconfirmation.html

If you want to test to see if those two templates above are secure: Then call them up in your browser independent of the script. Just put in the Full HTTPS URL to those files on the web. Does the template page load without any "insecure items" messages ? If it doesn't load in the plain browser as secure, then it will not load as secure when the script uses it.

3. You may be placing images of your products into the cart using the regular HTTP URL:

src img="HTTP .."

You must reference any of these images from the beginning as under SSL, so that when you get to the Order confirmation the URL is HTTPS.  They will end up however they start out.  The Final Invoice doesn't magically know to convert how you referenced them.

Note: this will not work under Netscape v6.x browsers

Tip: To trouble shoot where the non-secure image is coming from, view the html source for the page that triggers the non-secure message. Then do a search for http, not https.  Look closely at every image reference in the source and make sure if it is an image then it is referenced using HTTPS only.  Any HTTP reference for an image will trigger the dreaded message.  Remember: a reference in the html source may have its origins in either the configuration file, one of the template files, or even from placing pictures into your cart.



EDIT CART BUTTON ON BILLING SCREEN CAUSES ERROR UNDER SSL Sections LIst How Do I ?

When ALLOWED_DOMAINS is enabled and running under SSL:

Under some SSL installations, the cgi referring_url is not present in the environment when mof.cgi is called from a process in mofpay.cgi. It is not present at the server level of the cgi process, and therefore you will get a Domain Not Allowed message if attempting to use the "Edit Cart" option from the Billing information screen.

Disable both of these buttons in mofpay.conf so they do not allow a post back to the cart while on the Billing information page

$menu_viewcart_top = 0;
$menu_editcart_bottom = 0;

 

 

INSTALLING UNDER SSL Sections LIst How Do I ?

General SSL installation problems are usually caused because MOF's various components (configuration files, templates, navigation buttons, template images) are mixed up in some way between the regular HTTP protocols and HTTPS - SSL protocols.

What parts of MOF use SSL ?

The MOF front end does not need to be installed under SSL.  You only need the SSL when accepting live credit card numbers via the MOF Billing information screen.

Some folks install both the MOF front and back ends under SSL, but this this is not only unnecessary, it can be a problem if your shared SSL is crowded and sluggish, as your customer goes back and forth between shopping and the cart.

These are the MOF back end files installed under SSL:
  mofpay.cgi   The Back End Checkout
  mofpay.conf
  mofpaylib.pl
  mofnumber.dat   Support Files
  invoice.pl
  merchant.mail
  customer.mail
  paycountries.txt
  paystates.txt
  mofbilling.html Output templates for the MOF Back End Payment Manager
  mofconfirmation.html
  mofinvoice.html  *

* This particular template is used to save a web copy of the invoice on your web site. The web copy doesn't contain credit card numbers. You can save the copy to a regular HTTP location, or to an SSL location

Important Note: Please see the section above on "UNSECURED ITEMS" for tips on how to set up the MOF cart back end scripts, and support files under SSL so that your customers do not get the "unsecured items" messages.


SSL details:

Shared SSL can be very confusing, because it is done so different between servers. Whatever your SSL situation, this is what you need to accomplish:

  • mof.cgi passes off to SSL (HTTPS) for mofpay.cgi
    mof.conf $paymentfile = 'HTTPS--->URL-TO-MOFPAY.CGI';

  • mofpay.cgi passes back to regular HTTP for mof.cgi
    mofpay.conf $programfile = 'HTTP--->URL-TO-MOF.CGI';

  • mofpay.conf needs all images (src= ) referenced with SSL (HTTPS) URL

  • mofbilling.html (template) all images (src= ) using SSL (HTTPS) URL
  • mofconfirmation.html (template) all images (src= ) using SSL (HTTPS) URL


Note: Servers have varied scenarios for using shared SSL.

A. SSL is mapped to your regular file space, to same directories for cgi-bin and ../mofcart/, which is the easiest to use. If you have your own certificate, this is what you have. Also, some shared SSL is done this way also.

B. SSL is mapped to your account file space, but to separate directories than your regular web files. You may have "secure" directories to run CGI from and html files. In this scenario, you will need to place all images used by the MOF back end, both in the mofpay.conf image references, and images in the two back end templates, into the "secure" html area for files. So, you may have a duplicate set of images, one for the regular HTTP area and one set of images for the HTTPS area.

Say that another way Please:

B. The web server software has a standard HTTP virtual pointer to one set of directories, and an HTTPS virtual pointer to a completely different set of directories.  Both sets are usually off the same root account.  So, in this scenario you'll need to locate the actual files for each protocol in the appropriate set of directories.  That means all images, templates, scripts, and script support files. 

C. Your server's shared SSL may reside on a remote server different than the one your account is on. This is not an optimal situation for running MOF, but you can do it. MOF is split where you can run the front end on one server and the back end on a different one, however, you will not be able to use the $delete_cart_final switch

 

 

These programs are copyright @ MerchantOrderForm.com, MerchantPal.com 2001