Welcome to the www.dtp-aus.com E-Lists program scripts - version 2.2.

The program scripts ELISTS.CGI, ELISTADM.CGI, ELC.CGI, TESTBIN.CGI and associated Perl files were written (c) by Ron F Woolley, Melbourne Australia. Copyright 1998'99,2000. These scripts and associated Perl files CAN BE ALTERED for personal site use OR commercial site use as instructed here in and in our original program files,
BUT whole or portions of code cannot be copied,
AND all program name and copyright notices must remain in all output as is,
AND all of the header notices in the scripts MUST REMAIN intact as is,
AND using the scripts without first reading the README file(s), is prohibited.
IF YOU DO NOT AGREE, destroy all files NOW!

This code MUST NOT be sold, hired, or given/made available to others, in any way.
Changing output English words to another language is permitted for OWN USE ONLY
except program name and copyright notices must remain as is!

Australian copyright is recognised/supported in over 130 countries...
per the Berne Convention and other treaties ( including USA! ) registration not required!

The scripts, code, and supplied associated files remain the property of Ron F Woolley.
NO PROFIT what so ever is to be gained from users of these scripts for their sites use of these scripts, EXCEPT that a reasonable minimal charge for installation may be allowed if installing, as a site developer, for a user on the users site that is not on the developers site. This program must NOT be used for multiple E-Lists users on one site OR offered as a remote service.
Ron Woolley, the author, MUST be notified via the addresses/URLs below if any gain is to be made from the installation of these scripts.

NOTE: If you use these files, you do so entirely at your own risk, and take on full responsibility for the consequences of using the described files. You must first agree that Ron Woolley / HostingNet, the ONLY permitted suppliers of this or accompanying files are exempt from any responsibility for all or any resulting problems, losses or costs caused by your using these or any associated files. IF YOU DISAGREE with any of these requirements for any reason, you must immediately destroy all files.

These program scripts are free to use, but if you use them, a support donation would be appreciated and help in continuing support for free-to-use E-Lists and the creation of other programs for webmasters on the Internet (secure direct on line Visa/Mastercard payment possible).

THESE FILES can only be obtained via the above web addresses,
and MUST NOT BE PASSED ON TO OTHERS in any form by any means what so ever.
This does not contradict any other statements above.

TO KEEP IT FREE, WE NEED your support on link and resource listing sites!


DESCRIPTIONLIST TYPE 5VARIABLESURLs
CompatibilityFORMSINSTALLINGUTILITIES

re-released ** Version 2.2, July 2000: ** rewritten
check every few months for upgrades

History...
E-Lists was first released late 1998 with the dtp-aus.com program "ListMerge" soon following in 1999. Because the two programs were separate, E-Lists harvesting e-mail addresses both for PC download AND Web based mailing and ListMerge capable of mail-merging E-Lists and other address lists to e-mail mail outs "in batches", both programs gained a wide support group of users very quickly.

During the first half of 2000 E-Lists was withdrawn from international availability (for Aus only) and was to be replaced by an advanced "Pro" version.

The local version eventually received some further enhancements and an admin program much larger than previous as a result of a complete rewrite. Continued requests for the previous version brought about what is essentially a re-release of free-to-use E-Lists - E-Lists 2.2; which will still eventually be followed by the advanced Pro version.

Because it is a rewritten program I ask for your support when assessing the program. It has been withheld several times and extensively tested.... but a few little "niggles" may be found.

NOT E Lists!!!
This program, the author, HostingNet, and dtp-aus.com, ARE NOT ASSOCIATED in any way with another business in NSW Australia calling there own server based mail system (not a cgi program) by the name E Lists. We do not support, even care about, the interesting similarity!!

MENU


Low cost installations can be carried out by the author; see program page for details link.
This program must be compiled by Perl versions 5+, on Unix servers with Sendmail

ABOUT

List formats compatible with...
"ennyForms", "VizBook", and "MFormsPro2.2
b" plus of course "ListMerge".

E-Lists is designed for creating e-mail lists for both PC based mail merging programs like the excellent free Pegasus Mail mail merging, and Web based mail merging programs like ListMerge (see separate program).

Three programs with auxiliaries files are supplied - Subscribing, Administration, Remote confirmation.

You can save as many lists as you require from forms on various pages (or to the same list via forms on various pages). Options such as joining newsletter lists, information, or software upgrade notification etc can be considered.

E-Lists is designed to save multiple lists of visitor submitted e-mail addresses to files created in a secure directory (ie a subdirectory of the system protected cgi-bin).

E-Lists also includes a choice of one of five list formats per list for personalised mail merging (plus a sixth for "relayed" list subscribing - see separate section below).

Mentioned in the admin help page is an admin utility program under development enabling PC uploading of lists to the mail lists directory. Simple lists are not a problem BUT mixed list types MUST be avoided. As of July when E-Lists was re-released this utility could be a couple of months away. IF you would like notification by e-mail when this is available, please click on this link when on-line to subscribe (the list will only be used for that purpose and then destroyed).

