readme (3)

Lemur zaprasza

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.

Help / Advice

scrpthlp.htm

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

• • • •

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".

- 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.

- or any other cgi links site would also be appreciated to help "spread the word" )

Thank you.

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 - 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 (< and >) 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 - 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 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