CGIMailer for Windows 95/98/2000/NT4.0
December 2000 version 3.10
Purchase information: Shareware ($20.00)
Author:
	Goran Boban
	gboban@cursor.hr

Home page:
	gboban.tripod.com
	gboban.hypermart.net
	http://members.xoom.com/gboban/index.htm



	DISCLAIMER

	THIS SOFTWARE AND ALL THE ACCOMPANYING FILES ARE PROVIDED "AS IS" AND 
	WITHOUT ANY WARRANTIES EXPRESSED OR IMPLIED INCLUDING BUT NOT LIMITED
	TO IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
	PURPOSE. 



	LIMITATION OF LIABILITY

	AUTHOR SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE OR ANY
	THIRD PARTY AS A RESULT OF USING SOFTWARE. IN NO EVENT WILL AUTHOR BE
	LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT,
	SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER  CAUSED
	AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR
	INABILITY TO USE SOFTWARE, EVEN IF AUTHOR HAS BEEN ADVISED OF THE
	POSSIBILITY OF SUCH DAMAGES.      


	1. Description
	--------------

CGIMailer is an CGI (Common Gateway Interface) program wich will recive input from
web form and send mail.

CGIMailer supports:
	- Required variables
	- Template based e-mail messages
	- Template based response pages
	- Customisable error reports
	- File attachments

NOTE: There must be an SMTP server accessable from your server.



	2. Installation
	---------------

To install CGIMailer just copy CGIMail.exe to cgi-bin directory of your web server or any
other directory in wich your server will allow execute access. Please see your servers
documentation for more information.

To install samples copy *.cf and *.htt files to the directory where CGIMailer can read them.
If you want to restrict CGIMailer to access configuration files only in certain directories,
create CGIMASEC.TXT file in directory where you put CGIMailer or in Windows system directory
(e.g: c:\windows\system on Win9x or c:\WINNT\system32 on WinNT) and specify each directory
in separate line (see CGIMASEC.TXT shipped with this package for example).

Copy *.htm files to directory under your web root directory.
Also, edit ACTION property of FORM tags in *.htm files and change TEMPLATE, MSGTEMPATE,
SAVETOFILE variables in configuration files (*.cf) to reflect directories where you have
placed files.

NOTE: All included demo projects assume that you have following directory structure:
	/cgi-bin/
	/cgimailer/demo/
and expect CGIMIL.EXE to be in /cgi-bin directory and *.cf, *.htt, *.htm files in
/cgimailer/demo directory.
If your installation differs, you will have to edit demo files to reflect directory
structure on your server.

PLEASE, READ THIS README FILE FIRST TO UNDERSTAND HOW THIS VARIABLES SHOULD BE SET.



	3. Using CGIMailer
	------------------

Please see history.txt for list of changes.
See demo*.* files for examples.

CGIMailer is controlled with configuration files (Every form that uses CGIMailer can
have its own configuration file).
You can setup following variables in configuration file:

RESPONSE_TEMPLATE (v3.00) This variable should point to new style response template.
		See description of Response template/Error template below.

TEMPLATE	is relative path (from CGIMail.exe) to template file used to create
		response page if operation succeeds.
		This variable is not required any more since you may specify LOCATION or
		RESPONSE_TEMPLATE.

LOCATION	is URL where CGIMailer will redirect users browser if operation succeeds.
		This variable is used only if TEMPLATE variable is not present.

ERRTEMPLATE	relative path to template file if an error ocures. If this variable
		is not set CGIMailer will display an built-in error message or redirect
		to URL specified in ERRLOCATION.

ERRLOCATION	is URL where CGIMailer will redirect users browser if operation fails.
		This variable is used only if ERRTEMPLATE variable is not present.

MSGTEMPLATE	template for creating mail message. If this variable is not set CGIMailer
		will create message of following form:
			VARIABLE1=VALUE1
			VARIABLE2=VALUE2
			...
		Where VARIABLE1, VARIABLE2 etc. are names of input fields in your web form.

SAVETOFILE	relative path (from CGIMail.exe) to file wich you want to use for saving
		input. If this variable is not set, then CGIMailer will not try to save
		input to file. There must be WRITE access specified for the file.
		Since version 3.10 you can place multiple SAVETOFILE directives in
		configuration file.

DEBUG		If this variable is set to YES (DEBUG=YES) CGIMailer will send an text
		response with transcription of comunication with SMTP server.
		Othervise it will create response page based on file pointed in
		TEMPLATE variable.

GATEWAY		Name of smtp server (smtp.server.com for example) to use for sending mail.
		If this variable is not set CGIMailer will assume localhost.

PORT		Port number of SMTP service on SMTP server. By default it is 25.

FROM		E-mail address of sender. If this variable is not set CGIMailer will
		assume an addres of form CURRENT_USER@NAME_OF_LOCAL_MACHINE.
		You should set this variable in most cases.

TO		REQUIRED	E-mail addres (or list of addresses) of recipient(s).
				If this variable is not set CGIMailer will generate an
				error. E-mails have to be separated with space (" ").