ListMerge is written as a separate program for mass mail outs and is designed to make use of the E-Lists personalised address lists formats - or plain address only lists. ListMerge also enables you to send mail outs in controlled "batches" allowing for restrictions placed on mass mailing so common today with many hosts mail servers.... using Plain Text OR HTML merging!

Before installation a little bit of planning should be applied... what is the file name extension required for your list names, which directory do you want to save the lists to, and what "field separator" (delimiter) do you prefer. These options are set up in the config file "elistset.pl".
NOTE: if using ennyForms, ListMerge, or VizBook, you will have already decided what these values should be.

UNIQUE FORM REDISPLAY
E-Lists 2.2+ retains the original method of redisplaying a generated form containing the users input when address or missing input errors occur. This is far better for user interaction than having to use a "Back Arrow" to correct mistakes.

ACCESS ADMIN FIRST!
Once all files are installed you should access the admin pages via the supplied "webmster.html" page. This page contains an "ACCESS" password form. If the @referers array in the config file is edited correctly you and others will only be able to access the admin pages via this form ONLY ON YOUR SITE - not remote copies of the form EVEN on YOUR own PC or a browser command line.
NOTE: There are TWO program passwords; one to "ACCESS" the program and allow various windows to then open securely, and the other for "ADMIN Editing" - encrypted via an admin form!

NEW TO VERSION 2.2+..... ALLOWED LISTS
Once in the main admin page you will be presented with a number of program defaults that need checking/editing AND a section for creating "ALLOWED LISTS" data files. This is a major change on previous versions. Now a list cannot be subscribed to UNLESS activated as an "allowed" list. Allowed lists can be deactivated at any time without deleting the actual list of addresses.

Amongst other things this new method of allowed lists removes accessible information from the forms regarding each list, and if "referrer checking" is switched off bogus lists cannot be created remotely.

Double Address Input Checking
Each FORM can contain a second e-mail address entry box enabling a "double input check" similar to the familiar enter twice password checking methods used on many forms. This option can be used to reduce honest mistakes entering addresses!

Each FORM (not list) can be easily configured to tell the program to use YOUR OWN "thanx" or result page ie an often used method is to snap the program back to the originating forms URL!

Each FORM (not list) can be easily configured to tell the program to replace any "Back Arrow" comments with "CLOSE Window" comments should that form be used in a pop-up window.

ADMIN HELP
The main admin page activates a reasonably detailed pop-up HELP WINDOW for all options on the main admin page, and brief comments regarding the second "list specific" admin page that can be accessed once a list is "allowed" (second page options also briefly covered below and are self explanatory once viewed).

Each list, once created/activated as an allowed list, enables the generation of base subscribe form HTML Code containing all options for that list "type" (see below) via admin - ready for you to edit and place in any site pages ("Form" link on main admin page - depends on drop menu choice).

Each list will have its own:
• unique list "name" (from existing but with correct extension) OR created new,
• brief description appearing as reference in all output,
• receivers address (of course all lists could have the same),
• receivers name (personal OR department OR all the same etc),
• an "Organisation" reference IF required (displayed in mail headers).
(keep the description text to just a few simple identifiable words - creating a long letter to "mum" will cause problems where these words are to appear in HTML and e-mail output!!)

Each list will be pre-set to save received input in one of FIVE mail list formats (types):
0. Address,name,date
1. Address,name
2. Name,Address
3. Address only
4. Address,Date.
(each list type is referred to by the above numbers shown in red)

Each list can be Subscribed AND Un-Subscribed to:
• directly as most standard subscriber programs, or
• via a mailed "confirmation URL" (ensuring the address is that of the subscriber).

Each list can be subscribed to with a users choice of either:
• Plain Text receipt of subsequent mail-outs,
• HTML receipt of subsequent mail-outs.
This is a form included option (checkbox or radio buttons) and can be left off any lists form(s).

Each list allows the above mail-out "plain or html" format to be changed at any time simply by the subscriber returning and RE-SUBMITTING their address with the alternative mail-out format chosen.
NOTE: your regular merged mail-out texts should contain reference to this option (IF this option is enabled on the subscriber forms for that list).

Each list has its own texts appearing in the auto-response sent at the time of Subscribing (this text can be left out if so desired).

Each lists text message (above) can contain one or more imbedded "Promo Checking" URLs to "LnkinLite" counted links.... if LnkinLite is installed an access button appears in admin for quick creation/copying/pasting of "named and counted" URL links in to the texts.

Each list can have its own REJECTION LIST of:
• full addresses (wally@whatsit.com),
• domain names (whatsit.com),
• partial domain names (whatsit.) - note trailing dot character!
(rejection list options supporting the many sites that prefer to reject most "free" pop accounts)

Each lists contents can be viewed via admin - displayed 200 maximum per page ensuring all users PC GUI resources / browser page loading capabilities do not crash the view.

Each lists contents can be searched via admin allowing SELECTED DELETIONS - using a search option which can also find matches in names and even dates (if saved as those list types)... same 200 maximum view as above (this search option was in the previous versions but has been improved).

