Welcome to the www.dtp-aus.com ListMerge script - version 2.0
IMPORTANT INFORMATION THAT MUST BE READ IF YOU WANT TO USE THESE SCRIPTS

The program "LSTMRGE.CGI" was written (c) by Ron F Woolley, Melbourne Australia. Copyright 1998'99 2000. This script can be altered for private site use or commercial site use, EXCEPT THAT:
ALL COPYRIGHT NOTICES must remain in the code, visible on all output pages,
AND ALL of the header notices MUST REMAIN intact as is,
AND using the script without first reading the README.HTM, is prohibited.

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

The code, scripts and associated files REMAIN the property of Ron F Woolley.

NO PROFIT what so ever is to be gained from users of these scripts for installation of these scripts, except that a reasonable minimal charge for installation MAY be allowed. Supply, per installation, is directly from dtp-aus.com ONLY. Remote hosting of this program/resources is strictly not allowed. Installation on anothers behalf of altered ListMerge code or copy of parts of ListMerge code is strictly forbidden. Ron Woolley, the author, MUST be notified via the addresses/URLs below if any charge is to be applied for 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 supplier of this and/or accompanying files is 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 the included requirements, you must IMMEDIATELY DESTROY ALL FILES.

This programs scripts are free to use - Copyright notices must remain visible as is.

This programs scripts are free-to-use, but if you use them, a donation to the author would be appreciated and help in continuing support for ListMerge and the creation of other scripts for users of the internet.
    On line Visa / MasterCard payments are available for donations and low cost installations.

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 - ensure you have the latest.


Low cost installations can be carried out by the author; see program page for details link.
This program is written to be compiled by Perl versions 5+ on Unix servers
VARIABLESSAFE BATCH MAILINGSETTING UPINSTALLINGUTILITIES

major** Version 2.0, March 4, 2000 **changes
check every few months for upgrades

REQUIRES UNIX and SENDMAIL!

Users of **E-Lists prior to v2.2 will need to upgrade E-Lists also
**E-Lists v2.2 re-released mid June 2000

ABOUT

( version 2.0 major upgrade )
v2.0 includes NEW variables, NEW file names,
allowing you to choose the delimiter used to separate the address list feilds (ListMerge copy of original) - AND enables the detection of other mail lists using one of four different delimiters. E-Lists 2.0 (when available) and the next upgrade to ennyForms will allow user selection of either plain text e-mails OR HTML e-mails. ListMerge v2 now detects those list fields and can send plain text or HTML as appropriate to each list address.

Help dtp-aus.com if you can! - a major free www tutorial resource... June 2000
Soon after v2.0 was released ListMerge climbed near the top three or four in its listing at the cgi.resourceindex. Soon after AND 4 or 5 times since after steady climbing back from user support ListMerge receives several uncharacteristic 1 and 2 votes to repeatedly trash it well back down the list. We do not promote ListMerge as the best of its type but users have tried to support the program.
Should you use this program and find it useful, and to help combat this idiot (or opposition organisation?), I would ask you to not only vote for ListMerge but if a Registered Voter submit a written registered comment. Written registered comments are the only way to help combat such stupidity. We do not like to ask for extra help but you the www users are the only ones able to help keep a sense of reality/honesty amongst all the trashy happenings that occur on the Internet - and the cgi.resourceindex site is looked upon for honest appraisals; not childish prejudice - and thanks to Matt Wright for his recent enlightning letter 14th June.

ListMerge has ONE main requirement for names of original lists that it copies. They MUST NOT contain an hyphen character "-", also called the "minus sign".

upgrading - see below
Except for the data files that have to be deleted and recreated by the program, ALL files have been renamed so the older program can remain until installation is proved.

ListMerge has always created its own safe copies of E-Mail lists.

Two new list formats have been added to v2.+
List "formats" are an E-Lists and ennyForms subscriber thing where original lists can be created with extra subscriber/program input for personalising merged mail-outs via PC or ListMerge. See the new formats "4" and "5" below (blue E-Lists info box).

The lack of HTML code in the texts saving HTML box in the "sending" window will cause the program to send only plain text e-mails OR all can be overridden to send only HTML e-mails.