CC		List of addresses to send carbon copy of message (displayed in Cc: field
		of message).

BCC		List of addresses to send blind carbon copy of message. Addresses listed
		in this line will not be listed in header of message.

SUBJECT		Subject of message.

TIMEOUT		Timeout (in seconds) for socket operations. Default is 300.

ATTACH		File to attach to mail message. There may be multiple lines containing
		ATTACH.
		All files attached to message are base64 encoded and marked as
		"application/octet-stream".

REFBASE_ALOW	Accept submittions from URLs which are specified with this variable.
		This variable may appear several times in configuration file.
		Example: if your host is named www.yurhost.com and want to allow
		submittion from any form than put:
			REFBASE_ALLOW=http://www.yourhost.com/
		to allow submittions only from forms placed in /comments directory
		put:
			REFBASE_ALLOW=http://www.yourhost.com/comments/
		to allow submitions only from form on
		http://www.yourhost.com/comments/privileged.htm put:
			REFBASE_ALLOW=http://www.yourhost.com/comments/privileged.htm

REFBASE_DENY	Deny submittions from URLs specified here. This variable may appear
		several times in configuration file.
		Example: if you want to allow submittions from www.yourhost.com, but
		not from forms located in directory /spam on that host than put:
			REFBASE_ALLOW=http://www.yourhost.com/
			REFBASE_DENY=http://www.yourhost.com/spam/

Name of configuration file can be passed to CGIMailer in two ways:

	- By setting SYS.CONFIGFILE (or SYS_CONFIGFILE) on Your form. Your caling HTML code
	should look as follows:

		<FORM method=GET action="http://your.server/cgi-bin/cgimail.exe?">
		<input type=hidden name=SYS.CONFIGFILE value="configfile.cf">

			. . .

		</FORM>

	- Or by passing name of configuration file as command-line parameter:

		<FORM method=POST action="http://your.server/cgi-bin/cgimail.exe?configfile.cf">

			. . .

		</FORM>



NOTE:	path to configuration file must be relative to directory where cgimail.exe is placed,
	or absolute path (with drive letter).
	Also use SYS.CONFIGFILE (SYS_CONFIGFILE) variable when using GET method.

You can also call CGIMailer from <A HREF> tag with

	<a href="http://your.server/cgi-bin/cgimail.exe?configurationfile.cf&var1=val1&...">
or
	<a href="http://your.server/cgi-bin/cgimail.exe?&SYS.CONFIGFILE=configfile.cf&var1=val1...">

or
	<a href="http://your.server/cgi-bin/cgimail.exe?SYS.CONFIGFILE=configfile.cf&var1=val1...">


	4. Variables
	------------

CGIMailer will proccess configuration file, response template file and message template file
(if any) to check for variables to be replaced. Since version 3.00 CGIMailer you can put
variables in error template as well.
Variables should appear in following format:

	<%VARIABLE_NAME%>


CGIMailer recognises four types of variables:

- Required variables	Required variable names must start with "REQ." or "REQ_" (REQ.name
			for example). When CGIMailer finds required variable in any of
			following files: configuration file, response template file
			or message template file, it will check if variable is passed
			from form and if it contains any characters other than spaces.
			If not so CGIMailer will generate an error. CGIMailer will also
			check input from form for required variables.

- System variables	System variable names begin with "SYS." or "SYS_" prefix. Folowing
			system variables are present in CGIMailer:

			SYS.YEAR(SYS_YEAR) 		- current year.
			SYS.MONTH(SYS_MONTH)		- current month.
			SYS.DAY(SYS_DAY)		- day.
			SYS.HOURES(SYS_HOURES)		- hour when CGIMailer is started.
			SYS.MINUTES(SYS_MINUTES)	- minit when CGIMailer is started.
			SYS.SECONDS(SYS_SECONDS)	- second when CGIMailer is started.
			SYS.CONFIGFILE(SYS_CONFIGFILE)	- path to configuration file passed to
							CGIMailer (v3.00).
			SYS.RESPTEMPLATE(SYS_RESPTEMPLATE) - new style response template(v3.00).
			SYS.TEMPLATE(SYS_TEMPLATE)	- name of response template file.
			SYS.LOCATION(SYS_LOCATION)	- succes URL (see LOCATION in
							configuration file).
			SYS.ERRTEMPLATE(SYS_ERRTEMPLATE)- name of error template file.
			SYS.ERRLOCATION(SYS_ERRLOCATION)- failure URL (see ERRLOCATION in
							configuration file).
			SYS.MSGTEMPLATE(SYS_MSGTEMPLATE)- name of message template.
			SYS.SAVETOFILE(SYS_SAVETOFILE)	- name of file used to save input.
			SYS.MAILER(SYS_MAILER)		- name of mailer (defaults to: CGIMailer
							version 3.00)
			SYS.INPUT(SYS_INPUT)		- preproccesed message wich is sent.
			SYS.GATEWAY(SYS_GATEWAY)	- name of SMTP server.
			SYS.HOST(SYS_HOST)		- name of local host (where CGIMailer
							is executed).
			SYS.PORT(SYS_PORT)		- port number used to connect to SMTP
							service.
			SYS.FROM(SYS_FROM)		- E-mail addres of sender.
			SYS.TO(SYS_TO)			- E-mail(s) of recipient(s).
			SYS.CC(SYS_CC)			- Addresses listed in Cc: field.
			SYS.BCC(SYS_BCC)		- Bcc list of addresses.
			SYS.SUBJECT(SYS_SUBJECT)	- Subject of message.
			SYS.TIMEOUT(SYS_TIMEOUT)	- Timeout for socket operations in
							seconds.
			SYS.ERRMESSAGE(SYS_ERRMESSAGE)	- Built in error message or "Mail sent"
							message if no error (v3.00).
			SYS.ERRLEVEL(SYS_ERRLEVEL)	- Error code or 0 if no error (v3.00).
			SYS.STATUS(SYS_STATUS)		- String "Error" if an error occured or
							"Succes" if no error.