Each list can be Subscribed / UN-Subscribed to via admin (click button pop-up).

Each list can have an address deleted directly without the Un-Subscribe option OR ALL addresses can be deleted at once without deleting the actual list name and associated files.
(remember the latter option when first using various lists for testing / getting acquainted with the program!).

Each list can be subscribed to WITHOUT ACTUALLY SAVING to the list for webmaster testing purposes - simply use the "ACCESS" password instead of an address (pages and e-mails relevant to the list will result - nothing saved).

Each list can also be Copied/Saved to ASCII text delimited files for importing in to spreadsheet and other PC programs. Two file name extensions are possible - ".txt" and ".csv". Delimiter choices etc are also available. This option is supplied should the default list file name extension or delimiting method not be suitable for the importing program!

Site Matching HTML Output
All OUTPUT HTML RESULT/ERROR PAGES can be accessed/copied/edited/pasted/saved via main admin page links.
NOTE: it is strongly suggested you create and test the various list types, cause Subscribe / UN-Subscribe errors (badly spelt addresses, leave out names, etc) to become familiar with the many variations of wording the program generates BEFORE editing these pages.
NOTE: each output page contains imbedded program variables. MAKE SURE they are not damaged/deleted/misspelt when editing!
NOTE: the above testing option has been included primarily to assist testing HTML/e-mail changes!

NOTE: Two pages did not get admin access for editing. They are "waitadd.htm" and "waituns.htm" in the cgi-bin/elistdat/work/ cgi sub/sub dir. These pages only appear IF remote confirmation is activated. Text on the supplied defaults should explain.......

......Both are just simple "generated" html pages you can edit anyway you want to. Just remember links and image tags etc within those pages should be full URLs or relative to the main program script (default cgi-bin). Because they are hidden generated pages and not live linked pages a couple of imbedded field markers are avialable to indicate who and to what list the response refers to.

Javascript and Admin
Not all, but critical admin options are controlled by javascript. It must be enabled for admin use.

GMT Time Zones
This feature is described with more detail in the admin HELP page. The unique dtp-aus.com program-common "GMTime zone" date/time reporting feature accesses one file used by all my programs. Edit via the main admin page - when changed in any one programs admin, all dtp-aus.com programs will be adjusted accordingly.

All relevant files are supplied in one compressed .zip file that includes the recommended directory structure. It is assumed that the Zip file has been uncompressed to a mirror root directory ON YOUR PC creating the default directory structure included in the Zip file. This will ensure the correct line endings are created by your FTP program as each file is uploaded. ALL EXCEPT IMAGE FILES ARE TO BE UPLOADED AS ASCII TEXT - DO NOT use the FTP "auto" function unless you really know how to set it up - one of the common problems difficult to recognise when installing multi sub dir program/file structures!!

You MUST alter all reference to "yourdomain.name" in the "elistset.pl" file, sample forms, webmster.htm, and change the configuration variables, as described in this Readme text.

Example: For Pegasus Mail, you can set up a text file containing the letter you want to send, and merge the items for addressing and personalising each in the list. ie for Pegasus Mail the field markers are two tilde (~) characters surrounding each relevant field number in a record:...

Dear ~2~.
-----------------------------
Here is the latest newsletter from mydomain.site.
Etc… etc…
-----------------------------
Your address was included in the list on the ~3~.
To unsubscribe from this list, enter:
"Unsubscribe ~1~ ~2~"
in the Subject Line and e-mail to you@yourdomain.site.

For a "type 0" list, the merge utility would then replace ~1~ with the "address", ~2~ with the "name", and ~3~ with the date as it sent the letter to each listed recipient.

Delimited text lists can be used with most database programs.

NOTE: You can choose the delimiting character in the config file by changing the value of the variable "$sep". The default is a comma "," ie $sep = ",";

The lists can be used in any way you like and not just for mail merge utilities. The main objective is to get your visitors interested in hearing from you again for what ever promotional reason you can offer – and so returning for further visits (informing them of major updates to a particular page is another option). Just make them feel secure in supplying their details - be informative and open.

The cgi-bin directory and any subdirectories of it should be protected from user access by system default, so they are an ideal place for maximum security (nothing can be done if your server is hacked into). Scripts can access info files, but files cannot be accessed from outside.

INCLUDED or REQUIRED FILES
The Perl language allows the inclusion of extra files containing libraries of commonly accessed sub routines or common lists of script variables etc. These programs "require" a number of files.

Version Image
The main admin page should display an image accessed from dtp-aus.com. This image is to indicate to you the latest version available (saves hassles with e-mail contact) . This image is just that, an image, and NO info is received from the admin page (and such a log would quickly become ginormous and of little value to me!).... it is guaranteed to be just a simple info service for your benifit which will eventually be added to all programs.

UPGRADES
If upgrading the original forms will need minor changes. The original mail lists will be OK, but the program file AND directory structure is very different. Admin is now a separate program. Config file variables have changed. Original subscribe response text files may have to be copied manually and pasted to the admin area for those texts IF the version you have did not use the exact same method (compare files to supplied "list1.txt" sample).