It is expected that a site is tidy with all mail list saving programs saving to the one directory (preferably secure as a sub of the true cgi-bin). ListMerge is pointed to this directory and attempts to detect the format of the lists it finds with file name extensions matching those in the new $elst_exten variable. ListMerge then looks for any delimiters in those lists matching the new @seps array.

A list with a delimiter matching the default $sep variable between fields in the original list will be treated as an E-Lists or ennyForms saved list with possible "name" and "date" and "htm" fields saved with the "address". Lists with other delimiters from other porgrams will be recorded as "address only" lists with the new format marker of "5'.

Plain address only lists will be recorded with the original (earlier versions of ListMerge) format marker of "3". These marker values can be changed - but only IF really necessary.

A marked list of "3" can be changed to "5" even if the original list contains possible user "htm" fields (E-Lists v2+ and ennyForms) to slightly speed up the mailing process BUT only do this if the first fields of each record in the original list are addresses!

ListMerge v2+ allows the sending of test mails to the default site address of one plain text letter and one HTML page formatted letter - if the latter has been saved via the texts saving form.

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 the root directory creating the default directory structure included in the Zip file, and described below. A utility to create the default recommended cgi-bin subdirectories, file names, plus chmod permissions is included.

ListMerge is designed to bulk mail to elists.cgi created e-mail lists, AND/OR basic address-only e-mail lists. All you need for the latter is the list(s) file name extension and directory path where all lists reside.

ListMerge previously read information from the E-Lists config file and enable the additional merging of list member names and subscription dates - if those extra options were enabled in E-Lists. Now ListMerge attempts to detect the list type without reading the E-Lists config set up.

Which ever list types are used, it is assumed that all e-mail lists reside in one directory. By command, ListMerge creates a copy of original lists leaving the originals secure, keeps track of addresses not yet mailed to in a session, and allows for updating of new subscribers should any appear in the original lists before the current mail-out is completed (this latter option can be slow on very large lists).

For each original e-mail list found on your site, three files are created. One is the above mentioned copy of the original, and another is the data and texts associated with each list. Therefore the body text, a header or introduction text, signature text, the 'from' address, the 'Subject' line, and an HTML page can be created differently for each list. ie one might be in reference to price list upgrades with a 'from' address for sales@yourdomain.name and another for a monthly newsletter 'from' editor@yourdomain.name.... blah blah.

Once the mailing of all addresses for any list is completed and another later mail-out is ready, ie once a month or when a new upgrade is to be announced, the ListMerge copy of addresses can be recreated (over written) with the latest version of the original list (with new additions or deletions).

NOTE: Very large mass mail-outs should only be performed by a dedicated mail server. If your lists become so successful, consider leasing one for your business. The basic cgi methods of sending mail are inefficient for very large mail-outs on shared servers, and some programs including ListMerge offer an option to send mail in blocks to reduce the load on the Mail Server of your Hosting service.

