CGIMailer for Windows 95/NT
January 1998 version 1.00

Author:
Goran Boban
boban@student.math.hr




	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

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.




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

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:

TEMPLATE	REQUIRED	is relative path (from CGIMail.exe) to template file
				used to create response page if operation succeeds.
				If this variable is not set CGIMailer will generate an
				error.

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

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.

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.

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

SUBJECT		Subject of message.

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


Name of configuration file must be passed to CGIMailer as a command-line parameter.
Also you must use POST method.
So your calling HTML code will look like:

<FORM method=POST action="http://my.server.com/cgi-bin/cgimail.exe?path/to/conf/file.conf">

	...

</FORM>

NOTE: path to configuration file must be relative to directory where cgimail.exe is placed,
or absolute path (with drive letter).





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

CGIMailer will proccess configuration file, response template file and message template file
(if any) to check for variables to be replaced. Variables should appear in following format:

	<%VARIABLE_NAME%>


CGIMailer recognises four types of variables:

- Required variables	Required variable names must start with "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." prefix. Folowing system
			variables are present in CGIMailer:

			SYS.YEAR 	- current year.
			SYS.MONTH	- current month.
			SYS.DAY		- day.
			SYS.HOURES	- hour when CGIMailer is started.
			SYS.MINUTES	- minit when CGIMailer is started.
			SYS.SECONDS	- second when CGIMailer is started.
			SYS.TEMPLATE	- name of response template file.
			SYS.ERRTEMPLATE	- name of error template file.
			SYS.MSGTEMPLATE	- name of message template.
			SYS.MAILER	- name of mailer (defaults to: CGIMailer version 1.00)
			SYS.INPUT	- preproccesed message wich is sent.
			SYS.GATEWAY	- name of SMTP server.
			SYS.HOST	- name of local host (where CGIMailer is executed).
			SYS.PORT	- port number used to connect to SMTP service.
			SYS.FROM	- E-mail addres of sender.
			SYS.TO		- E-mail(s) of recipient(s).
			SYS.CC		- Addresses listed in Cc: field.
			SYS.SUBJECT	- Subject of message.
			SYS.TIMEOUT	- Timeout for socket operations in seconds.

- Environment variables	Environment variable names begin with "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. Error template
	-----------------

When an error occures (and if ERRTEMPLATE variable is set in configuration file) CGIMailer
will use error template file to create an response to user. Error template file is
an HTML document with directives of following form:

	<%SYS.errorNN%>

where NN is error code of error wich occures or one of keywords "default" or "end"
For list of error codes generated by CGIMailer see errcodes.txt.
When proccesing error template CGIMailer will create an HTML document from following
parts of 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.


	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 CGIMa100.exe 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
To obtain an registration key You have to send me 15$ or 25DM as a registration
fee to following address:

	Goran Boban
	Zeleni trg 3, 10000 Zagreb
	Croatia (Europe)

Please send cache only since (unfortunately) I can't handle checks or credit cards for now.

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

	There are no known bus for now.

	If You find any bugs PLEASE SEND REPORT to

		boban@student.math.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.