Please NOTE:
If you install and use this program, please contact us at elistsreport@dtp-aus.com with server type details and how the script installed and worked etc.
Any support you can offer via CGI resource/links sites would be appreciated. Helping to "spread the word" will also help to keep this program free-to-use. (we already receive jealous trashing from a few opposition sites for some of our successful programs!)

MENU


LIST TYPE "5"

There is an extra list "type', type "5". This list option allows users with current server based e-mail list processes to add site commonality and form subscribing functionality rather than the usual html coded e-mail address link so easily accessed via spam robots.

The subscribed address is "relayed" on to the server based list process and NO saving or response mailing is performed by E-Lists - that is up to the receiving list process.

E-Lists supports this method but it is not yet fully supported by the admin processes because you have to manually copy/edit/upload a simple data file for each type 5 list (you still have to create an "allowed" list name via admin). If you already use these lists then the options will be obvious.

Please send feedback regarding this option and if enough interest exists extras will be added so as to automate the process fully via admin.

Here is a copy of the supplied master dat file variables for a list named "bonzo" (poor imagination!). The file name is "bonzo.pl. NOTE: you MUST call each such file by the desired file name you give this option as with any other E-Lists list BUT the extension MUST BE ".pl".

• ONLY EDIT between the semi colons " ' " ....... " ' ".
• If an option is not applicable just leave it blank between the semi colons.
• The <%%ADDRS%%> special field marker enables the imbedding of the subscribed address IF required in that variables value.

The three variables for Subscribing and Un-Subscribing are for:
• the address TO the subscriber list,
• the Subject line sent to the subscriber list,
• the Body Text sent to the subscriber list.
• just which is used, or left blank, or contains special words, depends on the list process you are using. ie some require just the word "SUBSCRIBE" in the body text. For others the body text should be empty.
• If you use one of these systems then you will quickly recognise what is needed where.

Subscribing

   $ADDadrs = 'foosub@yourdomain.nme'
   $ADDsubject = 'subscribe <%%ADDRS%%>'
   $ADDbody = 'Subscribe <%%ADDRS%%>'

UN-Subscribing

   $UNSadrs = 'fooUNsub@yourdomain.nme'
   $UNSsubject = 'unsubscribe <%%ADDRS%%>'
   $UNSbody = 'UN-Subscribe <%%UNADDRS%%>'

Please send feedback if used.

MENU


For INTERMEDIATE installation experience - Help / Advice information is available.

The CONFIGURATION VARIABLES in DETAIL

GMT TIME ZONE reference
As with www.dtp-aus.com, Hosting services are being used now that are "remote" from ones local ISP service. Normally this means that all of our scripts etc report dates and times different to that of our local access points, ie our home locality from where we view our sites. To overcome this I use a Perl facility that allows us to use (G)reenwich (M)ean (T)ime with an offset reference reporting in my local time and date. One of the "sets" files, 'gmtset.pl', contains a variable name - $gmtPlusMinus - whose value MUST be set for your local GMT offset. I live in a world time zone 15 hours ahead of that of my Host Servers. Therefore, when I set the variable to 36000 (GMT+10hrs), the lists record, and I view, all dates and times relevant to my locality irrespective of where my Hosting service is. With this method I can move, or my host could move, my Domain server and the results should not change.

Most home / business computer systems have the GMT value listed in the system clock control panel... simple.

The manual calculation is simple. Your local GMT time, multiplied by 60, and multiplied by 60 again. ie 10X60X60. Therefore my variable entry is "$gmtPlusMinus = 36000". If your GMT zone is a negative value, simply include a negative value ie "$gmtPlusMinus = -36000". If you want the dates/times to be the same as the servers, simply enter the value for the servers GMT zone.

US AND BRITISH DATE reporting
E-Lists can save the e-mail address submission time using either the US mm/dd/yyyy format, or the BRITISH DD/mm/yyyy format. In the configuration file, 'elistset.pl', you will find a variable named $dtUS. Leaving this variable value as null, ie '$dtUS = ""' will cause the scripts to use "DD/mm/yyyy". Setting this variable to '$dtUS = "1"' will force 'mm/DD/yyyy'.

CHECKING FOR CORRECT REFERRERS EVEN YOURS
This option in the 'elistset.pl' file allows you create an "array" of Domain names and IP numbers that elists.cgi will respond positively to. By including the acceptable calls to your pages and/or your IP#, ie 'www.yourdomain.com' and yourdomain.com' you effectively stop improper additions to your lists from distant sites (entries are only accepted from LINKS/FORMS ON your site, not remote copies of your pages elsewhere OR browser command lines – they try all the time). The array is named "@referers" and you simply (MUST) enter your preferences in place of the examples. NOTE: The brackets, quotes and commas enclosing each item must be included else an error will occur, ie:

('www.yourdomain.com','yourdomain.com','000.000.000.000',). Leave out the IP# if you do not have a true domain name with a static IP#. "www.ahost.net/mysite/" etc will also work for second level site calls etc. If your scripts are called from the cgi-bin of a domain that is housing your site and your specific scripts are in that domains cgi-bin, you will have to include the cgi-bin also ie: "ahost.net/cgi-bin/".