You control the mail-out quantity by 'batch' sending
This simply means that once a nominated number of addresses have been mailed to, the "Send" page reappears ready for the next batch to be sent thus allowing the Mail Server CPU to perform other tasks in between. This will help prevent you from being banned by the host service (reports have confirmed this happens and people welcome the ListMerge batch option, but all it takes is contact with your host and they will mostly respond positively with perhaps a suggested "batch' figure).

Because ListMerge records addresses sent and those not sent (ready) per session, if the server is very slow you can return anytime later and continue where you left off with the next 'batch' without having to remain logged on while the full list is exhausted. If the program is "time terminated" by the server - the most common reason for mailing crashes - the last successful mailed address is recorded allowing you to continue again with possibly only one address sent twice.

NOTE: Too often the actual mail server alone is blamed for mailing crashes. Most servers have timed "life" limits on CGI programs primarily for the very good reason of trapping "runaway" programs. True, a mail server might be (usually is) very busy and slow in time slicing the many many accesses, but a good thing about Unix "SENDMAIL" is that it queues mail if the actual mail server is busy or even down. Therefore whatever the reason, terminated CGI is the biggest problem, followed by browser time out if no program response is detected (while it is working).

There are programs that use a "child" process to quickly refresh your browser, BUT the above still applies to the child process and if it crashes/is terminated you have NO way of knowing!! Be cautious of these methods because perhaps only a portion of your subscribers received any thing at all!!

Your Domain.Name
You MUST alter
all reference to "yourdomain.name" in the "lmrgeset.pl" 'require' file and supplied webmasters page (see below), and change the configuration variables in "lmrgeset.pl", also described in this Readme text.

No List viewing. Why?
Viewing of address lists is handled by E-Lists or whatever program you use to create your list. Once lists grow very large, list viewing becomes mostly useless although E-Lists does also offer a search and delete option. As ListMerge requires another program to harvest the subscribers addresses and those programs often have that option included, list viewing would be just a duplication of management facilities.

ListMerge not only mass mails to e-mail list addresses, and allows "batch" mailing to appease the wrath of mail server hosts, but the program also "merges" names and dates into each letter...
if E-List / ennyForms options are used to create the lists.

About E-Lists.
Offered as a separate program at dtp-aus.com, E-Lists is designed to save multiple lists of visitor submitted e-mail addresses to separate files created in a secure directory (ie a subdirectory of the system protected cgi-bin), via simple subscriber forms throughout your site. E-Lists can be configured to create as many different lists as there are forms by a simple change in the form code, and include not only the address, but the visitors name plus the submission date if required for mail-merging. Options such as joining newsletter lists, information or software upgrade notification or regular club updates etc can be considered - each with an 'un-subscribe' facility.

You can configure the E-Lists program to save addresses in one of four different formats:
address,name,date - +htm option
address,name - +htm option
name,address - +htm option
address only - +htm option
address,date
- +htm option
This allows users to create mail lists not only for ListMerge to merge and "batch" send, but also for FTP uploading / access by popular PC software that merges names,addresses, and dates localy before mailing. E-Lists versatility has caused it to become very popluar with serious users.
NOTE: ListMerge now also allows for another format, format "5" - address only. This is just a ListMerge thing mainly for lists created by non dtp-aus.com programs.

ListMerge can detect the E-Lists formats and enables the "merging" of E-List's fields into your mail outs for a simple but effective personal touch.

With or Without E-lists
There is a sample Admin page and Sending/Editing page supplied. Familiarise yourself with these before starting and you will soon understand how easy the program is to use. To add another list, all you have to do is create a form on one of your pages that saves the list via your subscriber program (ie E-Lists) with a common file name extension to the directory ListMerge will search. The matching list directory and file name extension is set-up in the ListMerge config file - "lmrgeset.pl".

Please NOTE:
If you install and use this script, please contact us at listmergereport@dtp-aus.com with server type detailsand how the script installed and worked etc, for a report base assisting others.
( a vote at cgi.resourceindex.com - via red form on the ListMerge program page - or any other cgi links site would also be appreciated to help "spread the word" )
  Thank you.

MENU


SAFE "Batch" Mail-List MAILING

Wherever your lists are situated ListMerge creates safe copies of the originals and works the mailing from them. ListMerge has the very rare but immensely popular facility of allowing you to send only the number e-mails you think/know your mail server can handle at one time. Then the program is ready to send the next batch and so forth until the current mail out is complete.

Because ListMerge keeps track of which addresses have been sent and which are ready to send, during a mail out the list copy can be refreshed with new arrivals without upsetting the "sent" tracking. With the "batch" method employed, addresses canot receive extra copies because the program knows where it left off. You have to reset the list when later ready to perform another mail out!

Each mail list Listmerge copies is acompanied by a data file that holds the letter information and texts and/or HTM page sent to each address in the list. The "sending and editing" admin page includes areas for entry of the From Address, Subject wording, Organisation name if desired, Header portion of the letter, Main body portion of the letter, Signature portion of the letter, AND a complete HTML page. An unsubscribe URL should now be included by you

NOTE: LnkinLite is ideal for creating permanent or temporary "named" hyperlinks that can be quickly created, generated and copied into your mail letter. This way not only subscribers can be given a special hidden html page to view, but responses can be judged by LnkinLite's link-click counting feature.

Already described above, if ListMerge detects the E-Lists file format when mail lists are saved with the subscribers name and subscription date then ListMerge can add that extra info to each letter by a simple process of you including field markers in the head/body/signature/HTML areas of the letter.

And as already mentioned each list accessed by Listmerge retains its own letter data file, so at the next mail out the new body text can be edited from the previous and perhaps the head and signature sections left as is.... designed with the user in mind.

Resetting or refreshing of each list is perfomed on the first admin page. Each list name is dsiplayed and from there the individual letter data and "batch mailing" form is accessed.

The program has an in built password administration page for changing your desired GMTime zone, admin page access password, and a further encrypted password authorising editing changes and mail-outs. Therefore, even if another person discovers your 'access' password in the browsers cache (all generated pages use the no-cache meta-tag), they cannot change or send any data, and if remote from your server loft, the prefered remote time is reflected in all output AND now displays your local time in the visible e-mail header in standard email time format!!

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). the programs can access info files, but files cannot be accessed from outside.

