[PREVIOUS CHAPTER] [NEXT CHAPTER]
7 FML internal data structures


Here we describe FML internal data structures. When you hacks FML,
this knowledge is required. However you do not need to read this
chapter if you toggle variables only on/off.

7.1	Naming convention of variables


* ^[A-Z0-9_]+$ name variable is USER DEFINED VARIABLE for customize.
It is a global variable. Fundamentally these variables are defined in
config.ph, sitedef.ph and site_init.ph.

	Example:	$MAIL_LIST


* Capitals are global not for USERS but for systems. In principle
  users should not touch them. If you hacks, it must require to handle
  these variable.

	$MailBody	$Reply_to
	%Envelope	*_cf


   %Envelope is the most important variable. We should not increase
   the number of global variables. Several variables e.g. @Fld 
   are capital but historically left not as global.


  ATTENTION: historically $debug is global for convenience.


* Lower case word is local variable. 


[Appendix]
Directory variables consists of two types


	$*_DIR 		relative path to $DIR
	$FP_*_DIR 	obsolete path


$FP_*_DIR is automatically defined based on directory variables.
In a lot cases absolute path is used.

	$FP_TMP_DIR
	$FP_VARDB_DIR
	$FP_VARLOG_DIR
	$FP_VARRUN_DIR
	$FP_VAR_DIR
    	$FP_SPOOL_DIR

7.2	Naming convention of functions


Except for a few cases, a function name is capitalized. The word after
"_" is also capitalized. It is similar to X11 style:D


* Some exceptions remains after fml 1.5.


File operation functions are defined as 


	f_function_name 	conversion interface


	Cnstr_function_name		constructor for this mode
	Destr_function_name		destructor for this mode


These are exceptional. In that age I should replace these naming
convention but still remains ;D

7.3	%Envelope (hash)


%Envelope is most important variable(hash). %Envelope contains header,
each field of the header, body as a hash table. This hash is passed in
a lot of function calls. It is similar to sendmail's struct ENVELOPE
e;


In the age of FML 1.5, perl 5 does not run. Hence we cannot use
e.g. the following style

	$Envelope->$Header->$From = "uja@domain";


It is represented by

	$Envelope{"h:From:"}  = "uja@domain";


":" is a separator. From: is a special syntax to identify this key is
a field.


Keys of %Envelope:


	KEY beginning with "h:" is a field of a header.


	h:Capital:	adjusted field data to use in delivery e.g. h:Subject:
	h:lower-case:	original field data e.g. h:subject:


	h:field:	header field 
			lower case name is original
			Capital is after changed.


	fh:field:	enforce a field to use this value


	oh:field:	enforce fml.pl to use original field value
			for this field


	GH:field:	enforce some value for field of command mail results
			and so on. used in GenerateHeader().

			reply-to: > From:


	Addr2Reply:	address to send a command result and so on


	[mode or method configurations]


	macro:x		corresponds to $x of sendmail


	mode:x		mode x is enabled.


	mci:mailer	Mail Connection Information
			mci:mailer is ipc or prog.


	[Internal Data]


	Header		original header
	Body		original mail body
	Hdr		header of sending mails out in distribute phase	


	message		message to send back to a sender
			for command results and others
	error		error message to send back to a sender

	MIME		ISO-2022-JP is detected (toggle Flag)
	UnixFrom	Unix From


	MIME		ISO-2022-JP is detected (toggle Flag)
	UnixFrom	Unix From
	Hdr2add		buffer when $SUPERFLUOUS_HEADER is set.
	nclines		number of lines for "# command" style lines
	nlines		lines of mail body
	preamble	preamble to put on mail body
	trailer		trailer to put on mail body

	tmp:x		temporary used


Example: Subject:


   $Envelope{'h:subject:'} is 
   an in-coming mail's original Subject: field value. 


   $Envelope{'h:Subject:'} is after cutting Re:'s and tags e.g. [Elena 100].


Example: In a header of distribution, used key of %Envelop is as follow:

        Field           key in %Envelope
	--------------------------------------- 
	Date: 		h:Date:
	From:		h:From:
	To: 		h:To:
	Subject: 	h:Subject:

7.4	Initialize data structures


Initialization of fml.pl is as follows:


	initialize $DIR $LIBDIR @INC and so on

	&InitConfig
	   &SetDefaults
		%Envelope
		DNS, @HdrFieldsOrder, and others

	   &LoadConfig
		$DIR/config.ph
		sitedef.ph

   	   &SetOpts
		command line options

	   COMPATIBILITY CODE

	&Parse


	&Parse
		reset %Envelope

	&GetFieldsFromHeader


	&GetFieldsFromHeader
		analyze %Envelope and set h:field: and h:Field: up.

	&FixHeaderFields


	&FixHeaderFields
		adjust h:Field:

	&CheckCurrentProc


	&CheckCurrentProc
		adjust fields, check loops, modes and so on


	After this fml.pl sets in the main routine,
	hooks are evaluated in several locations.

	Example:
		$START_HOOK
		$SMTP_OPEN_HOOK
		$FML_EXIT_HOOK


After this, the critical section begins. 

7.5	Directory variables