At this point I will bring your attention to the semi colons ( ; ) appearing at the end of each line in the config files. These MUST remain else an error will occur.

PATHS TO FILES ACCESSED BY SCRIPTS
The defaults used in the ' elistset.pl ' file assume you will place these files in your cgi-bin and add directories to it called "sets", "elistdat" (with sub dirs also), and "maillists". If you have to use other directory names, or your "cgi-bin" has a different name, then you will have to change the paths accordingly; "cgi-yourdomain" is not uncommon. There are two path types that can be used at various times with in a program or script. A relative path (preferred and easiest to use) is a path description to a source, relative to the directory of the program script: ie "jimbo.htm" means that the file being called should be in the same directory. "inone/jimbo.htm" refers to a file that should be in a directory named 'inone' which is a subdirectory within the current directory, and "../jimbo.htm" means that the file should be in a directory one above the current directory, and "../../jimbo.htm" is in a directory two above etc.

A full URL is the same as the path you enter in your browsers address box when typing in a site path that you wish to go to: ie 'http://www.wooz.com/harry.htm'. A relative URL is as above for paths BUT relative to the html page!

Relative paths should NOT begin with a forward slash. Absolute paths SHOULD begin with a forward slash!

For some servers, a simple relative path called by a script is unacceptable, so an absolute path relative to the sites root directory must be called. There are also variations to this description but "web/yourdomain/yourdirectory/jimbo.htm" (example only) is an absolute root path description that works on many servers. Another root absolute path is "/home/yourdomain/www/yourdirectory/jimbo.htm". If you have trouble with accessing the default simple relative paths included in the 'elistset.pl' file, try the absolute root reference ie "/web/yourdomain/cg-bin/counters/hitcount.t" etc. If this is still a problem, look in any installed scripts on your server for a reference, or contact your hosting support staff and send them the 'elistset.pl' file.

NOTE: If you have problems, double check ALL permission's (below) before changing the default paths, unless you know in advance what the paths should be.

MAIL PROGRAM server path
Similar to the Perl program path, this path has to be known for E-Lists to send submission notifications. If you do not know what it is or cannot find reference to in other installed scripts, ask your Host service support staff. The default is $mailprog = "/usr/sbin/sendmail";

GMT Path $gmt_pth
When you edit the GMT zone value from the admin page, the script needs to know the path to the gmtset.pl file. The default is the "sets" sub directory and file name relative to the scripts directory.

CONFIGURATION Path $cnfg_pth
When you edit the configuration values from the admin page, the script needs to know the path to the elistset.pl file. The default is the "sets" sub directory and file name relative to the scripts directory.

ADMIN SUBROUTINES Path $admin_pth
Whenever the lists and admin programs activated, relevant 'require' files are compiled in to memory with the scripts. This variable contains the path to those files.The default is "elistsdat" and must end in a forward slash.

The EXPORT DIRECTORY $xport_pth
This is the directory path (not file) used when exporting a ".txt" or ".csv" copy of a list. The default is "export" and must end in a forward slash.

The AUXILIARY WORK DIRECTORY $aux_pth
This is a directory path (not file) used by the programs for various tasks (and more in the future).
NOTE: It is a SUB DIR OF the "elistsdat" directory. The default is "work" and must end in a forward slash.

WEBMASTER NOTIFY $wbmstr_notify
If you want to be notified whenever a new entry is added to a list, set this variable to one.

ACCESS PASSWORD $theword
You enter your own ACCESS Password here in the elistset.pl file before installing the program, and later change via the admin page at any time. It has TWO PURPOSES!
• To display the admin page
, you MUST use an access form (ie supplied webmster.html) ON YOUR SITE ONLY. The admin pages will appear to allow program/list defaults editing.
• To use the "NO SAVE" subscription and mail TEST OPTION, just enter the "ACCESS" password in a subscriber forms e-mail address input box!

There are TWO program passwords; one to "ACCESS" the program and allow various windows to then open securely (above), and the other for "ADMIN Editing" - encrypted via an admin form!
• The ADMIN Editing password is described on the help page accessed via the main admin page, and is initially nothing (no password).
• If password changes do not take affect then your files are probably not read/write files!
• The ADMIN password file is named "elist.pw" and MUST NOT be manually edited. The created/changed admin password is encrypted and if forgotten, re-upload the original!

ENCRYPTION SEED $bitword
This can ONLY be any TWO alphanumeric characters or "." and "/"..

The ALLOWED LISTS Array @alwFiles
DO NOT EDIT this default. This array of "allowed" lists is managed via admin.

WEBMASTERS E-MAIL ADDRESS and NAME
This is the sites default Address AND Name. Admin options override this value but a default is needed to be sure. NOTE that the supplied default contains TWO VALUES, an Address AND a Name separated by a full colon ":". The program separates these for a more processional e-mail header (the name can be personal, a department, or what ever).

Program required URLs