Upgrades
YOU MUST DELETE ALL PREVIOUS DATA FILES FROM THE MRGLISTS DIRECTORY so they can be rebuilt with important file detection data - which is only created once.... read next praragraph

ALL FILES have now been renamed EXCEPT for the data files. So by first backing them up and then later "copy and pasting" the previous texts in to the new text windows the new data files can be (MUST BE) recreated with little fuss.

ListMerge has ONE main requirement for names of original lists that it copies. They MUST NOT contain an hyphen character "-", also called the "minus sign".

The rest of the program has been completely renamed except for the password file, so the old version can remain until confident with v2.0 - list data files are incompatible.


For INTERMEDIATE installation experience - Help / Advice information is available.
CONFIGURATION VARIABLES in DETAIL

GMT TIME ZONE reference - set via ListMerge pages.
As with www.dtp-aus.com, Hosting services are used now "remote" from ones local ISP service. Normally this means that all of our scripts etc report dates and times are 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 perl "require" 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 (+10hrs = Melbourne Australia GMTime), 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 my Domain and the results would not change.

ListMerge now takes advantage of the GMT method for all visible e-mail headers too.

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

The calculation is also 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
ListMerge 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, 'lmrgeset.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 - this can block even YOU... "Bad Referrer"
This option in the 'lmrgeset.pl' file allows you create an "array" of Domain names and IP numbers that lstmrge.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 pages on your site, not remote copies of your pages elsewhere – 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:

NOTE: You cannot access the program via a browser command line OR a link on a remote copy of a page containing the access link... this includes YOU!
• You must use a site based password form or link that will generate a password form.

