                            BASIC INFORMATION

Name: HAMcards
Version: 1.2
Last Modified: Dec 8, 1998

                               DESCRIPTION

This script will allow you to offer the service of making electronic
cards on your web site.  Once installed all that is needed is for you to 
develop the look and feel of you ecard service by making HTML
templates.  Users can preview, send (notice by email), and pick up their 
cards from your web site.  The script can now send notices at a later date
and act as a reminder service.


                        MAJOR BUG FIXES IN THIS  RELEASE
This release will fix many of the bugs experienced on non unix systems and
users who sent mail using the smtp_server instead of sendmail(or such).
See the Readme File For a list of the bug fixes

                      Upgrading from HAMcards 1.0 Beta 2 or higher?
If so follow the instructions in the update.txt file for easier updating.


                         COPYRIGHT INFORMATION
This application was written by Lee Huffman of HAMnet Consulting. You
may make modifications to the script as long as you inform HAMnet
Consulting of the changes so they may be incorporated into future versions.
You may not sale the HAMcards scripts.
Also: IF YOU CHANGE A LIBRARY FILE PLEASE GIVE IT A NEW NAME
SO PROBLEMS WITH OTHER CURRENT OR FUTURE SCRIPTS THAT USE
THE LIBRARY FILE DO NOT OCCUR

Finally, PLEASE SEND WORKING URL's to hamcards@hamnetcenter.com.
HAMnet will maintain a list of how the scripts are used around the world.


				 			SUPPORT

This script comes with no guarantees or warranties.  HAMnet Consulting
is not responsible for any problems obtained by using these scripts.

You may email to support@hamnetcenter.com or use the new support forums
at : 
   http://www.hamnetcenter.com/hamsupport/

Bug reports are greatly appreciated.  When inquiring about bugs or
installation problems make sure to include the following bits of information
(I may not respond to your email if you do not answer ALL of the following
questions):

1. What type of Web server are you running?
2. What type of Operating System is the Web server running on?

3. What is the "exact" error message from the Web?
4. What is the "exact" error message in your web server's error log?
5. What is the "exact" error message you receive when running the script
       from the command line.

6. Are you running this script on an ISP?  If so, what is the email
       address of the Sysadmin there?
7. Are you using a virtual server setup?  If so, what is the root path set
       in your Web server's environment?

8. In which directory is the Perl interpreter located?
9. In which directory is sendmail located (if you are using a script which
       demands use of sendmail)

Again, I MAY NOT ANSWER YOUR QUESTION unless you have answered all nine of
these questions.


                BASIC INSTALLATION (DOWNLOADING THE SCRIPT)

It is recommended that you point your Web browser to "HAMnet Consulting"
to get the latest version of this script.  The Script  is
located at the following URL:

                    http://www.hamnetcenter.com/


                BASIC INSTALLATION (UNARCHIVING THE APPLICATION)