[Directory variable list]

		$DIR @INC(original) $LIBDIR ...

	$DIR


	$DIR
		config.ph location. ML's HOME directory.
		The argument of @INC.

	$LIBDIR	
		library paths. @LIBDIR is a list of $LIBDIR's.
		fml pushes $LIBDIR to @LIBDIR.
		fml searches @LIBDIR for executable and libraries

    	$SPOOL_DIR		$DIR/spool


    	$SPOOL_DIR		$DIR/spool
		spool of articles of ML


	[Relative path from $DIR]

	$TMP_DIR		tmp (temporary)
	$VARDB_DIR		var/db  (database, 4.4BSD like)
	$VARLOG_DIR		var/log (log, 4.4BSD like)
				$DIR/log is exceptional for backward 
				compatibility.
				($VARLOG_DIR/log is preferable)
	$VARRUN_DIR		var/run (4.4BSD like)
				pid's file and several caches
	$VAR_DIR		var (4.4BSD like)


	[Corresponding fully pathed directory variables]

	$FP_TMP_DIR		$DIR/$TMP_DIR
	$FP_VARDB_DIR		$DIR/$VARDB_DIR
	$FP_VARLOG_DIR		$DIR/$VARLOG_DIR
	$FP_VARRUN_DIR		$DIR/$VARRUN_DIR
	$FP_VAR_DIR		$DIR/$VAR_DIR
    	$FP_SPOOL_DIR		$DIR/$SPOOL_DIR

7.6	On temporary directory ($TMP_DIR)


$DIR/tmp is temporary working area. It is defined as $TMP_DIR. We
should not use the system's /tmp or /var/tmp if the file is left when
OS crashes.


7.7	Configuration files


[Member Lists]

	$MEMBER_LIST 	 	$DIR/members


	the ML member list for authentication. If a given address is
	not in this list, fml.pl does not authenticate the
	address. This is not a delivery list in non automatically
	registration mode. In automatic registration mode, this file
	is both a member and delivery list.

	$ACTIVE_LIST 		$DIR/actives


	list of distribution in non automatically registration mode.

	$REJECT_ADDR_LIST	$DIR/spamlist


	list to reject as a spammer.


[files of guides and so on]

	$OBJECTIVE_FILE	 	$DIR/objective


	objective of ML

	$GUIDE_FILE		$DIR/guide


	guide for general people (for not member)

	$HELP_FILE	 	$DIR/help


	help file of ML (for only member)

	$DENY_FILE	 	$DIR/deny


	file to send back when fml.pl rejects mail from a non member.
	This is not used in auto registration mode.

	$WELCOME_FILE	 	$DIR/guide


	file to send back in auto-registration mode when 
	a user is automatically registered. 

	$CONFIRMATION_FILE       $DIR/confirm


	confirmation file in auto-registration mode.
	Please see confirmation (../how_to_subscribe 5.9).


[Logfiles]

	$LOGFILE	 	$DIR/log


	log file

	$MGET_LOGFILE    	$DIR/log


	mget log. In default $MGET_LOGFILE == $LOGFILE.

	$SMTPLOG		$VARLOG_DIR/_smtplog


	Log of SMTP (for debug).

	$SUMMARY_FILE 	 	$DIR/summary	


	summary of ML

	$SEQUENCE_FILE 	 	$DIR/seq


	ML's sequence number

	$MSEND_RC		$VARLOG_DIR/msendrc


	digest control file.

	$LOCK_FILE	 	$VARRUN_DIR/lockfile.v7


	lock file when not flock(2) lock but link(2) based.

	$LOG_MESSAGE_ID		$VARRUN_DIR/msgidcache


	Message-Id cache file to prevent loops.

	$MESSAGE_ID_CACHE_BUFSIZE


	Message-ID cache file size

	$INDEX_FILE		$DIR/index


	Fml.pl works without this file. If exists, "index" commands
	sends back this file. If not, FML scans $SPOOL_DIR,
	@ARCHIVE_DIR and sends back the summary.

7.8	Other useful variables

	$DO_NOTHING


	Special flag to declare "do nothing".

	$NULL


	dummy:D like "#define null (char *)0".

	$FML	


	process table name

	$FACE_MARK

	e.g. 	P(^^)
		Be seeing you P(^^)


	appended in the reply message, e.g. command results.

	$INCLUDE_SIM_PATH


	Please ignore this. This is used in simulation.

	$UNISTD

	Declare "Unix Standard" flag. undefined on Windows NT4

	$LOCKFILE

	lock file variable in some libraries. It may be uncontrolled
	by a user.

	%MAKE_FML


Please not touch %MAKE_FML in config.ph which variable "makefml" uses
though it is not used today.


* obsolete variables (renamed to)

   $GUIDE_REQUEST	-> $GuideRequest
   $RPG_ML_FORM_FLAG	-> $COMMAND_SYNTAX_EXTENSION


* obsolete

   $NON_PORTABILITY

7.9	Listing variables list


To dump variable used in fml.pl (by dumpvar.pl), sets 

	$DUMPVAR = 1;


FYI: fmlserv.pl uses the same technique to switch name spaces.


[PREVIOUS CHAPTER] [NEXT CHAPTER]