('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, but not the IP#. 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 may have to include the cgi-bin also in relevant urls 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 ' lmrgeset.pl ' file assume you will place these files in your cgi-bin and add directories to it called "sets" and "mrglists". 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 three path types that can be used at various times with in a program or script. 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 path is a path description to a source, relative to the directory of the program, file or web page that is calling it: 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.

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 a relative root path description that works on many servers. Another root path is "/home/yourdomain/www/yourdirectory/jimbo.htm". If you have trouble with accessing the default simple relative paths included in the 'lmrgeset.pl' file, try the root reference ie "web/yourdomain/cgi-bin/mrglists/mrgml.pw" etc. If this is still a problem, look in any installed scripts on your server for a reference, or contact your hosting support staff.

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, and reload files to double check that you used ASCII transfer mode for all text files.

"SENDMAIL" MAIL PROGRAM server path $mailprog
Similar to the Perl program path, this path has to be known for ListMerge to send submitted mail. If you do not know what it is or cannot find reference to in other installed scripts, ask your Host service support staff - the utility "testbin.cgi" may report this path for you.
The default is $mailprog = "/usr/sbin/sendmail";

ADMIN Password $adminword_pth
The file path relative to the script that will be created when you create an Admin Password. DO NOT edit this file – the new password will be encrypted. When you first start the script successfully from a form using the Access Password, create a new Admin password immediately via the 'passwords' page link to secure your data from visitors. The current password will be nothing (null) and you enter the new word twice to be sure. Once accepted you have to enter the admin password in the editing forms next to the submit buttons whenever you try to edit any options.

GMT Path $gmt_pth
When you edit the GMT zone value from the passwords 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 any configuration values or data files from the admin pages, the script needs to know the path to the 'lmrgeset.pl' file. The default is the "sets" sub directory and file name relative to the scripts directory. The "sets" directory is used by almost ALL dtp-aus.com programs and will have even more significance in the future.

The DATA FILES DIRECTORY $mrgdatdir_pth
This is the directory path (not file) for the files created when copies of the lists are created or updated, and data files are created or amended. The default is "mrglists".

DEFAULT MAIL ADDRESS $deflt_mail
NEW v2. This is the default mail address used by the new "Mail Test" option.

RETURN PAGE URL $hm_url
The value for this variable in the ' lmrgeset.pl ' file needs to be altered to include the FULL URL Path to your home page or any page that you wish to return to after finishing with the admin pages. Perhaps back to the webmster.html page.

FULL URL to LSTMRGE.CGI $theScrpt
The value for the variable named "$theScript" in the config file needs to be altered to include the FULL URL Path to the lstmrge.cgi script. It is suggested that the script is placed in your cgi-bin or equivalent secure directory.

ACCESS PASSWORD $theword
You can enter an Access Password in the lmrgeset.pl file before installing the program, or later from the admin page. To display the admin page, simply enter your access password into the form in the webmasters page, or via a hyperlink to the script that includes an embedded access password. Both of these options will be explained below.

ISO CHARACTER SET $ISO
NEW v2. This can be left as is for most users. It defines the character set used by you, commonly also seen in the head section of HTML pages. This is used in the (generally) hidden mail headers.

RECOGNISED RECORD FIELD DELIMITERS @seps - original lists
NEW v2. This array includes various delimiters ListMerge may come across when parsing lists not native to E-Lists or ennyForms. The array MUST include the default delimiter ($sep below) and if changes are made the format and "|" divider MUST remain as is.

The MAIL LISTS DIRECTORY $mailistdir_pth
CHANGED v2. This is the directory path (not file) to the ORIGINAL e-mail lists (ListMerge works off a safe copy of each). The default is "mailfrms". If using a program other than E-Lists to create the original lists, then change its defaults to this directory and simply copy the lists to this directory via FTP, OR change this default to the existing directory, when ever you want ListMerge to find them.
• This variable name has been changed to be compatible with E-Lists and ennyForms.

ORIGINAL LIST-FILES File Name Extension $elst_exten
CHANGED v2. If you want to use lists other than / as well as E-Lists list files, add their file name extension (including the dot) to this variable. The ".elf" extension is the dfault for E-List and ennyForms subscriber lists. If changes are made the format and "|" divider MUST remain as is.

ADDRESS,NAME,DATE SEPARATOR $sep
This is the default delimiter ListMerge uses to divide record filelds when merge list data is detected. It would be wise to keep this the same as E-Lists and ennyForms if those programs are used to create subscriber lists.


SETTING UP and USE

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. The script lstmrge.cgi "require"s several such files. One includes a variable used by the date/time routines and another contains script variables that you need to adjust before installation. changeable program defaults are accessed by the admin pages. If you use other dtp-aus.com / HostingNet programs, I have included the GMT reference variable in a separate file as used by all my scripts on dtp-aus.com. If I need to change this common variable for daylight savings or domain moves etc, then I only have to change one file, not many. The GMT value can be set simply via the admin page.

ListMerge has ONE main requirement for names of original lists that it copies. They MUST NOT contain an hyphen character "-", also called the "minus sign".

SAMPLE FILES
Once the script is uploaded and runs for the first time, setting the password(s) will also test the installation. Then alter and ASCII upload the sample files I have included into the "mailfrms" directory. "mytest.elf" etc would represent an e-mail address list. The extensions must match those of lists you are using (and set in the config file). Place these sample lists in your E-MAIL LISTS DIRECTORY. DO NOT manually create any data files in the "mrglists" directory as was possible in previous versions

CHANGE THE SAMPLES
If there are already some mail addresses, so before uploading, change the addresses in the sample files to yours. If you have multiple or unlimited email address names, enter several bogus names (ie fred@yourdomain.nme and bill@yourdomain.nme etc) OR just repeat the same one in each record.

NOTE: It is common-sense to aslo ALWAYS add your self to all real mail lists so you will receive and see just what your subscribers are getting!!

USING THE SAMPLES
Click on the radio button next to "mytest" listed in the first form, and click on the form button to take you to the Editing and Sending page for that list. You should see a screen like the second sample html page.

Create some texts (garbage will do), from address, subject line, add some HTML code etc and save the data. Use the "TEST" form to send your self a test letter of plain and HTML letters. If all goes well, set the "Batch Number" to 2 or 3, enter your admin password and click on the form button. If all goes well the script will find, talk to and send 2 or three e-mails to you (because the list contain your addresses). If they arrive without error then all should have been installed correctly (the time it takes for mail to arrive to yourself can be instant or minutes - this depends entirely on the Host Mail Server and Receiving Mail Server). Now you can send another two to check that the numbers displayed are incrementing/decreasing correctly.

There are four simple test texts supplied you can copy and paste into the text saving box for each test list you want to use. They are not brain intensive but will do for test purposes.

Depending on the traffic pressures on the Host Server, and to some degree whether they have a separate server for e-mail, you might have to wait a minute for just one e-mail to be sent whereas at other times it will be quicker even if you are sending fifty at once etc.

When all have been sent and received, try changing the texts and successfully saving changes several times. Close the window and come back a few minutes later and view the edit/send page again to make sure all changes appear as you would expect. DON'T forget you have to refresh a list with the first page "New" option to start again once a mail-out is complete.

You can try the above with all the lists as most have different formats and this will check the ListMerge parsing of the originals.

On the left of the second form on the first page are the last counted number of subscribers (recounts every time the first page is accessed). When the list has changed (subscribed to or UN-Subscribed to) the counted number will appear in red. This will indicate changes during a mail-out too (if batches are used) allowing you to use the "u/d" update option that will add new addresses to the current ListMerge list from the master (but not remove deleted ones). For very large lists this can be a bit slow so perhaps only use this if many addresses have been added to the original master list before a mailout is complete.

DELETING
Should a mail lists data files are not needed any more then the "delete" option can be used. THIS WILL ONLY DELETE all ListMerge data files and NOT touch the original list IF it still exists.

THE "BOX WIDTH" OPTION
When creating your own texts (header, body and signature), you can create long lines by simply typing and only hitting the enter key for a change of paragraph (hitting the enter key twice). However you might have noticed over time that many received e-mails are preset for easy reading with formatted narrow line widths. This is quite an important issue if you want the e-mails to be received well by all recipients, because many e-mail programs only have small viewing windows AND many people still using 640X480 resolution video can only read short lines without horizontal scrolling.

As a simple guide you can preset for your own preference, I have included a variable "box width" (40 to 66 characters) that helps by allowing you to hit the enter key just once as your lines approach the right hand window limit, forcing the lines to wrap with easy visual control. ListMerge will detect single and multiple hidden enter key characters and send your texts accordingly.

SIMPLE PREVIEW
Also included is the simple mono spaced sample view of the combined texts as they will be sent, displayed below the editing boxes, and this preview can be switched off if so desired.

HTML ENTRY BOX
The HTML entry box is for pasting a complete HTML page and saving with the plain text options also. The program will detect, from E-Lists and ennyForms subscriber lists, an "htm" field the user has selected to accept HTML formatted list mail-outs. Should there not be any message box text OR the "Use ALL HTML" button has been selected then every letter will actually be an HTML page.

If there is no HTML text then only the plain text message etc will be sent.

HTML PAGES
Be sensible creating HTML pages for transmission. Make all hyperlinks FULL URLs. Any images included must also contain their FULL URL back to your site (remembering that images are useless when viewed off-line).... in fact use NO or as few images as possible. NEVER use SSI pages - they just don't work remotely! Make the page neat, informative and do not try to impress with heaps of nested tables - think file size.

NOTE: The merging field markers appearing above the message box can be included in the HTML pages as well as the message, header, signature boxes; BUT if using wysiwyg editors then you may have to manually change ISO characters (&lt; and &gt;) to the hard coded << >> characters. See the supplied simple sample htm page text.

QUICKEST MAILING
Probably the quickest mailing will be performed with a standard address only list, format marked to "5", and with the "No MERGING" option box ticked. This will all avoid some of the programs logic checking..... BUT make sure the merging field markers do not exist in the texts because they will not be parsed / replaced and the subscribers will wonder what the heck! they mean.

The "Stay Alive" button may or may not help if you experience too many Browser Time-outs. With this option selected the program attempts to send back a single invisible character every 50 letters. Please give us feedback on this and other options of v2.+ as this is a very different program than the earlier versions and it would be appreciated.

That's just about it. Repeatedly reset (using the "new" radio button again) and send the sample addresses to yourself until you feel confident, and then create the ListMerge copies and data files for any real e-mail lists you have, ready for transmission. If you see the displayed number of records on the left of each original e-mail list name appear in bold (view sample html), you will know that the list has received new additions since you last updated the copies because the totals will be different. If a mail-out is not yet complete you can select the second radio button (u/d) to add only those new additions without resetting the list - if you would like to include them in that current mail-out.

NOTE: When a list is renewed (via a "new" radio button), all addresses are reset to the 'not sent' state, and doing this before a mail-out is finished will cause multiple e-mails to be sent to many recipients with possible nasty comments and requests for un-subscribing! We all hate what appears to be mass spamming. The "update" buttons allow safe inclusion of newly added addresses during a mail-out session ie between batch sending.


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

INSTALLING

THE PATH TO PERL
At the top of each perl 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.

SCRIPT and FILES PERMISSIONS
Each list copy must be given read and write permissions (chmod 766). The directory that they are placed in (mrglists) will also need read and write permissions. Either read and write chmod 766 (r+w) or possibly chmod 777 (r+w+x) will work - try the first before the latter. The "sets" directory and the ?.set files in it must also be given the same permissions as the "mrglists" directory and files.

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

CGI-BIN 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).

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. 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. 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 each time before they can be executed. The script (text) must be in ASCII text format for the interpreter to be able to read it.