Once you have downloaded the TAR file (a single file containing all
associated files in their relative positions under the root directory),
transfer the TAR file to an executable directory on your web server and
untar them.  On UNIX systems, you may type the following at the
command line:

                          tar xvfp filename.tar

       (If you are using a non-UNIX Operating System, you may 
       download a TAR/UNTAR program by pointing your Web browser
       to http://www.shareware.com).


                 BASIC INSTALLATION (SETTING PERMISSIONS)

Your Web server must have permission to read, write or execute as needed.
Each sub-directory and file in the application has its own correct
permissions level associated with it.  Once you have unarchived (UNTAR)
the application, you must then set the correct permissions.  On UNIX
systems, you will use the "chmod" command.   The following table is a
quick guide to setting permissions for UNIX servers.

	PERMISSION	COMMAND
	rwxrwxrwx 	chmod 777 filename		
	rwxrwxr-x	chmod 775 filename
	rwxr-xr-x	chmod 755 filename
	rw-rw-r--	chmod 664 filename
	rw-r--r--	chmod 644 filename

	Note: Not setting your permissions correctly is the 
	NUMBER 1 reason why installations fail.  Take time to 
	get this right.

The actual permissions required for the subdirectories and files used by
this application are listed in the next section.

         BASIC INSTALLATION (FILES, DIRECTORIES, AND PERMISSIONS)

The TAR file will then expand into a root directory called HAMweather.
HAMweather will contain several sub-directories and several files.  
The diagram below depicts the directory structure as well as the
permissions which must be applied to the files and subdirectories used by
the application.

HAMcards Root Directory (drwxr-xr-x)
   |____database Sub-directory (drwxrwxrwx)
   |        |___cards.dbase (-rwxrwxrwx)
   |        |___multidemo.dbase (-rwxrwxrwx) (DEMO ONLY)
   |
   |___demos Sub-directory (drwxr-xr-x) (DEMO ONLY)
   |
   |___hamlib Sub-directory (drwxr-xr-x)
   |       |___date.pl (-rwxr-xr-x)
   |       |___hamcardslib.pl (-rwxr-xr-x)
   |       |___hamlib.pl (-rwxr-xr-x)
   |
   |___templates Sub-directory (drwxr-xr-x)
   |       |___cardsent.html (-rwxr-xr-x)
   |       |___mail.txt (-rwxr-xr-x)
   |       |___notify_email.txt (-rwxr-xr-x)
   |       |___missing.html (-rwxr-xr-x)
   |       |___pickup.html (-rwxr-xr-x)
   |       |___preview.html (-rwxr-xr-x)
   |       |___required.html (-rwxr-xr-x)
   |       |___sendlater.html (-rwxr-xr-x)
   |
   |___logs Sub-directory (drwxrwxrwx)
   |   
   |____images Sub-directory (drwxr-xr-x)
   |
   |____changes.txt (-rw-r--r--)
   |____readme.txt (-rw-r--r--)
   |
   |____hamcards.cgi (-rwxr-xr-x)
   |
   |____singlepagedemo.html (-rw-r--r--)   
   |____index.html


hamcard is the root directory for the application and must have its
	permissions set to be readable and executable by the web server.

database is a subdirectory used to hold the card database(s). This directory
needs to be readable & writtable by the server.

cards.dbase is the name of the card database used by the script. This file
         needs to be readable &writable by the server.

demos is a subdirectory used by the multi-page  and reminder demos. All things
      in this directory need to be readable & executable by the server. the 
      individual hamcards.cgi need to be executable by the server as well

hamlib is the subdirectory that holds the library files.  This directory needs to be
      readable and executable by the server.

   date.pl is a standard library file that converts  Julian dates. This file needs to be
         readable/executable by the server

   hamcardslib.pl is the library file containing all the HAMcards routines. This file
         needs to be readable and executable by the server.

   hamlib.pl is a standard HAMnet library file. This file needs to be readable and
         executable by the server.

templates is the subdirectory containing the various html and mail templates. this 
      directory needs to be readable by the server.

   cardsent.html is the HTML template used when telling the card maker
         that the card has been sent to the recipient

   display.html is the HTML template used to display the card to the user picking
         it up.

   mail.txt is the mail template used when sending a notification email to the 
         card receiver.
         
   notify_email.txt is the mail template used when sending  the card sender a 
         pickup notification when the reciever picks up the card.

   missing.html is the HTML template used when a card can not be found
         during pickup

   pickup.html is the HTML template used to allow the user to enter the card number
         needed to pickup the card

   preview.html is the HTML template used when previewing the card
         to the maker

   required.html is the HTML template used when a required input is missing.

   sendlater.html is the HTML template used in place of cardsent.html
         when the user has a card to be sent at a later date.

images is a subdirectory used to hold the various card images.  This
	directory need not be writable by the web server.

changes.txt is the file that contains all the changes from previous versions

readme.txt is this file.

hamcards.cgi is the setup/launch of the HAMcards system.  this script needs to be 
      set to readable and executable by the server.

      The various variables in hamcards.cgi are listed as follows:

      $OS is set to the current OS "NT" or "UNIX" this is only used to stop NT from 
            emailing.. And for testing purposes.  IF you are on UNIX set to UNIX.. 
            If you are on NT or WIN 95/98 set it to "NT".

      $mail_mode is set to the mode for mailign you want to use.  To use the standard 
            mode of using the application set by $mail_prog (usually sendmail) leave this
            variable either undefined or set to 0.  If you want to use an smtp server to
            send mail set to 1.. WIndows users should use this latter mode.

      $smtp_server is set to the smtp server to use to send mail when $mail_mode is 
            set to mode 1.
            
      $admin_email ios set to the email of the card system administrator. This email is
            also used as the return address for the pickup notification that is sent to the
            card sender when the card is picked up.
            
      $allow_pickup_notification is used to allow pickup notificatons to be sent to the
            card sender when the reciever pics the card up.  (also the form 
            element 'PickupNotification' must be  set to any value when card is posted.. 
            use a checkbox so sender can choose to have a notification sent to him.
            $allow_pickup_notification = 0  no notifications sent
            $allow_pickup_notification = 1 notifications sent remember this is 
            a pickup notification that is sent to the card sender to let them know the 
            card was picked up.  This is not the notification sent to the reciever
            (that notification can not be turned off)
            
      $notification_subject is used to allow you to provide a custom subject for
            the pickup notification emails

      $script_loc is set to the URL of the hamcards.cgi script. This is used to replace 
            %%scriptloc%% in the templates.

      $hamlib_path is set to the full path (minus the trailing slash) of the hamlib directory

      $html_template_path is set to the full path (minus the trailing slash) of the directory
            that contains the html templates.

      $email_template_path is set to the full path (minus the trailing slash) of the directory
            that contains the email notification template.
      
      $notify_template is set to the the name of the html mail template that is used to 
            send a notification to the Card sender that the card was picked up.. Only used if 
            $allow_pickup_notification is set to 1.

      $card_dbase_path is set to the full path (minus the trailing slash) of the directory
            that contains the databases.

      $lock_file_path is set to the full path (minus the trailing slash) of the directory
            that will contain the lock files (Files used to keep more than one person from 
            changing the database at once)

      $mail_prog is set to the full path to the mail program (sendmail)

      $preview_template is set to the name of the preview template

      $display_template is set to the name of the template used to display the card 
            at pickup time.

      $sent_template is set to the name of the template used to let user know the card 
            has been accepted and notification has been sent.

      $sendlater_template is set to the name of the template used to let the user know the
            card has been accepted but notification will be sent at the given date.

      $missing_req is set to the name of the template to let the user know that a card could
            not be found in the database

      $required_template is set to the name of the template used if the user did not 
            input all required data

      $mail_template is set to the template used to send the email notifications

      $dbase_name is set to the name of the card database.

      $allow_html is set to 0 to block user from using html in input. If it is set to 1 then
            HAMcards will allow the user to input html code to be displayed on the 
            card.  The usage in mode 1 does increase the security risks.

      $max_age is set to the number of days to keep cards in the database. Cards that
            are "SendLater" will be kept for the max age after notification is sent

      $delete_old_cards_mode is used to set the  mode for deleting old cards Also
            this is when HAMcards will check if any "SendLater" cards need to be sent.
             0 = delete out of date cards whenever a new card is posted
             1 = only delete old card when script is with no Do..ie from telnet
                    this allows you to automate this process with a cron job
                    thus not wasting server usage whenever a card is posted.
            2 = same as one but started from a web browser...you would
                    just use the URL to the script & it will delete out of date cards

      @required is set to any form fields that you want required at all times
            except during  a "passvar" method.  All field names in this list will be
            checked for existence. If the field does not exist then the $required_template
            will be displayed. The list should be setup as follows:
            @required('Item1', 'Item2', 'Item3');
            Remember that Case is significant.  "Item" is not the same as "item".

singlepagedemo.html is the classic one page HAMcards demo front page

index.html is the html page that allow you to check out the three demos:
         Single Page, Multi-Page and Reminder System.

            How The Templates Work

HAMcards uses HTML templates so that the web developers can easily
make the HAMcards site to their needs buy just developing a few web pages.
It is the ultimate goal of HAMcards to allow a developer to use the same
script for more that one card site just by using html templates.

The template system is easy to use and allows for great flexibility. All
you need to do is develop your html page for taking in the needed card
information.  This html page will use a form to post the information (the
form fields) to the hamcards.cgi script.  HAMcards will then process
the information and then displaying the appropriate html template and
filling in the form information in to it.

For instance: if you information page (where you gather the information)
takes in the fields 
   PictureURL, RName, REmail, SName, SEmail, SpecialMessage

If you want your HTML templates to display this information back in any of
your templates you will just place the formfield name wher you want it
surrounded by a two percent(%) signs on each side.

so to make the SpecialMessage appear in the preview and the pickup
html output.. just place %%SpecialMessage%% in the html template
where you want the information.

The Following Template definitions have are added by default in HAMcards:

%%scriptloc%% will be replaced by the hamcards.cgi URL

The next four template definitions are for the preview method only: Mainly
for the purpose of generating the current date for a SendLater select box.

%%CurrentMonth%% will be replaced by the current month number
%%CurrentMonthName%% will be replaced by the name of the current month
%%CurrentDay%% will be replaced by the current day of the month
%%CurrentYear%% will be replaced by the current year.

This works for both the html templates and the mail notification template.

You may use any fields you like.. With the following presets used by
the hamcards.cgi script.

RName = Receiver Name
REmail = Reciever Email
SName = Sender Name
SEmail = Sender Email
Greeting = Greeting
cGreeting = Custom Greeting: if the cGreeting field is not null then it
                     will replace the Greeting
Closing = Closing
cClosing = Custom Closing: if the cCloding field is not null then it 
                     will replace the Closing
CardID = the id of the card wanted
Do = Tells HAMscripts what method to perform(What to do)
NextPage = Tells HAMscript what template to display next during a
                     "passvar" method
Required = Required Fields.  
When = During the Send method defines when card should be sent... Now or Later
SendMonth = Month to send card
SendDay = day to sent card
SendYear = the year to send card
PickupNotification = Whether a pickup notification will be sent to the card sender
                     when the card is picked up.

You can add more or less to these as you like and use them in your templates.
You also can require the user to fill out certain fields by placing them in  a 
hidden field by the name of Required.
example:
<input hidden name="Required" value="Greeting,Closing,SEmail">

This would require the user to have the field Greeting, Closing and SEmail
completed.  If they are not completed then the template in $missing_req will
be outputted.

The difference between  the @required variable in the hamcard.cgi and the 
Required form element are as follows: 
@required make sure that the fields in its list are present at every request
      on HAMcards except during a "passvar"method (When Do=passvar)
The Required field only makes sure the fields on that page/request to 
      HAMcards are present.  Thus this can be different from template to 
      template.  Also Required field is checked at all stages of use of HAMcards
      even during a passvar method (When Do=passvar)

The HAMcards does require the following fields  when posting a new card:
       REmail
This is because we at least have to know the email of the recipient.

METHODS
Also the following command placed in a field with the name of Do are used 
to make the script perform its various tasks:

   Do=preview  : Hamcards.cgi will check for required fields and output the 
                            preview.

   Do=send        : Hamcards.cgi will store the card in the database, email the
                             notification to the recipient and  output the card sent template.
                             See  SENDING CARDS LATER for greater detail on this method

   Do=pickup     : HAMcards.cgi will look for the card in the data base identified by
                            the CardID field.  If found it will display the card using the
                             $display.html template. If it does not find  the card it will output the
                            not_found template.

   Do=passvar     : HAMcards will just process the required field if there is one and 
                              then output the template in named in the field NextPage.  The template
                              must be in the template directory. example of NextPage set on a form
                              <input type='hidden' name='NextPage' value='step2.html'>.
                              Also, all fields from current page will be transfered to the new
                              template page following the preceding template rules.

                     PCIKUP NOTIFICATION
New to the final release of HAMcards 1.0 is the ability for Pickup notifications to be sent
to the card sender when the reciever picks up the card.  This feature was requested by 
many and thus was added.  THere isa two pronged approach to using this feature though.
You must first set the $allow_pickup_notification variable to the value of 1.  Next 
there must be a form element by the name of "PickupNotification" set to "yes" when
the form is posted.  The reason for this second requirement is to allow you to provide a
checkbox to the card sender to decide whether they want a pickup notification.  You may
an example of this in the demo.  If you want to force pickup notifications to be sent to 
all card senders then just make a hidden input field on the preview screen setting the
PickupNotification form element to "yes".  ALso if you are using the HAMcards script
as a reminder service it does make since to use this mode, for users wil lnot be checking
the reminder anyway.

                     SENDING CARDS LATER
HAMcards has  the ability to make a card now and have it send the card
at a later date. During the Send method  HAMcards will look for the "When" form field
if it equals "Now" or doesn't exist then the card will be accepted and notification sent then.
if the "When" form field equals "Later" then HAMcards will process the send date stored in 
"SendMonth", "SendDay", and "SendYear".  If the send date is previous to current date an error
will be displayed.  if the send date  is equal to the current date then HAMcards will handle
the card as if "When" had equaled "Now". Finally, if the send date is after the current date
then the card will be stored in the database

HAMcards will check to see if any "SendLater" cards in the database need to be sent & 
send them during the database "delete out of date cards" routine.  so the Deleting old cards should 
be automated if possible to insure  that all Sendlater cards are sent on time.

           DELETING OUT OF DATE CARDS and SENDING "SENDLATER" CARDS
HAMcards also has  the ability to delete old cards out of the database.. This is also
a good time to check to see if any sendlater cards need to be sent. If so they are.

HAMcards gives you three ways to perform the cleanup/sendlater routine.  The method is 
set by the $delete_old_cards_mode variable:

      $delete_old_cards_mode is used to set the  mode for deleting old cards Also
            this is when HAMcards will check if any "SendLater" cards need to be sent.
             0 = delete out of date cards whenever a new card is posted(Once per day)
             1 = only delete old card when script is with no Do..ie from telnet
                    this allows you to automate this process with a cron job
                    thus not wasting server usage whenever a card is posted.
            2 = same as one but started from a web browser...you would
                    just use the URL to the script & it will delete out of date cards

In mode 0... The first time a person "post a new card to send" each day the database is cleaned.  This is
      is a good method for slow site or sites that don't have access to cron jobs
In mode 1...  This mode is for setting a cron job (crontab) to automate the process.. .Once a day
      is should suffice... Just  have the crontab run "hamcards.cgi" and the script will handle the rest.
In mode 2..  This mode was only given for those who do not have access to setting cron jobs, have
      minimal used site or  have a busy site and cant accept the wasted CPU usage of mode 0.
      All you need to do is access the script.. from a web browser.. "http://yourdomain.com/hamcards.cgi"
      If the database is big and/or a lot of SendLater cards need to be sent then the process could take 
      a while before completion.

You should remember that During the cleaning out of the database that "SendLater" cards are sent if need be.
So choose your method wisely and try to have it performed at least once a day.

			   RUNNING THE SCRIPT
Make sure that you are using Perl 5.0 or better and that the first line of the 
executable points to the location of perl on your server.  For example, if your
Perl interpreter is located in the "/usr/local/sbin" directory, you should 
change the first line to read:

			#!/usr/local/sbin/perl 