LISTS PROGRAM URL $prog_url
The value for the variable named "$prog_url" in the config file needs to be altered to include the FULL URL to the elists.cgi script. (use your cgi-bin, not a docs directory, to try and maximise security of saved data).

ADMIN PROGRAM URL $admn_url
The value for the variable named "$admn_url" in the config file needs to be altered to include the FULL URL to the elistsadm.cgi administration script. (Use your cgi-bin, not a docs directory, to try and maximise security of saved data).

REMOTE CONFIRMATION PROGRAM URL $cnfm_url
The value for the variable named "$cnfm_url" in the config file needs to be altered to include the FULL URL to the elc.cgi script. This is the program that responds to remote confirmation of subscriptions (use your cgi-bin, not a docs directory, to try and maximise security of saved data).

LIST UPLOAD PROGRAM URL $uload
NOT YET AVAILABLE - JULY 2000
The value for the variable named "$uload_url" in the config file needs to be altered to include the FULL URL to the eload.cgi script. This program will eventually be released and the admin pages are ready to recognise it once installed. (Use your cgi-bin, not a docs directory, to try and maximise security of saved data).

RETURN PAGE URL $hm_url
The value for this variable in the ' elistset.pl ' file needs to be altered to include the FULL URL Path to your home page or any DEFAULT page that you wish recipients of the courtesy e-mail to come to if they need to remember your site address, OR if they were improperly added to the list without their knowledge. Consider this a backup if the form hidden tag options are omitted/in error.

WEBMASTERS ACCESS PAGE URL $wmsta_url
The value for this variable in the ' elistset.pl ' file returns the webmaster from admin to a preferred return-to page.

Compatibility Variables
if saving to lists via ennyForms, VizBook, MFormsPro, OR using ListMerge
.....these values must match in all program config files!!

The LISTS DIRECTORY $listDir
Where your are to be located. This is the directory path (not file) for the lists created when visitors submit addresses, or when you edit the lists. The default is "maillists" and it must end in a forward slash.

LIST-FILES File Name EXTENSION $list_exten
You can change this (default .elf) to what ever you like. If it helps your Mail Merge utility to recognise the file after FTP down loading, change it as required. REMEMBER that you can also "export" a list to a separate file at any time.

ADDRESS LIST FIELD DELIMITER $sep
You can change this to another character IF required. The default comma will serve most needs, but if using in another language where the comma is an alphanumeric character, OR other lists exist that use another character like the pipe symbol "|", change it accordingly. But know what you are doing and do not change just because you do not like commas! the program could report address errors.

MENU


THE FORM

Single Input Box Forms
You can use a minimum single input box for e-mail addresses plus a submit button, for standard address-only saving to the list(s) (list type "3"; see above). Sample forms are included in the .ZIP file. You how to replace the ‘submit’ button with a bitmap image.

UPGRADES NOTE:
  The ‘hidden’ input tag named "force" is no longer used!!
  The ‘hidden’ input tag named "frmref" is no longer used!!

The form can include several hidden object variations and a number of visible input objects (excluding the buttons). A sample form below shows the "input" names and values that are available.

Double Address Input
• You can include TWO address input boxes to enable the familiar input checking - similarly used on many password forms. By doing this the number of 'innocent' input mistakes can be reduced.

• The hidden value of "df" is the list file name you wish to apply this particular form to. Therefore the df value will be the name of an e-mail list.
This value MUST INCLUDE TWO FULL COLONS: ie value="list1::".
NOTE: the file name value for "df" does not include a file extension – this is added by the program from the extension variable in elistset.pl.

• The hidden value of "return" is the preferred page ( full URL ) you want subscribers to return to after adding or deleting their e-mail address. This value is IMBEDDED in the response/error pages. Not necessary if "thnx" value = "pop" - see below.

• The hidden value of "this" is the full URL of THIS page containing the Subscribe option for THIS particular form (this URL is included as a link in the auto response mail).

• ONLY NEEDED if you have UN-Subscribe forms on separate pages to the Subscribe forms. The hidden value of "undo" is the full URL of the page containing the UN-Subscribe option for this particular form (this URL is included as an UN-Subscribe link in the auto response mail).
NOTE: if this hidden option is not used (most common) then the "this" value is used by default.

TWO OPTION USES - "thnx"
1. The hidden value of "thnx" is the full URL of a page you want to use to override the internal results page - jump straight back to. Most commonly this hidden tag is used to just return the subscriber back to the original form page - no results. But for friendly open interaction with visitors keeping their confidence in your site it is advisable to let them see the result info.
2. Many webmasters keep their visitors on a page when subscribing by using JAVASCRIPT POP-UP WINDOWS via a link to open a form for subscriptions. E-Lists supports this in a simple but useful way by replacing the normal "Back Arrow" request with "CLOSE This Window"!!
To do this, use the the single word "pop" as the value of the "thnx" hidden tag.

ALLOWING/DISALLOWING USER UN-SUBSCRIBING
The sample forms include two radio buttons with the "unsub" name but different values. By simply leaving one of these out of a form, unsubscribing is disabled (or visa versa). Variable changes are not needed.