CALLING THE SCRIPT from a hyperlink
<a href="http://www.yourdomain.path/cgi-bin/lstmrge.cgi?accwrd=***"> ListMerge </a> where *** = your access password (NOT your admin password),
OR from a simple form as viewed in the webmstr.html code.

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

So, assuming the default directory structure is used, you will up load into:
• CHANGED v2.0+

Directory:
cgi-bin (server)
lstmrge.cgi (chmod 755)
cgi-bin/sets (chmod 766 or 777)
lmrgeset.pl, gmtset.pl (chmod 766 or 777)
cgi-bin/mrglists (chmod 766 or 777)
mrgml.pw, admn1.pl, admn21.pl, admn3.pl, admn4.pl, admn5.pl
plus
[list / data files created by program], (chmod 766 or 777)

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 lstmrge.cgi. ie::

#--- Alter these two paths (TWICE EACH) only, if needed! -----#
      if (-s "sets/
lmrgeset.pl") {require "sets/lmrgeset.pl" ..etc etc
      if (-s "sets/gmtset.pl") {require "sets/gmtset.pl"
..etc etc
#--- Do Not make any changes below this line. ----------------#

To help keep the program free, we need your support on link and resource listing sites!


UTILITIES

Webmasters Page - the 2 methods to Admin
I have supplied a sample webmasters page ( webmster.html ) that can be used to access the admin page, or copy the required link (form or hyperlink) to your own webmasters utility page. You will have to change the path in the links to suit your own. This page should ideally be placed in a secure directory. If not, use the form method of accessing admin and DELETE the hyperlink. Else if secure you can use the simple link with the embedded password.

NOTE: You cannot access the program via a browser command line OR a link on a remote copy of a page containing the access link... this includes YOU!

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. 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). ListMerge is a Perl 5 script, for Unix servers using Sendmail.

The new version of tesbin.cgi attempts to ascertain server paths to all Perl versions and paths to Sendmail. Either or both of these may not be listed depending on server set-up. Testbin.cgi also now allows you to check your path to perl by attempting a mail out. To do this change in the code near the top the URL to the testbin.cgi program.

So!
Change the program URL in the code - only variable to change.
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
I have created a simple utility script that can be placed in your cgi-bin and run from your browsers command line. If your server allows directory creation via cgi scripts, 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 has worked well on many sites.

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.

To use it, make sure the "Perl Path" at the top of the script is correct. NOTE: the default Dir/File 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)

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

If by chance you select the wrong values and you are locked out of directories, simply change the chmod values and re-run.

So! 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

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