- Environment variables	Environment variable names begin with "ENV." or "ENV_" prefix. CGIMailer
			will replace every occurance of variable beginning with "ENV." prefix
			with coresponding environment variable. For example occurance of ENV.TEMP
			variable will be replaced with environment variable TEMP passed by OS
			(contains name of default temporary directory on your system).

- Occurance of any other variable (not beginning with REQ., SYS. or ENV. prefix), will be simply
replaced with its value.




	5. Response template/Error template
	-----------------------------------

Since version 3.00 you can use single file (RESPONSE_TEMPLATE) to specify both,
error response and succes response.
New response template file is an HTML document with format similar to old style error
template, but which allow you to specify succes response under error code 0.
Response (error) template directives are of following form:

	<%SYS.errorNN%>

where NN is error code of error which occures (or 0 if no error) or one of keywords
"default" or "end". For list of error codes generated by CGIMailer see errcodes.txt.
When proccesing response (error) template CGIMailer will create an HTML document from
following parts of response (error) template file:

	- beginning of document untill first <%SYS.errorNN%>, <%SYS.errordefault%>
	<%SYS.errorend%> directive, or end of file if there is no any error directive.

	- section wich begins with <%SYS.errorNN%> directive (where NN is error code
	of error generated by CGIMailer if such directive) or <%SYS.errordefault%>
	directive if there is no an appropriate <%SYS.errorNN%> directive,
	and ends with any other error directive or end of file if no error directives
	are listed after this one.

	- section wich begins with <%SYS.errorend%> directive and ends with end of file.

For the complete listing of error codes see errcodes.txt
Since version 3.00 CGIMailer will procces any variable found in response (error) template
as described above (4. Variables).

	6. Registration
	---------------

You have permission to use an unregistered copy of CGIMailer for
period of 30 days for evaluation purposes only.
If You continue to use CGIMailer after period of 30 days You have
to register it.
Also You have permission to distribute CGIMailer package under
following conditions:

	- You have to distribute CGIMa130.zip package as it is without any changes. 
	- You take no fee other than for distribution costs. 
	- It must be clear that CGIMailer is shareware. 

CURRENTLY AN UNREGISTERED COPY OF CGIMAILER WILL ATTACH SHORT MESSAGE
TO ALL CREATED PAGES.

To remove this messages You have to register. 

To register CGIMailer just follow these steps:

	- Obtain an registration key

If You are registered user of any version prior to 3.10 just use registration key you have
(Upgrade is free for You).

If You are not an registered user of version prior to 3.10 You have to pay $20 as
registration fee.

On-line registration is aviable via Register Now! service at:

	https://www.regnow.com/softsell/nph-softsell.cgi?item=1275-2

You can use Visa, Mastercard, American Express, or Discover card.

You can also send me money with mail to following address:

	Goran Boban
	Zeleni trg 3
	10000 Zagreb
	Croatia (Europe)

If You decide to send money with mail please send cache only. Also please contact me
via e-mail before sending money.

Also be sure to send me following information

- Your first and last name (or company name)
- E-mail address
- Name of program you want to register (CGIMailer in this case)

BE SURE TO SEND AN E-MAIL ADDRESS SO I CAN SEND YOU A REGISTRATION KEY


	- Register Your software using register.exe
Register.exe utility is distributed within this package.
By using register.exe You will disable messages which unregistered version of
CGIMailer attaches to responses sent to user.

NOTE: For information on running register.exe see register.txt file.



	7. Bugs
	-------

	PLEASE SEND BUG REPORTS to

		gboban@cursor.hr

	with:
		CGIMail - bugs
	in subject.

	Also feel free to contact me if you have any problems running or setting-up
	CGIMailer or if you have any sugestions for future releases.

	IMPORTANT: When sending bug reports or questions please be sure to include
	following information:

	- Program name	(CGIMailer)
	- Version	(3.10)
	- OS		(Win95/98/2000/NT4.0)
	- Web server name and version.
	- What have You tryed to solve problem
	- Any other information which You find relevant.