HTML MAIL-OUTS or PLAIN TEXT?
Any form can allow the user to select whether they want your merged lists mail-outs in Plain Text (standard e-mail) OR as an HTML page (this is a "ListMerge" program option). Simply add two radio buttons as shown - or one checkbox.
NOTE: Visitors can return at any time to change between HTML or Plain Text by re-Subscribing and choosing the alternative. You should mention this in your mail merging texts IF using ListMerge!

This form is supplied as a sample in the Zip file. Add colour etc as desired. Remove objects as required. Remember: The special input names like "from" and "fstname", must remain as is also, df = the list file name for that form - without an extension - as activated in the admin.

<form align="center" method="POST" action="http://yourdomain.name/cgi-bin/elists.cgi">
   <input type="hidden" name="df" value="listname::">
   <input type="hidden" name="return" value="http://yourdomain.name/linkedreturnpage.htm">
   <input type="hidden"name="this" value="http://yourdomain.name/samepage.htm">
   <input type="hidden"name="undo" value="http://yourdomain.name/if_unsubpage.htm">
   <input type="hidden"name="thnx" value="http://yourdomain.name/yourresultpage.htm">
 OR
   <input type="hidden"name="thnx" value="pop">

<table border="0" width="480" cellspacing="0" cellpadding="2">
<tr><td width="100%" align="center"><small>Enter <b>your Name</b></small><br>
   <input type="text" name="fstname" value="" size="20" maxlength="30"></td>
</tr><tr>
<td width="100%" align="center"><small>Enter your <b>E-mail Address</b></small><Br>
   <input type="text" name="from" value="" size="25" maxlength="75"></td>
</tr><tr>
<td width="100%" align="center"><small>REPEAT <b>E-mail Address</b></small><Br>
   <input type="text" name="fromChk" value="" size="25" maxlength="75"></td>
</tr><tr>
<td width="100%" align="center"><small> Subscribe</small>
   <input type="radio" name="unsub" value="0" checked> <small>UN-Subscribe</small>
   <input type="radio" name="unsub" value="1"></td>
</tr><tr>
<td width="100%" align="center"><small>News letter as </small>
   <input type="radio" name="ishtml" value="0" checked> <small>Plain Text </small>
   <input type="radio" name="ishtml" value="htm"> <small>HTML</small></td>
</tr><tr>     
<td width="590" align="center">    
   <input type="submit" value=" Submit " name="send">
   <input type="reset" value="clear"></td>
</tr></table>
</form>

Hidden input tag when no visible subscribe buttons are used:
   <input type="hidden" value="0" name="unsub">
Single checkbox tag replacing Plain/HTML buttons
:
   <input type="checkbox" name="ishtml" value="htm">

There is this and other sample forms in the Zip file (form(#).htm).

MENU


SETUP & FTP POSTING

Run "testbin.cgi" to ascertain the correct Perl path for v5+ (5.003+ preferred), and hopefully check the path to "Sendmail". If you understand chmod values then check/alter "makedir.cgi" and run it. Prepare the "elistset.pl" config file also with help from the detailed config variables described above.

THE PATH TO PERL
At the top of each script (and must remain as the first line) is a default path to the Perl program on your host server. This can vary slightly between UNIX servers. If you have problems running the scripts, check with your host support staff about the correct path described in this line. The default entry is "#!/usr/bin/perl" and another common variation is "#!/usr/local/bin/perl". In Perl scripts the hash sign "#" character comments out the code on a line starting with this character. Here it has a special meaning to Perl and MUST remain. Check with other installed scripts also if you do not know what this line should look like.
NOTE: one path to perl MAY work for simple programs BUT not be suitable for complex programs using cgi sub dirs etc. KNOW your server and the correct default or latest version path!!

SCRIPT and FILES PERMISSIONS
Each list file must be given read and write permissions (chmod 666). The directory that they are placed in will also have to have read and write permissions. Either read and write chmod 766 (r+w) or possibly chmod 777 (r+w+x) should work - try the first before the latter. The other directories should also be given the same permissions as the mailists directory.
• a few servers will be set up to allow read/write via a default manually created directory (even 755!)
• a few servers will set a 766 value automatically to 777!
• a very few servers have strange permissions options and must be known via the hosts help pages.
• NO programmer can remotely tell you exactly what permissions will be required. Host engineers sometimes create their own ideas of server/site dir and file permissions.

UP LOADING FILES (Posting)
The script must be given read and execute permissions (r+x).

CGI-BIN dir permissions are set by the server and no attempt should be made to change them. Should you have to use another directory, AND your server allows the execution of Perl CGI scripts in other directories, then that directory should be set with read and execute permissions - chmod 755 (r+x). NOTE: on most sites, using a NON server created/protected cgi-bin or html docs directory will allow hacker robots access to your data files and client details - be warned.

By far the biggest problems faced when installing scripts are firstly the file transport encoding used and secondly the permissions settings set for both files and new directories. The 'AUTO" function in most FTP programs should only be used IF you know how and bother to set them up - FTP FILES MANUALLY!!

Bitmap images must be sent to the server using the "Binary" protocol. Text files, ie html pages, CGI SCRIPTS and require files, MUST be sent in "ASCII" format. (ALL E_LISTS FILES are ASCII text).

Failure to do this will result in a server failing to recognise and execute the scripts. Although often referred to as programs, scripts must be compiled before they do anything. As an example, files with the .EXE extension on programs that are installed on Wintel machines are pre-compiled binary executable programs. Perl scripts on the other hand are compiled in memory by Perl every time before they can be executed. The script (text) must be in ASCII text format for the interpreter to be able to read it.

I REPEAT: Up load scripts / text files as "ASCII" files, images as "Binary".

So, assuming the default directory structure is used, you will up load into:

Directory:
cgi-bin (server)
elists.cgi, elistadm.cgi, elc.cgi (chmod 755)
cgi-bin/sets (chmod 766 or 777)
ALL files (chmod 666 or 766 or 777)
cgi-bin/maillists (chmod 766 or 777)
program should be able to create/manage the files OK
cgi-bin/elistsdat (chmod 766 or 777)
ALL files (chmod 666 or 766 or 777)
cgi-bin/elistsdat/work (chmod 766 or 777)
ALL files (chmod 666 or 766 or 777)
cgi-bin/elistsdat/export (chmod 766 or 777)
program should be able to create/manage the files OK

If you must use another directory for the ??.set files, you must also change the path to those files at the top of the code in three program ".cgi" files. ie::

#--- Alter these two paths only, if needed! ------------#
    if (-s "sets/gmtset.pl") {require "sets/gmtset.pl";} else {...........
    if (-s "sets/elistset.pl") {require "sets/elistset.pl";} else {...........
#--- Do Not make any changes below this line. ----------#

Accessing ADMIN
To display the admin page
, simply enter your access password into the/a "webmster.html" form. The admin page will appear and allow you to edit the program and lists data.

MENU


UTILITIES

UTILITY testbin.cgi
I have created a simple utility script that can be placed in your cgi-bin and run from your browsers command line before E-Lists installation. This script will, in almost all cases, detect the Perl version you are using and report its findings. If it reports version 4 as the only default, then you must ask your Host Service for the correct path to Perl 5 (Always top and FIRST line in all scripts). E-Lists is a Perl 5 program for Unix servers using Sendmail.

The latest version of testbin.cgi attempts to list all Perl paths on your server AND obtain path information to Sendmail. note: Not all servers report either/both of these. NOTE: To check the Sendmail path you need to change the programs URL listed near the top of the testbin.cgi code.

So!
Change the Perl path at the very top of the program code - or try the default.
Change the programs URL, listed near the top of the testbin.cgi code.
Place "testbin.cgi" in your cgi-bin directory and chmod 755 (7=r+w+x, 5=r+x).
Then run from a browser command line, ie http://www.yourdomain.path/cgi-bin/testbin.cgi

UTILITY makedir.cgi - "relative" paths are the easiest to use and manage!
This is also a good learning tool (about your server site). I have created a simple utility script that can be placed in your cgi-bin and run from your browsers command line after "testbin.cgi". With so many files involved it can guarantee correct naming, and quite a lot can be learned by getting it to work properly.

If your server allows directory creation via cgi scripts (not all do), then this utility will attempt to create the default (recommended) directories and file names for you, and set the permissions. It is unprotected and there is no guarantee that it will work; try it at your own risk (disclaimer only). It works well on many sites and we also use it for all installations - often learn a bit about the site too.

Try installing and running this script first. It will report success or failure when creating the files/directories and prove the correctness of your Perl Path", plus indicate that the default relative paths will work OK. If the default urls/paths are not used, then you will have to change them first. IF nothing works trying to create the cgi sub dirs, create them manually, note "# comments" against dir names, and run again to then see if files are created - good way to prove relative paths.

To use it, make sure the "Perl Path" at the top of the script is correct. NOTE: the default Sub-Directory permissions are set to 766. Change these values to 777 if your site so requires BEFORE running the script. If running the script is successful, you only have to FTP your supplied files over the new empty ones. (note: for security reasons, makedir does NOT prepare an empty file for the cgi scripts, you must upload them (as ascii) and set chmod 755 your self).

The default permissions for all cgi sub dir auxilliary files is chmod 666.

Once the run is comeplete, delete the program immediately because it has no input protection and could be run again by some low-life wanting to cause mischief

So!
Check that the default permissions values are correct for your cgi sub directory R/W permissions.
Place "makedir.cgi" in your cgi-bin directory and chmod 755 (7=r+w+x, 5=r+x).
Then run from a browser command line, ie:
http://www.yourdomain.path/cgi-bin/makedir.cgi

Note: Only occasionaly a server becomes really padantic! if a program creates directories with incorrect permissions (a sort of security lock-out), not allowing acces to those directories via FTP afterwards. To overcome, simply change the permissions in the program and run again.

Enjoy - & please let me know how you get on with this script, how/what server type it installed to.
      Ron

MENU